# Specification: 033-replenishment-reporting-system

## Status

| Field | Value |
|-------|-------|
| **Created** | 2026-02-05 |
| **Current Phase** | PLAN Reviewed - Ready for Implementation |
| **Last Updated** | 2026-02-05 |
| **PLAN Created** | 2026-02-05 |
| **PRD Review Date** | 2026-02-05 |
| **SDD Started** | 2026-02-05 |
| **SDD Review Date** | 2026-02-05 |

## Documents

| Document | Status | Notes |
|----------|--------|-------|
| product-requirements.md | completed | ✅ Codex reviewed, all blockers resolved; buy data source corrected |
| solution-design.md | completed | ✅ Codex reviewed, 6 ADRs confirmed, all blockers resolved |
| schema-validation-report.md | completed | Schema vs SDD validation report |
| implementation-plan.md | completed | ✅ 10 phases, 95+ tasks, full PRD coverage, Codex reviewed |

**Status values**: `pending` | `in_progress` | `completed` | `skipped`

## Decisions Log

| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-02-05 | Schema validation completed | Identified 5 critical issues, 3 moderate issues, 4 minor inconsistencies. See schema-validation-report.md |
| 2026-02-05 | POS subcategory as main bin category | User clarified that mainCategory should always be a POS subcategory for sales matching. Custom categories become "tags". |
| 2026-02-05 | Graceful migration for existing bins | Existing mainCategory values that aren't POS codes get moved to tags; mainCategory set to NULL |
| 2026-02-05 | Start with PRD phase | Complex multi-module feature requires solid requirements before technical design |
| 2026-02-05 | Per-rack unit override | Individual racks can override their rack type's default capacity. E.g., Double H-rack=4, modified H-rack=1.5 |
| 2026-02-05 | Rack unit defaults | H-rack=2, Rounder=1, Four-Way=4, Gondola=4, Double H-rack=4, Wall=varies |
| 2026-02-05 | 7-day rolling window + manual reset | Default time window is 7 days. "Reset All Replenishment" button allows manual override. |
| 2026-02-05 | In-app only notifications | Dashboard widget and badges; no push/email for initial release |
| 2026-02-05 | All concepts get POS categories | Non-PC stores will get POS subcategories; develop using PC data |
| 2026-02-05 | Replace Audit button | Replenishment report replaces existing "Audit" button on heatmap page |
| 2026-02-05 | Bin priority: Onsite first, then FIFO | Always prefer onsite bins; then oldest by ageDate |
| 2026-02-05 | Modal popup for zone details | Clicking zone opens modal with stats and Create Task button |
| 2026-02-05 | Batch task creation | Checkboxes in table enable bulk task creation |
| 2026-02-05 | Per-store threshold settings | Adequate/Monitor/Urgent thresholds configurable per store |
| 2026-02-05 | Smart bin category removal | On task complete, handle single vs multi-category bins with prompts |
| 2026-02-05 | Full mobile support | All features responsive for mobile/tablet |
| 2026-02-05 | Floor plan permissions | Anyone with floor plan access can configure rack units/thresholds |
| 2026-02-05 | Default score thresholds | 0-5 Adequate, 5-15 Monitor, 15+ Urgent (per-store customizable) |
| 2026-02-05 | Remove main category on completion | Task completion removes main POS category; tags stay |
| 2026-02-05 | Setup wizard for empty state | Guide users through floor plan + categories + rack units setup |
| 2026-02-05 | Exact POS code matching for buys | Buy's subCatID must exactly match floor socket's subcategory |
| 2026-02-05 | Link bins to tasks | Track specific bin used for each replenishment task in history |
| 2026-02-05 | SDD: Use kiosk_sales.buys for buy data | kiosk_sales.buys has subCatID for accurate per-category buy tracking |
| 2026-02-05 | SDD Review: Modify existing mainCategory | Use existing bsBins.mainCategory column for POS codes; simpler schema than new column |
| 2026-02-05 | SDD Review: 5-tier threshold system | Aligned SDD with PRD's 5-tier color scale: Green/Yellow/Orange/Red/Deep Red |
| 2026-02-05 | SDD Review: UI entry points added | Specified Audit button replacement, heatmap toggle, setup wizard |
| 2026-02-05 | SDD Review: Offsite print UX | Added state model for pulled/included checkboxes, print styling spec |
| 2026-02-05 | SDD Review: Should-have features deferred | Alerts (F9) and History (F10) explicitly deferred to Phase 2 |
| 2026-02-05 | SDD Review: Analytics events mapped | PRD tracking events → service methods with emit locations |
| 2026-02-05 | SDD Review: Traceability matrix added | PRD features → SDD components/endpoints/migrations/tests |
| 2026-02-05 | PRD Update: Buy data source corrected | Changed buyQueue → kiosk_sales.buys for consistency with SDD |
| 2026-02-05 | SDD: New ReplenishmentHeatmapService | Separate service for clean architecture, not extending existing HeatmapService |
| 2026-02-05 | SDD: POS as main category confirmed | Backstock bins use POS subcategory as primary, custom categories become tags |
| 2026-02-05 | PLAN created | 10 phases with TDD structure; parallel execution for P2.1-2.3, P6-P7 |
| 2026-02-05 | PLAN Reviewed by Codex | Resolved 4 blockers, 6 important items; added 10+ tasks for settings, TaskCompletion, bulk API, offsite report, empty states |
| 2026-02-05 | SDD: Category-level thresholds | Thresholds configurable per-category with store-level defaults (0-5/5-15/15+) |
| 2026-02-05 | SDD: Auto-reset on task completion | Completing replenishment task resets that category's time window |
| 2026-02-05 | PRD Review: Hybrid time window | Resolved blocker: Default 7-day rolling window; resets to fresh window on replenishment completion |
| 2026-02-05 | PRD Review: Stockout definition | Resolved blocker: Stockout = category score > Urgent (15+) for 24+ consecutive hours |
| 2026-02-05 | PRD Review: Store eligibility | Resolved blocker: Stores without POS data see warning but can access feature |
| 2026-02-05 | PRD Review: Color thresholds | Added 5-tier color scale: Green (0-5), Yellow (5-10), Orange (10-15), Red (15-20), Deep Red (20+) |
| 2026-02-05 | PRD Review: Responsive breakpoints | Defined: Desktop ≥1200px, Tablet 768-1199px, Mobile ≤767px |
| 2026-02-05 | PRD Review: Trip estimation | 10 bins per trip (configurable in store settings) |
| 2026-02-05 | PRD Review: Operational edge cases | Added scenarios for partial replenishment, concurrent tasks, bin moves, category removal |

