# Requirements

## Status Note

These draft requirements combine current-state operating gaps with implemented and planned prototype behavior. Stakeholder approval remains outstanding.

## Business Requirements

| ID | Requirement | Status | Evidence Quality | Evidence |
| --- | --- | --- | --- | --- |
| BREQ-001 | The system shall support a staged commercial-kitchen operating loop from recipe identity through menu planning, forecasting, production recording, and inventory. | Implemented MVP | Observed | `README.md`, `AGENT.md` |
| BREQ-002 | The system shall preserve Recipe Collection item identity as culinary identity reused by downstream workflows. | Implemented MVP | Observed | `docs/agent_context/recipe_collection.md` |
| BREQ-003 | The system shall keep Inventory catalog/vendor identity separate from Recipe Collection item identity. | Implemented draft/MVP | Observed | `docs/agent_context/inventory.md`, `database/schema.sql` |
| BREQ-004 | The system shall support role-based review before recipes become live production items. | Implemented MVP | Observed | `src/services/workflow_service.py` |
| BREQ-005 | The system shall support production-facing forecasts and posted production facts for downstream reporting. | Implemented MVP | Observed | `src/services/production_record_service.py` |
| BREQ-006 | The system shall provide inventory planning without slowing the main inventory dashboard. | Implemented MVP | Observed | `docs/agent_context/inventory.md` |
| BREQ-007 | The system shall stage invoice/vendor data before treating it as accounting truth. | Implemented draft direction | Observed | `docs/agent_context/inventory.md`, invoice schema |
| BREQ-008 | The future-state prototype shall address corporate current-state gaps in mass-to-volume conversion and commercial-kitchen unit scaling. | Future-state objective | User-provided/Observed | User clarification; recipe/unit services |
| BREQ-009 | The future-state prototype shall support sub-recipe ingredient rollups so nested recipes contribute to scaled demand. | Future-state objective | User-provided/Observed | User clarification; recipe flattening/scaling services |
| BREQ-010 | The future-state prototype shall connect menu forecasting to production records and forecast accuracy analysis. | Future-state objective | User-provided/Observed | User clarification; production record services |
| BREQ-011 | The future-state prototype shall support ordering forecast direction from menu/recipe demand and inventory facts. | Future-state objective | User-provided/Observed | User clarification; inventory planning services |

## Functional Requirements

| ID | Requirement | Status | Evidence Quality | Acceptance Criteria |
| --- | --- | --- | --- | --- |
| FREQ-001 | Users can create base foods with unique normalized names. | Implemented | Observed | Duplicate creation returns or suggests a suffixed name. |
| FREQ-002 | Users can create recipes with yield, ingredients, method, and instructions. | Implemented | Observed | Missing required recipe fields produce validation errors. |
| FREQ-003 | Authorized workflow users can move items through submitted/reviewed/approved/analyzed/live/rejected states. | Implemented | Observed | Invalid role/action combinations are blocked; required reasons are enforced. |
| FREQ-004 | Menu owners can create dated menus and materialize slots from selected service days, meal periods, and concepts. | Implemented | Observed | Menu creation creates the expected slot count. |
| FREQ-005 | Menu users can copy, paste, and clear menu slot assignments by cell/day/week/concept scope. | Implemented | Observed | Route/service tests pass assignment reuse scenarios. |
| FREQ-006 | Forecast users can save yield, case, serving, case-pack, and batch-split forecast data. | Implemented | Observed | Batch splits totaling other than 100 are rejected. |
| FREQ-007 | Production users can snapshot forecast rows, record actuals/variance, post records, export CSV, and view history. | Implemented | Observed | Posted facts exclude drafts and production record posting requires recorded lines. |
| FREQ-008 | Inventory users can create locations/sub-locations, count items, reorder rows/breaks, transfer rows, print count sheets, and view current on hand. | Implemented | Observed | Inventory route and service tests cover count/current-on-hand behavior. |
| FREQ-009 | Inventory users can review catalog matches and manage approved substitutes. | Implemented draft | Observed | One preferred active substitute is enforced per catalog item. |
| FREQ-010 | Inventory users can stage vendor invoice lines, auto-match by vendor code, manually link unmatched lines, and place lines into grouped sub-locations. | Implemented draft | Observed | Invoice service tests cover staging, matching, linking, placement, and substitutes. |
| FREQ-011 | Dev users can generate seed data and operating data for manual workflow testing. | Implemented | Observed | Dev automation tests cover menus, records, inventory, and invoices. |
| FREQ-012 | Users can scale recipes using measurement authority that supports same-family and mass/volume bridge conversions. | Implemented | User-provided/Observed | Unsupported conversions produce warnings rather than silent bad quantities. |
| FREQ-013 | Users can use hotel-pan units in live scaling and Forecasting contexts. | Implemented | User-provided/Observed | Advanced units are available where production planning needs them and restricted from basic authoring. |
| FREQ-014 | Users can view nested recipes as hierarchical and flattened ingredient rollups. | Implemented | User-provided/Observed | Flattening expands sub-recipe ingredients and preserves warnings for problematic conversions/cycles. |
| FREQ-015 | Users can analyze forecast accuracy from production actuals and variance. | Implemented / expanding | User-provided/Observed | Production records calculate implied demand and forecast accuracy; history and item trends are available. |
| FREQ-016 | Users can generate inventory planning signals from upcoming menu/recipe demand and current on hand. | Implemented / expanding | User-provided/Observed | Planning rows expose coverage, shortage/review status, and ordering-window context. |

## Non-Functional Requirements

| ID | Requirement | Status | Evidence Quality |
| --- | --- | --- | --- |
| NFR-001 | The app should remain lightweight and local-first using Flask, SQLite, server-rendered templates, and focused JavaScript. | Current architecture | Observed |
| NFR-002 | Expensive calculations should not block first-screen dashboards. | Implemented pattern | Observed |
| NFR-003 | Business calculations should live in service/query layers, not templates. | Documented standard | Observed |
| NFR-004 | Schema changes should use forward-only migrations and update `database/schema.sql`. | Documented standard | Observed |
| NFR-005 | Tests should be scoped by module/relation markers for focused validation. | Implemented | Observed |
| NFR-006 | Production security, authentication, backup, deployment, and data retention requirements are needed before live production use. | Not defined | Inferred/Unknown |

## Assumptions and Dependencies

- Inferred: SQLite remains acceptable while the product is local-first/MVP and data volume is limited.
- Inferred: Mock auth is acceptable for development and role testing only.
- Observed: Future Analytics depends on stable menu, usage, inventory, purchasing, cost, and production-variance contracts.
- User-provided: The corporate current-state gap examples are accepted as initial future-state drivers for this analysis.
- Unknown: Stakeholder approval is required before treating these prototype requirements as official replacement-system requirements.

## BA Alignment

- Activity areas: Manage requirements lifecycle; analyze requirements and define design options.
- Techniques used: Requirements analysis, acceptance criteria, document analysis, interface analysis.