# User Stories Baseline

**Source:** `~/ALAI/products/Plock/docs/demo-readiness/01-user-stories-baseline.md`

---

# PLOCK — User Stories Baseline

**Date:** 2026-03-14  
**Purpose:** Establish a first canonical user-story baseline for PLOCK using real repository evidence and authoritative product documents. This is not yet the final polished story set; it is the operational baseline for documentation, QA, and backlog slicing.

---

## 1. Scope and Method

This baseline is derived from:

- `docs/PRD.md`
- actual backend route/service structure
- actual frontend MFE structure
- integration modules present in the repository
- operational and regulatory documentation where relevant

This document intentionally avoids inventing features not supported by either:

- current product docs, or
- current repository structure

---

## 2. Story Status Model

Each story is tagged as one of:

- **exists** — strongly supported by real code/routes/docs
- **partial** — visible in docs and/or code structure, but maturity unclear
- **planned** — described in docs, but implementation evidence is limited or phase-dependent

---

## 3. Receiving / Inbound

### US-INB-001 — Receive goods via barcode

**Status:** exists  
**Evidence:** `PRD.md`, `ReceivingRoutes.kt`, `ReceivingService.kt`, barcode-related backend structure

**As a** warehouse worker  
**I want to** scan a barcode and identify the purchase order it belongs to  
**So that** I can receive goods correctly without manual lookup

### US-INB-002 — View open purchase orders

**Status:** exists  
**Evidence:** `PRD.md`, `ReceivingRoutes.kt`, supplier/receiving route structure

**As a** warehouse manager  
**I want to** see all open purchase orders and expected arrival dates  
**So that** I can plan staffing and dock capacity

### US-INB-003 — Guided putaway after receiving

**Status:** partial  
**Evidence:** `PRD.md`, `LocationRoutes.kt`, `PutAwayService.kt`

**As a** warehouse worker  
**I want to** be guided to the correct bin location after receiving  
**So that** I do not need to memorize where products belong

### US-INB-004 — Detect receiving discrepancies

**Status:** exists  
**Evidence:** `PRD.md`, `ReceivingDiscrepancyTest.kt`, discrepancy migration/table evidence

**As a** warehouse manager  
**I want to** be notified immediately when received quantities do not match the purchase order  
**So that** I can resolve supplier issues before inventory is corrupted

---

## 4. Inventory Management

### US-INV-001 — Real-time inventory visibility

**Status:** exists  
**Evidence:** `PRD.md`, `InventoryRoutes.kt`, `InventoryService.kt`

**As a** warehouse manager  
**I want to** see the exact quantity of a SKU by location in real time  
**So that** I can answer operational questions without walking the warehouse

### US-INV-002 — Reorder point alerting

**Status:** partial  
**Evidence:** `PRD.md`, inventory domain present; implementation maturity unclear

**As a** warehouse manager  
**I want to** receive an alert when inventory falls below reorder point  
**So that** I can prevent avoidable stockouts

### US-INV-003 — Zone-based cycle counts

**Status:** exists  
**Evidence:** `PRD.md`, `CycleCountRoutes.kt`, `CycleCountService.kt`, tests

**As a** warehouse manager  
**I want to** run a cycle count for a specific zone without stopping all operations  
**So that** I can maintain inventory accuracy continuously

### US-INV-004 — Mobile-assisted physical inventory count

**Status:** partial  
**Evidence:** `PRD.md`, V7 mobile support migrations, runbook/mobile references

**As a** warehouse worker  
**I want to** perform physical inventory counts on a mobile device  
**So that** counting is faster and less error-prone than paper workflows

---

## 5. Orders / Outbound

### US-OUT-001 — Release urgent orders quickly

**Status:** exists  
**Evidence:** `PRD.md`, `OrderRoutes.kt`, order/picking domain structure

**As a** warehouse manager  
**I want to** release urgent orders with a single action  
**So that** I can respond quickly to escalations and deadlines

### US-OUT-002 — Work from structured picking flow

**Status:** exists  
**Evidence:** `PickingRoutes.kt`, `PickingService.kt`, `mfe-picking`

**As a** picker  
**I want to** receive a structured picking workflow  
**So that** I can pick efficiently and consistently

### US-OUT-003 — Verify packing with product photo

**Status:** partial  
**Evidence:** `PRD.md`, frontend/product/packing intent visible in docs

**As a** packing worker  
**I want to** see a product photo during packing  
**So that** I can confirm I am sealing the correct item

### US-OUT-004 — Unified shipment tracking view

**Status:** partial  
**Evidence:** `PRD.md`, `ShipmentRoutes.kt`, carrier integration structure

**As a** warehouse manager  
**I want to** see outbound shipment status in one place  
**So that** I can proactively handle delays and customer issues

---

## 6. Shipping / Carrier Operations

### US-SHP-001 — Print carrier labels directly from Plock

**Status:** exists  
**Evidence:** `PRD.md`, PostNord/DHL/Instabee integration code, shipment/carrier routes

**As a** warehouse worker  
**I want to** print shipping labels directly from Plock  
**So that** I do not need to log into separate carrier portals

### US-SHP-002 — Use multiple carriers in one operational flow

**Status:** exists  
**Evidence:** `CarrierRoutes.kt`, `CarrierIntegrationRoutes.kt`, multiple carrier adapters/services

**As a** warehouse manager  
**I want to** work with PostNord, DHL, and Instabee in one system  
**So that** outbound shipping does not depend on multiple manual carrier workflows

### US-SHP-003 — Track carrier sync and integration health