## PRD Review Summary

**Review Date:** 2026-02-05
**Reviewer:** Codex (via MCP)

### Blockers Resolved
1. ✅ **Time window conflict** - Clarified as hybrid: 7-day rolling default, resets on replenishment
2. ✅ **Stockout definition** - Defined as score > Urgent for 24+ hours with tracking events
3. ✅ **POS data eligibility** - Stores without data see warning, can still access feature

### Important Improvements Made
- Added 5-tier color scale with specific hex values
- Defined responsive breakpoints (Desktop/Tablet/Mobile)
- Added trip estimation formula (10 bins per trip)
- Added 4 operational edge cases for task/bin state handling
- Added Dependencies section with data/system/migration requirements
- Added explicit "Won't Have" items for IoT/real-time tracking

### Ready for SDD
All blockers resolved. PRD is complete and ready for Solution Design phase.

## SDD Review Summary

**Review Date:** 2026-02-05
**Reviewer:** Codex (via MCP)

### Blockers Resolved
1. ✅ **Buy data source mismatch** - Confirmed kiosk_sales.buys is correct; updated PRD to match
2. ✅ **Backstock category column** - Decided to modify existing mainCategory (not add new column)
3. ✅ **Threshold tier mismatch** - Aligned SDD to PRD's 5-tier system with specific colors

### Important Improvements Made
- Added UI Entry Points section (Audit button replacement, heatmap toggle, setup wizard)
- Added Offsite Print UX specification with state model and print styling
- Added Analytics Events Mapping table (PRD events → emit locations)
- Added PRD-to-SDD Traceability Matrix
- Added Scope Boundaries section (Should-have features explicitly deferred)
- Added ADR-6 for mainCategory column decision
- Fixed code examples to use mainCategory instead of mainPOSCategory
- Added cache invalidation timing to Quality Requirements

### Architecture Decisions Confirmed (6 Total)
1. ADR-1: kiosk_sales.buys for buy data ✅
2. ADR-2: POS category as main, custom as tags ✅
3. ADR-3: New ReplenishmentHeatmapService (not extending) ✅
4. ADR-4: Category-level thresholds with store defaults ✅
5. ADR-5: Task completion resets category window ✅
6. ADR-6: Modify existing mainCategory column ✅

### Ready for Implementation Plan
All blockers resolved. SDD is complete and ready for Implementation Planning phase.

## PLAN Review Summary

