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>
111 lines
5.1 KiB
Markdown
111 lines
5.1 KiB
Markdown
# Phase: Experience Template System (11.4)
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| Identifier | `experience-11.4` |
|
|
| Status | Complete |
|
|
| Owner | Platform |
|
|
| Module(s) | Templates, Template Versions, Template Instantiations |
|
|
| Service(s) | `experience` (Torbat Pages) |
|
|
| Depends On | `experience-11.3` |
|
|
| ADR(s) | [ADR-016](architecture/adr/ADR-016.md), [ADR-008](architecture/adr/ADR-008.md) |
|
|
| Manifest | [phase-manifest.yaml](ai-framework/phase-manifest.yaml) |
|
|
|
|
## Enterprise Phase Discovery Record
|
|
|
|
| Input | Finding |
|
|
| --- | --- |
|
|
| Roadmap / manifest | Next unfinished Experience phase = `experience-11.4` Template System |
|
|
| Prior handover | [phase-11-3.md](phase-handover/phase-11-3.md) — themes/layouts complete; no template catalog |
|
|
| Boundaries | Experience owns the template catalog; templates compose existing themes/layouts/components by reference only; no Core DB access |
|
|
| Existing codebase | Template scaffolding (models/services/schemas/repositories/commands/queries/policies/validators/specifications/APIs, and a `.future`-suffixed Alembic revision) already existed on disk but was intentionally unwired at the end of the Phase 11.3 repair |
|
|
| Missing vs DoD | Alembic head still pinned to `0004`; `app.models.templates` not imported; template routers not mounted; capability flags still `False`; no phase test suite |
|
|
|
|
Derived capabilities: a tenant catalog of reusable page-type templates; immutable published template versions carrying a `blueprint_json` shell; one-click instantiation of a published template version into a new page (optionally wiring an existing active theme/layout by reference and seeding component placement shells). **Not** forms, surveys, locales, media pipelines, or SEO — those remain Phase 11.5+.
|
|
|
|
## Objective
|
|
|
|
Re-wire and validate the existing Phase 11.4 Template System scaffolding on `experience_db` so tenants can define a template catalog, publish immutable template versions, and instantiate a published version into a concrete page — reusing the Phase 11.1 sites/pages resources and the Phase 11.3 theme/layout catalogs by reference only.
|
|
|
|
## Scope
|
|
|
|
### In Scope
|
|
|
|
- `ExperienceTemplate` (catalog: code, name, description, page_type, category, tags, starter-pack flag, status, latest/published version pointers)
|
|
- `ExperienceTemplateVersion` (immutable once published: `blueprint_json`, changelog)
|
|
- `TemplateInstantiation` (audit trail: template + version + site → created page, result/error payload)
|
|
- Policies, specifications, commands, queries
|
|
- Pagination / filter / sort / search on list APIs
|
|
- Permissions `experience.templates.*` (full `view|create|update|delete|manage` CRUD tree)
|
|
- Events `experience.template.*` / `experience.template_version.*` / `experience.template.instantiated`
|
|
- Alembic `0005_phase_114_templates` (head); version `0.11.4.0`
|
|
- `/capabilities` flags: `templates`, `template_versions`, `template_instantiation`
|
|
|
|
### Out of Scope
|
|
|
|
- Forms / surveys / appointment page shells — Phase 11.6
|
|
- Full localization + media reference pipeline — Phase 11.5
|
|
- SEO metadata / sitemap / PWA — Phase 11.7
|
|
- Owning the theme/layout/component engines themselves (Experience only *references* published theme/layout versions and component codes from a template's blueprint)
|
|
|
|
### Models
|
|
|
|
| Entity | Soft delete | Audit | Tenant | Optimistic lock |
|
|
| --- | --- | --- | --- | --- |
|
|
| ExperienceTemplate | Yes | Yes | Yes | Yes |
|
|
| ExperienceTemplateVersion | Yes | Yes | Yes | Yes |
|
|
| TemplateInstantiation | Yes | Yes | Yes | Yes |
|
|
|
|
### Permissions
|
|
|
|
`experience.templates.view|create|update|delete|manage`
|
|
|
|
### Events
|
|
|
|
`experience.template.created|updated|activated|deprecated|archived`
|
|
|
|
`experience.template_version.created|updated|published|retired`
|
|
|
|
`experience.template.instantiated`
|
|
|
|
### APIs
|
|
|
|
| Method | Path |
|
|
| --- | --- |
|
|
| * | `/api/v1/templates` (+ activate/deprecate/archive/delete) |
|
|
| * | `/api/v1/template-versions` (+ publish/retire) |
|
|
| * | `/api/v1/template-instantiations` (instantiate + list + get) |
|
|
|
|
### Artifact coverage (DoD)
|
|
|
|
| Artifact | Status |
|
|
| --- | --- |
|
|
| Discovery | This record |
|
|
| Policies / Specs / Commands / Queries | Implemented |
|
|
| Soft delete / Optimistic lock / Audit / Tenant | Yes |
|
|
| Pagination / Filter / Sort / Search | Yes |
|
|
| Background jobs | N/A — instantiation runs synchronously within the request |
|
|
| Forms / Surveys | Explicitly out of scope |
|
|
|
|
### Tests
|
|
|
|
- [x] Health / capabilities reflect phase 11.4
|
|
- [x] Full lifecycle: create template → create version → publish (auto-activates template) → explicit activate → instantiate (creates page) → list/get instantiations
|
|
- [x] Tenant isolation
|
|
- [x] Immutable published version update blocked (409) and re-publish blocked (409)
|
|
- [x] Architecture / permission / migration / docs
|
|
|
|
## Completion Criteria
|
|
|
|
- [x] Template APIs + validators + tests green
|
|
- [x] No forms/surveys engine
|
|
- [x] Docs / manifests / handover updated
|
|
|
|
## Related Documents
|
|
|
|
- [Handover](phase-handover/phase-11-4.md)
|
|
- [Phase 11.3](experience-phase-11-3.md)
|
|
- [Experience Roadmap](experience-roadmap.md)
|
|
- [ADR-016](architecture/adr/ADR-016.md)
|
|
- [ADR-008](architecture/adr/ADR-008.md)
|