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>
5.1 KiB
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, ADR-008 |
| Manifest | 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 — 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.*(fullview|create|update|delete|manageCRUD tree) - Events
experience.template.*/experience.template_version.*/experience.template.instantiated - Alembic
0005_phase_114_templates(head); version0.11.4.0 /capabilitiesflags: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
- Health / capabilities reflect phase 11.4
- Full lifecycle: create template → create version → publish (auto-activates template) → explicit activate → instantiate (creates page) → list/get instantiations
- Tenant isolation
- Immutable published version update blocked (409) and re-publish blocked (409)
- Architecture / permission / migration / docs
Completion Criteria
- Template APIs + validators + tests green
- No forms/surveys engine
- Docs / manifests / handover updated