**Review Date:** 2026-02-05
**Reviewer:** Codex (via MCP)

### Blockers Resolved
1. ✅ **Bulk category settings endpoint missing** - Added T3.3.10 for POST /categories/settings
2. ✅ **Store settings persistence not covered** - Added T1.3.6 migration + T8.5 backend service
3. ✅ **Workbook settings reset button missing** - Added T4.4.3 template modification
4. ✅ **TaskCompletion model linkage missing** - Added T2.6 sub-phase for integration

### Important Improvements Made
- Added dedicated offsite report JS module (T5.6) with bin selection, sorting, estimated trips
- Added table default view toggle (T5.5.6) for "Needs Attention" vs "Show All"
- Added task modal fields for employee assignment and destination zone (T5.3.9)
- Added empty/warning state handling in page controller (T3.4.4-5) and frontend (T5.3.8)
- Added backend tests to T6/T7 for TDD consistency
- Added explicit Phase 6/7 dependencies on Phase 1/2
- Added API/UI contract checkpoint (T3.6.5) after Phase 3
- Added cache invalidation tasks (T8.5.3) and timezone handling (T8.5.4)
- Added Risks & Mitigations section
- Added per-phase Definition of Done criteria

### Ready for Implementation
All blockers resolved. Implementation Plan is complete with 10 phases, 95+ tasks, full PRD/SDD coverage.

---

## Context

### Business Problem
Resale stores need intelligent replenishment tracking that accounts for:
1. **Variable floor space per category** - Denim jeans might have 4-6 rack lengths while summer skirts have 0.5 rack lengths
2. **Buy activity offsetting sales** - Items bought are tagged and placed on racks same day, reducing replenishment need
3. **Backstock bin management** - Prioritize onsite bins for quick replenishment; generate offsite pull reports when needed
4. **Actionable task generation** - Create workbook tasks when bins are pulled for replenishment

### Existing System Analysis

**Floor Plan Module** (`userfrosting/src/BuyerKiosk/FloorPlan/`):
- Racks placed on canvas with positions and categories assigned via sockets
- RackTypes define templates (H-rack, Rounder, etc.) with `defaultSocketCount`
- SocketAssignments link subcategory codes to rack sockets
- HeatmapService generates sales heatmaps by aggregating sales data to socket positions
- Already has `widthFeet`/`depthFeet` on RackTypes (migration 20251219_001)

**Backstock Module** (`userfrosting/src/BuyerKiosk/Backstock/`):
- Bins with categories (`mainCategory`, plus `bsBin_Cat` junction table)
- Locations with `onsite` boolean flag
- Age tracking via `ageDate` field
- BackstockFactory provides bin retrieval by category/location

**Workbook Tasks** (`userfrosting/src/BuyerKiosk/Workbook/`):
- TaskListManager handles task lists with scheduling
- Tasks linked to taskGroups
- Completion tracking via `workbook_task_completions`

**Sales Data** (`kiosk_sales` database):
- `sales` table with `subCatID`, `salesDate`, `price`, `typeNum`
- Already used by HeatmapService

**Key Tables (Store DB)**:
- `fpRackTypes` - Rack templates with socket counts, dimensions
- `fpRacks` - Placed racks on floor plan
- `fpRackSockets` - Individual sockets per rack
- `fpSocketAssignments` - Category-to-socket mapping per layout
- `bsBins` - Backstock bins with categories
- `bsLocations` - Locations (onsite/offsite)
- `bsBin_Cat` - Bin-to-category junction
- `tasks` - Workbook tasks
- `workbook_task_completions` - Task completion tracking

### Key Requirements Summary

1. **Rack Capacity Tracking**
   - Add "rack units" to RackTypes as defaults (H-rack=2, Rounder=1, etc.)
   - Allow individual racks to override type defaults (Double H-rack=4, modified racks)
   - Calculate rack unit allocation per category on a socket
   - UI for adjusting category-to-rack-unit distribution

2. **Replenishment Scoring**
   - Formula: `(sales - buys) / rack_length_capacity`
   - Score indicates "fullness depletion rate"
   - Higher score = more urgent replenishment need

3. **Three Reports**
   - **Replenishment Heatmap**: Visual floor plan with depletion intensity
   - **Replenishment Table**: Ranked categories with bin recommendations
   - **Offsite Pull Report**: Printable list for offsite storage retrieval

4. **Task Integration**
   - Generate workbook tasks when bins pulled
   - Mark area "replenished" when task completed
   - Track replenishment history

---
*This file is managed by the specification-management skill.*