Menu Management Phase 3

Phase 3 adds tenant-local menu management for paid restaurants: nested categories, items, variants, reusable modifiers, combos, branch pricing, service-mode availability, station routing, and optional AI descriptions. It remains setup-only and does not create POS orders, KDS tickets, QR ordering, inventory deduction, reservations, or reports.

Access

Menu screens are available only after tenant login and an active paid subscription. Use /r/{tenant}/menu for the command center and /r/{tenant}/menu/studio for the Pro Studio. Subscription-blocked tenants are redirected before menu routes are reached.

Data Model

• menu_categories stores nested categories, images, colors, icons, default station routing, status, sort order, and metadata.
• menu_items stores SKU, rich descriptions, base price, prep time, calories, spice level, dietary flags, allergens, tags, image, tax, featured, combo, and status fields.
• item_variants stores variant names, optional SKU and price overrides, default flag, status, sort order, and metadata.
• modifier_groups and modifiers provide reusable required/optional modifier and add-on rules.
• combo_items attaches child items or variants to combo parent items with quantity, included quantity, price adjustment, and routing metadata.
• branch_menu_prices stores branch item/variant price overrides, availability status, service modes, schedules, and visibility.
• ai_usage_logs records provider, model, prompt hash, item, credit cost, status, response metadata, and error details.

Variant-Led Pricing

Price resolution is intentionally variant-led. The order is branch variant override, branch item override, variant price, then item base price. Branch pricing also controls service-mode visibility for dine-in, takeaway, delivery, and QR.

Pro Studio

The Studio view shows a category rail, searchable item cards, animated hover states, branch and service-mode filters, price-source badges, station badges, availability badges, and quick actions for item edit, preview, and pricing. Item cards can be drag-sorted and saved through the menu reorder endpoint.

Modifiers And Combos

Add-ons are implemented as modifier groups with type=add_on; no separate add-on table is used. Modifier groups can attach to categories for inheritance or directly to items. Combo rows keep child item, optional variant, quantity, included quantity, adjustment, and routing metadata ready for future POS phases.

Station Routing

Station routing uses item override first, then category default, then unassigned. The command center shows station coverage so menu teams can find uncategorized or unrouted items before POS/KDS phases.

AI Descriptions

AI menu descriptions are disabled by default. Enable the global provider in config/menu_ai.php or env variables, then enable tenant behavior through the menu_ai.enabled tenant setting. Provider keys stay in env/config, not tenant plaintext settings. HTTP provider calls are tested with fakes.

• Supported adapter shapes: OpenAI-style chat completions, Anthropic-style messages, and Gemini-style generate content.
• AI usage consumes the SaaS ai_credits plan feature.
• Failures are logged in ai_usage_logs with status and error message.

UI Conventions

All Phase 3 screens use shared Blade components, x-ui.page-header, shared table markup, tenant CSS assets, and the existing confirm Swal, loading Swal, then appToast result pattern for mutating actions.

Phase 3+ Operations Studio

Phase 3+ deepens menu management into a full operations workflow while staying setup-only. Published menu tables remain the active source, but bulk changes, imports, and staged edits move through revisions before publishing.

• /r/{tenant}/menu/operations opens the operations command center for drafts, QA, imports, exports, media, AI, and publish batches.
• /r/{tenant}/menu/studio/pro opens the graphical Pro Studio with item cards, bulk staging, inspector, pricing matrix, media panel, QA panel, and revision timeline.
• Revision flow is draft, pending review, approved, published, with reject and rollback support.
• CSV, XLSX, and JSON imports validate first, then create draft revisions; they never mutate the published catalog immediately.
• JSON exports preserve nested catalog data, while CSV/XLSX exports support restaurant admin spreadsheet workflows.
• Menu QA checks copy, images, branch pricing, station routing, dietary/allergen metadata, modifier rules, variants, duplicate identifiers, and combo self-reference issues.
• AI batches use the same provider controls and credit accounting as single-item generation.

Draft Review Publish

Operations changes are staged through menu_revisions. A revision can be created by a bulk action, import commit, or future editor workflow. It does not touch the published menu until it is submitted, approved, added to a publish batch, and published.

• Draft: editable staged payload owned by the current tenant.
• Pending review: submitted for a manager or owner to approve or reject.
• Approved: eligible for a publish batch.
• Published: applied to the active menu tables and recorded with before/after payloads for rollback.
• Rollback: restores previous values for updated records and removes newly created records when safe.

Imports And Exports

Imports support CSV, XLSX, and JSON. CSV and XLSX are designed for restaurant admin spreadsheets; JSON preserves exact nested catalog structure for migration, backups, and developer-grade round trips.

• /r/{tenant}/menu/imports creates import jobs from upload or pasted text.
• /r/{tenant}/menu/imports/{import}/validate checks required names, duplicate row identifiers, and file shape before commit.
• /r/{tenant}/menu/imports/{import}/commit creates draft revisions only. Approval and publish are still required.
• /r/{tenant}/menu/exports creates JSON, CSV, or XLSX export jobs from the current published catalog.
• JSON exports include categories, items, variants, modifier groups, modifiers, combo rows, branch pricing, and routing metadata.

Bulk Operations

The Pro Studio bulk toolbar stages mass edits without immediately changing the live menu. Supported item actions include status changes, archive/restore, featured/taxable flags, category or station reassignment, tag replacement, price adjustments, and duplication.

Every bulk operation follows the shared UI flow: confirm Swal yes/no, loading Swal, then appToast result notification. Permission checks, tenant isolation, active subscription gating, SKU/slug handling, and plan-sensitive behavior are enforced server-side.

Quality, Media, And AI

/r/{tenant}/menu/quality runs setup-only menu QA and stores findings in menu_quality_checks. Use this before publishing a large import or bulk edit.

• QA detects missing descriptions, missing images, unrouted items, branch visibility gaps, invalid modifier min/max rules, dietary/allergen gaps, hidden active variants, duplicate SKUs/slugs, and combo self-reference risks.
• /r/{tenant}/menu/media stores menu image assets in local public storage with library metadata for future customer menu surfaces.
• /r/{tenant}/menu/ai/batches generates descriptions in bulk through the configured provider and logs batch results in menu_ai_batches.
• AI provider keys remain env/config-only. Tenant settings control whether AI is enabled and which provider/model behavior is allowed.

Recommended Workflow

1. Open /r/{tenant}/menu/operations and review catalog health, QA warnings, drafts, and publish status.
2. Use /r/{tenant}/menu/studio/pro for visual item review, bulk staging, media checks, and branch pricing inspection.
3. Import CSV, XLSX, or JSON if needed, then validate and commit to draft revisions.
4. Submit revisions for review, approve the valid ones, create a publish batch, and publish.
5. Run QA again after publishing. Use rollback only when a published batch needs to be reverted.

Verification

php artisan test
php artisan route:list --path='r/'
npm run build