# KYN POS — Phase 2 Schema Notes

Phase 2 adds the first real POS data model on top of the Phase 1 foundation.

The old K41 POS is still treated as business-logic reference only. None of the old legacy tables are copied directly. The new schema is normalized, InnoDB-based, `utf8mb4`, and designed to feed KYN ERP, the Food Cost Calculator, and the future TFF Auto-Resupply Engine.

## Design/code separation rule

Designers should continue working mainly in:

```text
/templates
/public/assets/css
/public/assets/js
```

Database structure, business rules, permissions, calculations, payments, and integrations stay in:

```text
/inc
/modules
/sql
/storage
```

The new schema catalog page follows this rule: `modules/schema/controller.php` prepares simple arrays, and `templates/schema/index.php` only displays them.

## Migration order

Run migrations in this order:

```text
/sql/migrations/001_foundation_schema.sql
/sql/migrations/002_core_pos_schema.sql
/sql/seeds/002_core_pos_seed_minimum.sql
```

The seed file is safe baseline lookup data only. It does not create real staff passwords or PINs.

## What Phase 2 adds

- Staff, roles, PIN hashes, and shifts.
- Dining zones, tables, and table merge rules.
- Service types, tax rates, sales departments, menu categories, menu items, menu price history, modifier groups, modifiers, and item/modifier relationships.
- Checks, check lines, line modifiers, course events, and line events.
- Discounts, voids, tax lines, payment methods, payment rows, payment allocations, and tip lines.
- Cash drawer sessions, cash drawer entries, daily close batches, tender totals, department totals, and item totals.
- KYN/Food Cost/TFF bridge placeholders using external UUIDs instead of cross-database foreign keys.

## Key design choices

### 1. Checks replace the old cart/order/transaction split

The old system used `cart_k41`, `order_k41`, and `transactions_k41`. The new model uses:

```text
pos_checks
pos_check_lines
pos_check_line_modifiers
pos_payments
pos_daily_close_batches
```

This keeps the workflow simple but auditable.

### 2. Voids are never destructive deletes

The old system could delete cart lines. The new system keeps line records and adds explicit void records:

```text
pos_check_line_voids
pos_void_reason_codes
```

That gives KYN visibility into waste, mistakes, training issues, theft review, and operational leakage.

### 3. Modifiers are normalized

The old system stored repeated modifier columns. The new system uses:

```text
pos_modifier_groups
pos_modifiers
pos_modifier_group_options
pos_menu_item_modifier_groups
pos_check_line_modifiers
```

This lets a modifier change price, kitchen display, food-cost behavior, packaging, or TFF resupply logic later.

### 4. Daily close is the KYN boundary

The POS runs service in real time. KYN should consume finalized facts after closeout.

The important boundary table is:

```text
pos_daily_close_batches
```

KYN imports from daily close, check headers, check lines, modifiers, payments, taxes, tips, discounts, voids, and item movement.

### 5. External KYN/Food Cost/TFF links use UUIDs

KYN ERP, Food Cost Calculator, and TFF production planning may live in separate databases. Phase 2 therefore uses external UUID columns such as:

```text
kyn_sales_department_uuid
food_cost_recipe_uuid
tff_resupply_sku_uuid
packaging_profile_uuid
```

No cross-database foreign keys are used.

## What Phase 2 does not do yet

Phase 2 does not create the working POS ordering screen yet.

It does not yet include:

- Staff PIN login workflow.
- Table dashboard actions.
- Add item to check workflow.
- Payment form.
- Daily close calculation code.
- Food Cost theoretical usage calculation.
- TFF par/resupply engine.

Those come after the data model is approved.

## Recommended next phase

Phase 3 should create the first working operational slice:

```text
Staff PIN login
→ table dashboard
→ open check
→ add simple menu item
→ view open check
```

Do not build payments before open checks and check lines are stable.