# MENU AVAILABILITY & PRODUCTION CAPACITY

**Service:** `common\services\MenuAvailabilityService` (single calculation engine, read-only)
**Controller:** `backend/controllers/MenuAvailabilityController.php` (`index`, `get-data`, `detail`)
**Views:** `backend/views/menu-availability/`
**Permission:** `viewMenuAvailability` (run `php yii rbac/init` to register it, then refresh permission cache)
**Tests:** `tests/unit/MenuAvailabilityServiceTest.php` (pure, no DB)

## 1. Data sources (no new tables)

| Need | Source |
|------|--------|
| Menus | `barang` where `jenis = 'Finish'`, `deleted_at IS NULL`, not draft, not bundled, active in `barang_stok` (`cabang_id`, `delete = 'N'`) |
| Recipe link | `barang.linked_fg` -> item whose recipe is in `barang_recipe` |
| BOM | `barang_recipe` (`barang_id` parent, `item_id` component, `amount`, `qty`, `conversion`), loaded level by level (1 query per nesting level) |
| Stock | `stok.latest_qty` of the **latest row per (barang, subwarehouse)** (`used_at`, highest `id` on ties), `deleted_at IS NULL`, summed only inside the selected location |

Bundled menus are not listed: they have no recipe, they consume the menus selected inside the bundle.

## 2. Stock location

POS sales and WIP production both post to the outlet's `mainKitchen` subwarehouse
(`MyStockManagement::insertStock()`), so that is the default. Filters allow a whole warehouse
(all its subwarehouses) or one subwarehouse. Stock of other locations is never added implicitly.

## 3. How existing consumption is mirrored

Quantities are in the item's base unit (`barang.satuan`); `conversion` converts the recipe unit.

| Linked item `cook_type` | Sale deducts | Ready Stock | Production Capacity |
|---|---|---|---|
| `1` cooked on sales | `amount * conversion` of each recipe row | 0 | `MIN(floor(available_i / need_i))` |
| `0` pre-cooked (stocked) | `hasil_jadi` of the linked item | `floor(stock / hasil_jadi)` | `floor((stock + batches * hasil_jadi * hasil_jadi_qty) / hasil_jadi) - ready` |

A production batch of an item consumes `amount * qty * conversion` of each of its recipe rows and yields
`hasil_jadi * hasil_jadi_qty` (see `MyStockManagement::saveWIP()`).

## 4. Nested BOM

For a component with its own recipe: `available = max(0, stock + producible)` where
`producible = floor(MIN(batch capacity of its rows)) * yield`. Stock is used first and only the missing amount is
produced, so stock and raw material are never counted twice. A negative balance must be covered by production first.
Recursion is guarded by the current path (circular recipe -> `circular`) and `MAX_DEPTH`.
`stok_ignore = 1` components are skipped, like POS does.

## 5. Status

* `not_configured` - no linked recipe / no ingredients / missing or deleted component / zero quantity or conversion /
  no stock-tracked component / circular recipe / missing yield (unless Ready Stock > 0). Never treated as unlimited,
  production capacity is 0 in that case.
* `out_of_stock` - total potential 0
* `limited` - total potential <= `limited_threshold` (default 10)
* `available` - otherwise

## 6. Result structure (per menu)

`menu_id, menu_name, menu_code, category_*, linked_fg_*, cook_type, ready_stock, production_capacity, total_potential,
status, status_label, bottleneck {item_id, name, capacity, path[]}, recipe_status, recipe_issues[], components[], batch`.
Each component node has `required_base, stock, producible, available_total, capacity, status, is_bottleneck, children[]`.

## 7. Independent capacity / future allocation

Every menu is calculated independently from the same stock snapshot, nothing is reserved or written, so capacities of
menus sharing an ingredient must not be summed (the dashboard card is labelled "sum of independent estimates").
`buildSnapshot()` (DB) and `calculateFromSnapshot()` (pure) are separate on purpose: a future Production Allocation can
clone the snapshot, decrement `snapshot['stock']` per planned menu and reuse the same calculation.
