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>
110 lines
4.0 KiB
Markdown
110 lines
4.0 KiB
Markdown
# Phase: Experience Component Library & Versioning (11.2)
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| Identifier | `experience-11.2` |
|
|
| Status | Complete |
|
|
| Owner | Platform |
|
|
| Module(s) | Components, Component Versions, Page Component Placements |
|
|
| Service(s) | `experience` (Torbat Pages) |
|
|
| Depends On | `experience-11.1` |
|
|
| ADR(s) | [ADR-016](architecture/adr/ADR-016.md) |
|
|
| Manifest | [phase-manifest.yaml](ai-framework/phase-manifest.yaml) |
|
|
|
|
## Enterprise Phase Discovery Record
|
|
|
|
| Input | Finding |
|
|
| --- | --- |
|
|
| Roadmap / manifest | Next unfinished Experience phase = `experience-11.2` Component Library & Versioning |
|
|
| Prior handover | [phase-11-1.md](phase-handover/phase-11-1.md) — versioned components only; no theme/layout |
|
|
| Boundaries | Experience owns components; no CRM/Hospitality/Marketplace/Storage ownership |
|
|
| Existing codebase | Sites/pages complete; `commands/`/`policies/`/`queries/`/`specifications/` were empty shells |
|
|
| Missing vs DoD | Immutable versions, composition shells, list filter/sort/search, policies, specs, commands/queries |
|
|
|
|
Derived capabilities (this phase only): component catalog lifecycle, immutable published versions, page↔version placement pins, permissions/events/audit/tenant isolation. **Not** themes, layouts, templates, SEO, forms.
|
|
|
|
## Objective
|
|
|
|
Deliver a production-ready versioned component library on `experience_db` with immutable published revisions and composition shells that pin versions onto pages — without theme/layout engines.
|
|
|
|
## Scope
|
|
|
|
### In Scope
|
|
|
|
- `ExperienceComponent` catalog (kinds, status, category, tags)
|
|
- `ExperienceComponentVersion` with draft → published (immutable) → retired
|
|
- `PageComponentPlacement` composition shells (slot_key, sort_order, props_override)
|
|
- Policies, specifications, commands, queries
|
|
- Pagination, filtering, sorting, searching on list APIs
|
|
- Permissions `experience.components.*`; events `experience.component*` / `experience.page_component.*`
|
|
- Alembic `0003_phase_112_components`; version `0.11.2.0`
|
|
- Seed catalog: `component_kinds` via `/capabilities`
|
|
|
|
### Out of Scope
|
|
|
|
- Theme / layout engines — Phase 11.3
|
|
- Template catalog — Phase 11.4
|
|
- Visual page builder UI / section trees
|
|
- Forms, SEO, PWA, analytics, AI content
|
|
|
|
### Models
|
|
|
|
| Entity | Soft delete | Audit | Tenant | Optimistic lock |
|
|
| --- | --- | --- | --- | --- |
|
|
| ExperienceComponent | Yes | Yes | Yes | Yes |
|
|
| ExperienceComponentVersion | Yes | Yes | Yes | Yes |
|
|
| PageComponentPlacement | Yes | Yes | Yes | Yes |
|
|
|
|
### Permissions
|
|
|
|
`experience.components.view|create|update|delete|manage`
|
|
|
|
### Events
|
|
|
|
`experience.component.created|updated|activated|deprecated|archived`
|
|
|
|
`experience.component_version.created|updated|published|retired`
|
|
|
|
`experience.page_component.placed|updated|removed`
|
|
|
|
### APIs
|
|
|
|
| Method | Path |
|
|
| --- | --- |
|
|
| * | `/api/v1/components` (+ activate/deprecate/archive/delete) |
|
|
| * | `/api/v1/component-versions` (+ publish/retire) |
|
|
| * | `/api/v1/page-component-placements` (+ delete) |
|
|
|
|
List endpoints support `page`/`page_size`, filters, `q`, `sort_by`/`sort_dir`.
|
|
|
|
### 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 — no async work in phase boundary |
|
|
| Themes/layouts | Explicitly out of scope |
|
|
|
|
### Tests
|
|
|
|
- [x] Unit policies
|
|
- [x] API component/version/placement flow + immutability
|
|
- [x] Tenant isolation + optimistic lock
|
|
- [x] Architecture / permission / migration / docs
|
|
|
|
## Completion Criteria
|
|
|
|
- [x] Component library with immutable versions; tenant isolation tests green
|
|
- [x] No theme/layout engine
|
|
- [x] Docs / manifests / handover updated
|
|
|
|
## Related Documents
|
|
|
|
- [Handover](phase-handover/phase-11-2.md)
|
|
- [Phase 11.1](experience-phase-11-1.md)
|
|
- [Experience Roadmap](experience-roadmap.md)
|
|
- [ADR-016](architecture/adr/ADR-016.md)
|