# Proposal

## Why

Inventory and checkout currently use browser-local examples, so they cannot provide reliable stock availability, supervisor approval, or a durable movement history. A shared Inventory transaction service is needed before Maintenance can consume and return spareparts safely.

## What Changes

- Add API capabilities for sparepart master data, availability, summary, movement history/export, stock operations, and warehouse quarantine.
- Add checkout discovery through a general catalogue grouped by part group with search, and direct part lookup from a scanned QR. Scanning never posts stock.
- TECHNICIAN checkout waits for ADMIN/SUPERVISOR approval; ADMIN/SUPERVISOR checkout is approved and posted immediately. Pending requests do not reserve stock. No priority-based checkout auto-approval.
- Keep stock in one internal room balance per part without client location selection, new place/rack fields, or transfers. Preserve existing optional consumer location presentation pending compatibility confirmation.
- Make posted ledger entries the source of stock changes and future WO usage; enforce atomic writes, concurrency protection, retry safety, and attributed audit.
- Exclude prices, valuation, maintenance costs, and financial endpoints. Retain existing monetary columns as unused storage compatibility fields.
- Plan explicit confirmation checkpoints for consumer integration/approval UI, photo persistence, and any database mismatch. This proposal does not authorize consumer edits or schema migration execution.

## Capabilities

### New Capabilities

- `inventory-catalog`: Sparepart metadata, stock availability, master lookups, and summary.
- `inventory-ledger`: Stock posting, approval, immutable history, reversal, export, and Maintenance service boundary.
- `inventory-quarantine`: Immediate holds, case history, and controlled release/scrap.
- `inventory-checkout`: QR/catalogue discovery, attributed requests, and role-based checkout approval.

### Modified Capabilities

None. Durable specs inventory is currently empty. Follow the existing `establish-core-api-architecture` change specs and the Pilot Plant handoff without copying or superseding their capabilities.

## Impact

Backend additions stay in existing routes/controllers/services/validators/config folders, use the existing auth and response contract, and preserve current Work Order read URLs. Public DTO additions belong in packages/shared when that workspace is authorized. Real MySQL transaction tests and OpenAPI contract checks are required.

Consumer references: inventory/page.tsx, inventory/movement-page.tsx, and kiosk-checkout/page.tsx. These files remain untouched until explicit integration approval. Current UI gaps include approval queue/status, expanded movement types, safe stock adjustment, and persistent photos; detail and confirmation checkpoints are in design.md.

Existing Prisma models are the starting point, not authorization to alter their design. Photos and any additional persistence required for retry semantics or compatibility must be reviewed before migrations. Full Work Order execution, notifications delivery, location management, and financial reporting are outside this change.