203671a7bf
Add the experience service with sites through analytics/AI hooks, migrations through 0011, and phase docs/manifests marking the track complete. Co-authored-by: Cursor <cursoragent@cursor.com>
95 lines
4.2 KiB
Markdown
95 lines
4.2 KiB
Markdown
# Phase Handover — Experience 11.5 Localization, RTL/LTR & Media
|
|
|
|
## Metadata
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| Phase ID | `experience-11.5` |
|
|
| Title | Localization, RTL/LTR & Media |
|
|
| Status | Complete |
|
|
| Service(s) | `experience` (`experience_db`) |
|
|
| Version | `0.11.5.0` |
|
|
| Date | 2026-07-26 |
|
|
| ADR(s) | [ADR-016](../architecture/adr/ADR-016.md), [ADR-008](../architecture/adr/ADR-008.md) |
|
|
|
|
## Discovery Summary
|
|
|
|
Phase 11.4 delivered the template catalog/instantiation pipeline. Foundation locale profiles (11.0) already described language + direction catalogs, and themes expose `DirectionMode` shells, but tenants could not bind locales to sites, store multi-locale content shells, or attach media without risking binaries in `experience_db`. This phase adds site locale bindings, localization upserts with first-class RTL/LTR, and media refs that store Storage file references only.
|
|
|
|
## Reusable Components
|
|
|
|
| Component | Location | Reuse notes |
|
|
| --- | --- | --- |
|
|
| Site locale binding | `app/models/localization.py` (`SiteLocaleBinding`), `app/services/localization.py` | One default locale per site; direction inherited from profile or overridden |
|
|
| Localization shells | `ExperienceLocalization` | Unique per tenant/target/locale; upsert API |
|
|
| Media refs | `ExperienceMediaRef` | `storage_file_ref` only; validators reject `data:` / base64 metadata keys |
|
|
| Policies / specs | `app/policies/localization.py`, `app/specifications/localization.py` | Profile usability, status transitions, list UX |
|
|
| Validators | `app/validators/localization.py` | Locale code, text direction, storage ref, no-binary payload |
|
|
|
|
## Public APIs
|
|
|
|
| Method | Path | Permission |
|
|
| --- | --- | --- |
|
|
| CRUD | `/api/v1/site-locale-bindings` | `experience.locales.*` |
|
|
| Upsert + CRUD | `/api/v1/localizations` | `experience.locales.*` |
|
|
| CRUD | `/api/v1/media-refs` | `experience.media_refs.*` |
|
|
|
|
## Events
|
|
|
|
| Event type | Notes |
|
|
| --- | --- |
|
|
| `experience.site_locale.*` | assigned / updated / replaced / unassigned |
|
|
| `experience.localization.*` | upserted / updated / archived |
|
|
| `experience.media_ref.*` | created / updated / archived |
|
|
|
|
## Extension Points
|
|
|
|
| Extension point | How to extend | Forbidden uses |
|
|
| --- | --- | --- |
|
|
| `ExperienceLocalization.content_json` | Locale-specific content shells for renderers | Store binary media or form submission payloads |
|
|
| `ExperienceMediaRef.storage_file_ref` | Point at File Storage objects | Inline blobs, data-URIs, base64 in metadata |
|
|
| `SiteLocaleBinding.text_direction` | Concrete rtl/ltr for site rendering | Do not invent a second locale catalog — reuse locale profiles |
|
|
|
|
## Known Limitations
|
|
|
|
- No forms/surveys/appointment engine (11.6)
|
|
- No SEO/PWA publishing pipeline (11.7)
|
|
- Media refs do not call StorageProvider at write time (ref validation only); resolve-on-read remains a later integration concern
|
|
- Localization targets are shells — deep CMS field graphs remain out of scope
|
|
|
|
## Migration Notes
|
|
|
|
| Item | Detail |
|
|
| --- | --- |
|
|
| Alembic revision(s) | `0006_phase_115_localization_media` (head) |
|
|
| Upgrade steps | `alembic upgrade head` |
|
|
| Downgrade support | Drops `experience_media_refs`, `experience_localizations`, `experience_site_locale_bindings` |
|
|
| Breaking changes | None (additive) |
|
|
|
|
## Dependencies
|
|
|
|
| Dependency | Type |
|
|
| --- | --- |
|
|
| experience-11.4 templates | Required prior (manifest chain) |
|
|
| experience-11.1 sites/pages | Required (bindings/localizations attach to sites/pages) |
|
|
| experience-11.0 locale profiles | Required (site bindings reference profiles) |
|
|
| File Storage (API contract) | External — media binaries never in `experience_db` |
|
|
| ADR-016 | Boundaries |
|
|
|
|
## Quality Gates
|
|
|
|
- [x] Discovery complete
|
|
- [x] Architecture / boundaries preserved
|
|
- [x] Tests green
|
|
- [x] Permissions / events registered
|
|
- [x] Docs + manifests + next-steps updated
|
|
- [x] Phase handover written
|
|
|
|
## Next Phase Entry
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| Next phase | `experience-11.6` — Forms, Surveys & Appointments |
|
|
| Entry docs | This handover + [experience-phase-11-5.md](../experience-phase-11-5.md) |
|
|
| Do not start | Forms before localization/media DoD is green (this phase) |
|