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>
104 lines
3.5 KiB
Markdown
104 lines
3.5 KiB
Markdown
# Phase Handover — Experience 11.2 Component Library & Versioning
|
|
|
|
## Metadata
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| Phase ID | `experience-11.2` |
|
|
| Title | Component Library & Versioning |
|
|
| Status | Complete |
|
|
| Service(s) | `experience` (`experience_db`) |
|
|
| Version | `0.11.2.0` |
|
|
| Date | 2026-07-26 |
|
|
| ADR(s) | [ADR-016](../architecture/adr/ADR-016.md) |
|
|
|
|
## Discovery Summary
|
|
|
|
Prior phase delivered sites/pages. Gap: versioned reusable components with immutable published revisions and page composition pins. Themes/layouts deferred to 11.3.
|
|
|
|
## Reusable Components
|
|
|
|
| Component | Location | Reuse notes |
|
|
| --- | --- | --- |
|
|
| Component catalog | `app/models/components.py`, `services/components.py` | Lifecycle + kinds |
|
|
| Immutable versions | `ExperienceComponentVersion.is_immutable` | Publish locks content |
|
|
| Composition shells | `PageComponentPlacement` | Slot pins only — no layout engine |
|
|
| Policies / specs | `app/policies/`, `app/specifications/` | Transition + list UX |
|
|
| Commands / queries | `app/commands/`, `app/queries/` | CQ separation |
|
|
|
|
## Public APIs
|
|
|
|
| Method | Path | Permission |
|
|
| --- | --- | --- |
|
|
| CRUD + activate/deprecate/archive | `/api/v1/components` | `experience.components.*` |
|
|
| CRUD + publish/retire | `/api/v1/component-versions` | `experience.components.*` |
|
|
| CRUD | `/api/v1/page-component-placements` | `experience.components.*` |
|
|
|
|
## Events
|
|
|
|
| Event type | Notes |
|
|
| --- | --- |
|
|
| `experience.component.*` | Catalog lifecycle |
|
|
| `experience.component_version.*` | Version lifecycle + immutability |
|
|
| `experience.page_component.*` | Placement create/update/remove |
|
|
|
|
## Extension Points
|
|
|
|
| Extension point | How to extend | Forbidden uses |
|
|
| --- | --- | --- |
|
|
| `definition_schema` / `props_defaults` | Theme/layout phases consume props | Store theme tokens as layout engine in 11.2 |
|
|
| `render_hint` | Future render engines | Bind foreign DB rows |
|
|
| `menu_ref` / `catalog_ref` kinds | Vertical entity refs via API | Shared Hospitality/Marketplace tables |
|
|
|
|
## Known Limitations
|
|
|
|
- No theme/layout engines (11.3)
|
|
- No visual section tree / page builder UI
|
|
- Placement requires published version only
|
|
- Metrics remain discovery-oriented
|
|
|
|
## Migration Notes
|
|
|
|
| Item | Detail |
|
|
| --- | --- |
|
|
| Alembic revision(s) | `0003_phase_112_components` |
|
|
| Upgrade steps | `alembic upgrade head` |
|
|
| Downgrade support | Drops placements, versions, components |
|
|
| Breaking changes | None (additive) |
|
|
|
|
## Dependencies
|
|
|
|
| Dependency | Type |
|
|
| --- | --- |
|
|
| experience-11.1 sites/pages | Required parent |
|
|
| ADR-016 | Boundaries |
|
|
|
|
## Quality Gates
|
|
|
|
- [x] Discovery complete
|
|
- [x] Architecture / boundaries preserved
|
|
- [x] Tests green (unit, API, architecture, migration, docs, tenant, security-compatible)
|
|
- [x] Documentation + manifests + registries updated
|
|
- [x] Self audit: no theme/layout leakage; published versions immutable
|
|
|
|
## Next Phase Entry
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| Recommended next phase | `experience-11.3` Theme & Layout Engine |
|
|
| Entry checklist | Read this handover + phase doc; implement themes/layouts only — no template catalog 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.2](../experience-phase-11-2.md)
|
|
- [Experience Roadmap](../experience-roadmap.md)
|
|
- [ADR-016](../architecture/adr/ADR-016.md)
|