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>
105 lines
5.1 KiB
Markdown
105 lines
5.1 KiB
Markdown
# Phase Handover — Experience 11.4 Template System
|
|
|
|
## Metadata
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| Phase ID | `experience-11.4` |
|
|
| Title | Template System |
|
|
| Status | Complete |
|
|
| Service(s) | `experience` (`experience_db`) |
|
|
| Version | `0.11.4.0` |
|
|
| Date | 2026-07-26 |
|
|
| ADR(s) | [ADR-016](../architecture/adr/ADR-016.md), [ADR-008](../architecture/adr/ADR-008.md) |
|
|
|
|
## Discovery Summary
|
|
|
|
Prior phase delivered replaceable themes and dynamic layouts. The Phase 11.4 template scaffolding (models, services, schemas, repositories, commands/queries, policies/validators/specifications, and APIs) already existed on disk from earlier work but was intentionally unwired — models excluded from `app/models/__init__.py`, routers unmounted, and the Alembic revision suffixed `.py.future` — as part of the Phase 11.3 repair so the Alembic head stayed pinned to `0004`. This phase re-wired that scaffolding: restored the migration, imported the models, mounted the routers, aligned events/permissions/capabilities, and added the phase 11.4 test suite.
|
|
|
|
## Reusable Components
|
|
|
|
| Component | Location | Reuse notes |
|
|
| --- | --- | --- |
|
|
| Template catalog + versions | `app/models/templates.py` (`ExperienceTemplate`, `ExperienceTemplateVersion`), `app/services/templates.py` | `blueprint_json` immutable once published; mirrors the Phase 11.2/11.3 catalog+immutable-version pattern |
|
|
| Instantiation | `TemplateInstantiation`, `ExperienceTemplateService.instantiate` | Creates an `ExperiencePage` from a published version's blueprint; records theme/layout readiness without owning those engines |
|
|
| Policies / specs | `app/policies/templates.py`, `app/specifications/templates.py` | Lifecycle + version-immutability + instantiation-eligibility rules, list UX |
|
|
| Validators | `app/validators/templates.py` | `page_type` validation, status-transition tables, `blueprint_json` shape checks |
|
|
|
|
## Public APIs
|
|
|
|
| Method | Path | Permission |
|
|
| --- | --- | --- |
|
|
| CRUD + activate/deprecate/archive/delete | `/api/v1/templates` | `experience.templates.*` |
|
|
| CRUD + publish/retire | `/api/v1/template-versions` | `experience.templates.*` |
|
|
| Instantiate / list / get | `/api/v1/template-instantiations` | `experience.templates.*` |
|
|
|
|
## Events
|
|
|
|
| Event type | Notes |
|
|
| --- | --- |
|
|
| `experience.template.*` | Template catalog lifecycle (created/updated/activated/deprecated/archived) |
|
|
| `experience.template_version.*` | Template version created/updated/published/retired |
|
|
| `experience.template.instantiated` | Emitted after a page is successfully created from a published version |
|
|
|
|
## Extension Points
|
|
|
|
| Extension point | How to extend | Forbidden uses |
|
|
| --- | --- | --- |
|
|
| `ExperienceTemplateVersion.blueprint_json` | `page_type`, `content_shell`, `seo_shell`, `theme_id`, `layout_id`, `placement_shells` — consumed at instantiation time | Store full CMS blobs / binary media |
|
|
| `TemplateInstantiation.result_json` | Records whether the referenced theme/layout were ready and applied | Do not use as a source of truth for theme/layout state — always re-read the theme/layout catalogs |
|
|
| `TemplateInstantiationPolicy` / `TemplateVersionPolicy` | Gate instantiation to published, non-deleted templates/versions | Do not bypass via direct repository writes |
|
|
|
|
## Known Limitations
|
|
|
|
- No forms/surveys/appointment engine (11.6)
|
|
- No localization/media-ref pipeline for template content yet (11.5)
|
|
- Instantiation only *references* theme/layout by id; it does not validate deep compatibility beyond active/published status
|
|
- Metrics remain discovery-oriented
|
|
|
|
## Migration Notes
|
|
|
|
| Item | Detail |
|
|
| --- | --- |
|
|
| Alembic revision(s) | `0005_phase_114_templates` (head) |
|
|
| Upgrade steps | `alembic upgrade head` |
|
|
| Downgrade support | Drops `experience_template_instantiations`, `experience_template_versions`, `experience_templates` |
|
|
| Breaking changes | None (additive) |
|
|
|
|
## Dependencies
|
|
|
|
| Dependency | Type |
|
|
| --- | --- |
|
|
| experience-11.3 themes/layouts | Required prior (referenced by id from template blueprints) |
|
|
| experience-11.1 sites/pages | Required prior (instantiation creates an `ExperiencePage`) |
|
|
| ADR-016 / ADR-008 | Boundaries / branding |
|
|
|
|
## Quality Gates
|
|
|
|
- [x] Discovery complete
|
|
- [x] Architecture / boundaries preserved
|
|
- [x] Tests green
|
|
- [x] Documentation + manifests + registries updated
|
|
- [x] Self audit: no forms/surveys/CMS leakage; template versions immutable once published
|
|
|
|
## Next Phase Entry
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| Recommended next phase | `experience-11.5` Localization, RTL/LTR & Media |
|
|
| Entry checklist | Read this handover + phase doc; implement locale profiles content/media refs only — no forms/surveys/appointments yet |
|
|
|
|
## Completion Sign-Off
|
|
|
|
- [x] Quality gates passed
|
|
- [x] Tests green
|
|
- [x] Documentation updated
|
|
- [x] Progress / next-steps / registries updated
|
|
- [x] Self audit completed
|
|
|
|
## Related Documents
|
|
|
|
- [Experience Phase 11.4](../experience-phase-11-4.md)
|
|
- [Experience Roadmap](../experience-roadmap.md)
|
|
- [ADR-016](../architecture/adr/ADR-016.md)
|
|
- [ADR-008](../architecture/adr/ADR-008.md)
|