Phase Handover — 12.1 Digital Menu Catalog
Metadata
| Field |
Value |
| Phase ID |
hospitality-12.1 |
| Title |
Digital Menu Catalog |
| Status |
Complete |
| Service(s) |
hospitality |
| Version |
0.12.1.0 |
| Date |
2026-07-25 |
| ADR(s) |
ADR-017 (no new ADR — catalog depth within Hospitality boundary) |
Summary
Phase 12.1 deepened the Torbat Food digital menu catalog on hospitality-service / hospitality_db (port 8009, version 0.12.1.0). Additive migration 0002_phase_121_digital_menu_catalog added catalog tables and MenuItem enrichment fields. No POS / kitchen / QR ordering / reservation engines.
What Changed
| Area |
Change |
| Models |
app/models/catalog.py + MenuItem additive columns |
| Migration |
Alembic 0002_phase_121_digital_menu_catalog |
| APIs |
Allergens, modifiers, availability, media refs, localizations |
| Events / Permissions |
Catalog hospitality.* types and trees |
| Capabilities |
phase: 12.1, digital_menu_catalog: true |
| Tests |
test_catalog.py + updated architecture/migration/docs/API |
Public APIs
| Method |
Path |
Notes |
| POST/GET |
/api/v1/allergens |
Venue-scoped allergen catalog |
| POST/GET |
/api/v1/modifier-groups |
Selection rules only |
| POST/GET |
/api/v1/modifier-options |
Price deltas |
| POST |
/api/v1/menu-item-modifiers/link |
Link item → group |
| POST |
/api/v1/menu-item-allergens/link |
Link item → allergen |
| POST/GET |
/api/v1/availability-windows |
Time windows by scope |
| POST/GET |
/api/v1/menu-media-refs |
Storage file_ref only |
| POST |
/api/v1/menu-localizations/upsert |
Multi-language shells |
Plus existing 12.0 foundation surfaces unchanged (additive MenuItem fields).
Events
| Event type |
Aggregate |
hospitality.allergen.created |
allergen |
hospitality.modifier_group.created |
modifier_group |
hospitality.modifier_option.created |
modifier_option |
hospitality.menu_item_modifier.linked |
menu_item_modifier |
hospitality.menu_item_allergen.linked |
menu_item_allergen |
hospitality.availability_window.created |
availability_window |
hospitality.menu_media_ref.created |
menu_media_ref |
hospitality.menu_localization.upserted |
menu_localization |
Extension Points
| Extension point |
How to extend |
Forbidden uses |
Media file_ref |
Resolve via Storage API/Events |
Do not store blobs in hospitality_db |
| Availability windows |
Consume in QR Menu / Ordering later |
Do not embed ordering engine here |
| Modifier selection rules |
Drive cart/POS later |
Do not implement cart/checkout in 12.1 |
Known Limitations
- No QR Menu public rendering or ordering cart
- No kitchen ticket mapping from modifiers
- Media is reference-only (no binary upload API in Hospitality)
- Bundle gating of catalog APIs not enforced at middleware yet (permission keys registered)
Migration Notes
| Item |
Detail |
| Alembic revision(s) |
0002_phase_121_digital_menu_catalog (down_revision 0001_initial) |
| Upgrade steps |
Run alembic upgrade head on hospitality_db |
| Downgrade support |
Drops catalog tables; removes additive MenuItem columns |
| Data backfill |
N/A (new nullable / defaulted columns) |
| Breaking changes |
None — additive only |
Quality Gates
| Gate |
Result |
| Architecture |
Pass |
| Dependency |
Pass |
| Backward Compatibility |
Pass (additive) |
| Health / Capability |
Pass |
| Permission |
Pass |
| API |
Pass |
| Repository / Service |
Pass |
| Migration |
Pass |
| Tenant Isolation |
Pass |
| Security |
Pass |
| Performance |
Pass |
| Documentation |
Pass |
| Integration (contracts only) |
Pass |
| Self Audit |
Pass |
Next Phase Entry
- This handover + hospitality-phase-12-1.md
- Updated module registry / manifests (version
0.12.1.0)
- Phase 12.2 — QR Menu & QR Ordering (do not skip; no POS yet)
Related Documents
5c6a2e78cf