suaveplan/openspec/changes/enterprise-api-plugin-warehouse-ops/tasks.md

Tasks: enterprise-api-plugin-warehouse-ops

Change ID: enterprise-api-plugin-warehouse-ops Package: @suaveplan/api-plugin-warehouse-ops Target path: api/logistics/api-plugin-warehouse-ops Prerequisite packages on Verdaccio: @suaveplan/api, @suaveplan/api-shared, @suaveplan/api-plugin-auth, @suaveplan/api-plugin-database, @suaveplan/api-plugin-inventory, @suaveplan/events, @suaveplan/idempotency, @suaveplan/audit-logging, @suaveplan/barcode, @suaveplan/error

---

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold + types + errors + events

• Create api/logistics/api-plugin-warehouse-ops/; package.json v0.0.0; standard tooling.
• Types: Zone, Aisle, Bin, InboundReceipt, PickList, PickLine, CycleCount, WarehouseOpsConfig (Zod).
• Errors: 6-code union + registration. Test + doc.
• Events: WarehouseEventMap (warehouse:goods:received, warehouse:pickpack:ready, warehouse:cycle-count:completed).

---

2. SurrealQL

• zone.surql, aisle.surql, bin.surql, inbound_receipt.surql, pick_list.surql, pick_line.surql, cycle_count.surql. tenantId indexes.

---

3. Services (all .test.ts + .md)

• ZoneService: CRUD zones + aisles. getBinLabel(binId) via @suaveplan/barcode.
• BinService: CRUD bins; capacity tracking; slot optimisation (assign bin to SKU based on velocity).
• InboundService: receiveGoods(receipt) — record inbound receipt; trigger putaway suggestion; emit warehouse:goods:received.
• OutboundService: generatePickList(orderId) — create optimised pick route; confirmDispatch — emit warehouse:pickpack:ready.
• PickListService: getPickList, updatePickLine, completePickList.
• CycleCountService: startCycleCount, recordCount, completeCount (variance calculation); audit; emit event.

---

4. Routes

• Full CRUD + state transitions.
• Route .test.ts + .md.

---

5. Plugin factory + integration tests + publish

• createWarehouseOpsPlugin: definePlugin, dependencies: ["database", "auth"], migrationsPath: "./surql".
• Integration: receive goods → putaway → pick list → dispatch → warehouse:pickpack:ready event emitted (real SurrealDB).
• bunx turbo lint typecheck test --filter=@suaveplan/api-plugin-warehouse-ops — green; 100% coverage.
• bun scripts/publish.ts --package @suaveplan/api-plugin-warehouse-ops.
• Archive → openspec/archive/2026-04-24-enterprise-api-plugin-warehouse-ops/.