**Status:** partial  
**Evidence:** `integration_sync_log` schema, runbook sections for Fortnox/carrier failures

**As a** system operator  
**I want to** inspect carrier/integration sync behavior  
**So that** I can detect and troubleshoot failures quickly

---

## 7. AI / Smart Warehouse Operations

### US-AI-001 — Ask warehouse questions in Swedish

**Status:** partial-to-exists  
**Evidence:** `PRD.md`, `AI-STRATEGY.md`, `mfe-ai/`, product positioning

**As a** warehouse manager  
**I want to** ask warehouse questions in Swedish and get immediate answers  
**So that** I can make decisions without SQL, exports, or manual searching

### US-AI-002 — Execute warehouse commands via AI with confirmation

**Status:** planned / partial  
**Evidence:** `PRD.md`, `AI-STRATEGY.md`

**As a** warehouse manager  
**I want to** trigger operational actions through natural language with explicit confirmation  
**So that** I can manage exceptions faster than through deep UI navigation

### US-AI-003 — Optimize pick routes

**Status:** partial-to-exists  
**Evidence:** `PRD.md`, `AI-STRATEGY.md`, picking domain, runbook references to Smart Picking

**As a** warehouse manager  
**I want to** use smart pick route optimization  
**So that** workers spend less time walking and more time picking

---

## 8. Dashboard / Monitoring

### US-DASH-001 — Operational dashboard

**Status:** exists  
**Evidence:** `DashboardRoutes.kt`, `PRD.md`, dashboard domain

**As a** warehouse manager  
**I want to** see a real-time dashboard with today’s operational KPIs  
**So that** I can spot bottlenecks before they become incidents

### US-DASH-002 — Monitor shipment and fulfillment progress

**Status:** partial  
**Evidence:** dashboard/shipment routes, PRD

**As a** operations lead  
**I want to** monitor fulfillment progress and pending shipments  
**So that** I can intervene before SLAs are missed

---

## 9. Users / Roles / Multi-Tenancy

### US-SEC-001 — Manage users and roles

**Status:** exists  
**Evidence:** `UserRoutes.kt`, `RoleRoutes.kt`, `RbacService.kt`

**As an** admin  
**I want to** manage users and roles  
**So that** only the right people can perform sensitive warehouse actions

### US-SEC-002 — Restrict data by warehouse

**Status:** exists  
**Evidence:** `TenantPlugin.kt`, `RLS-AUDIT.md`, RLS migrations

**As a** warehouse operator  
**I want to** only see data for my warehouse  
**So that** tenant/customer separation is enforced safely

### US-SEC-003 — Keep tenant isolation enforced at the DB layer

**Status:** exists  
**Evidence:** `RLS-AUDIT.md`, migration `V6__rls_tenant_isolation.sql`

**As the** platform  
**I want to** enforce tenant isolation in PostgreSQL using RLS  
**So that** application bugs do not automatically become cross-tenant data leaks

---

## 10. Integrations / Accounting

### US-INT-001 — Sync warehouse/accounting data with Fortnox

**Status:** exists  
**Evidence:** Fortnox integration modules, docs, secrets, runbook

**As a** Swedish SMB operator  
**I want to** integrate Plock with Fortnox  
**So that** warehouse operations and accounting stay aligned

### US-INT-002 — Re-authorize or recover from Fortnox sync failure

**Status:** partial-to-exists  
**Evidence:** Fortnox OAuth/sync routes, runbook incident section

**As a** tenant admin  
**I want to** reconnect or recover the Fortnox integration when it fails  
**So that** business operations are not blocked by stale tokens or sync errors

---

## 11. 3PL / Client Isolation (Phase-Dependent)

### US-3PL-001 — Separate client inventory views

**Status:** planned  
**Evidence:** `PRD.md`, `GTM-STRATEGY.md`, regulatory references

**As a** 3PL operations lead  
**I want to** see inventory separated by client  
**So that** I can manage a multi-client warehouse safely

### US-3PL-002 — Support 3PL billing workflows

**Status:** planned  
**Evidence:** `REGULATORY.md`, GTM and pricing logic

**As a** 3PL operator  
**I want to** support warehousing-service billing workflows  
**So that** customer charging is structured and scalable

---

## 12. Business / Sales / Market Layer

### US-BIZ-001 — Position as Fortnox-next-step WMS

**Status:** planned/business  
**Evidence:** `GTM-STRATEGY.md`

**As the** business  
**I want to** position Plock as the natural next step after Fortnox Lager  
**So that** market entry is focused and credible

### US-BIZ-002 — Support Swedish SMB self-serve onboarding motion

**Status:** planned/business  
**Evidence:** GTM and product docs

**As the** product business  
**I want to** enable a low-friction onboarding and trial motion  
**So that** acquisition cost stays low and distribution scales

---

## 13. Summary

### Strongly supported by current code/docs

- receiving
- inventory
- orders
- picking
- shipments
- carriers
- RBAC
- tenant isolation
- Fortnox integration
- dashboard
- barcode
- audit/webhook/SSE infrastructure

### Present but maturity unclear

- AI chat execution depth
- smart picking maturity
- mobile/PWA operational depth
- packing/photo verification
- full shipment monitoring UX
- reorder alerting maturity

### More Phase 2 / strategic than current MVP

- 3PL client isolation workflows
- 3PL billing
- full commercial/demo/support packaging
- polished sales enablement materials

---

## 14. Working Rule

This user-story baseline is the first canonical operational extraction.

Any future:

- feature catalog
- QA gate
- implementation backlog
- demo script
- support playbook

must map back to these stories and mark each item as:

- exists
- partial
- planned