# Specification: 045-workbook-backstock-report

## Status

| Field | Value |
|-------|-------|
| **Created** | 2026-04-13 |
| **Current Phase** | COMPLETE — All 6 Phases Done |
| **Last Updated** | 2026-04-21 |

## Documents

| Document | Status | Notes |
|----------|--------|-------|
| product-requirements.md | completed | Reviewed by Codex, all findings addressed |
| solution-design.md | completed | All ADRs confirmed by user, Codex reviewed + all findings addressed |
| implementation-plan.md | completed | All 6 phases complete, Phase 6 validation passed 2026-04-21 |

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

## Decisions Log

| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-04-13 | Full feature parity (not analytics) | User wants operational bins management, not the reports/analytics dashboard |
| 2026-04-13 | Full-page SPA view (not panel) | The feature is too complex for a workbook grid panel |
| 2026-04-13 | All workbook users (no role gating) | Simplest access model; feature flag is the gate |
| 2026-04-13 | Reuse admin API endpoints | Same data, less code duplication |
| 2026-04-13 | Syncfusion Charts preferred | Per CLAUDE.md guidance |
| 2026-04-13 | Disabled nav item when flag OFF | Teaches users the feature exists |
| 2026-04-13 | Admin settings toggle for flag | Owner self-service enablement |
| 2026-04-13 | Default OFF for existing stores | Opt-in model |
| 2026-04-13 | Ably real-time sync | Multi-employee collaboration on bins |
| 2026-04-13 | Events page not in this phase | Focus on core bins management |
| 2026-04-13 | Include bin creation, locations, categories, printing | Full management capability |
| 2026-04-13 | API-loaded data (not server-rendered) | SPA pattern: avoid loading 500+ bins on every workspace page load |
| 2026-04-13 | External JS modules (not inline Twig) | Follows workbook convention, better caching |
| 2026-04-13 | Separate BackstockAblySync class | Follows schedule-ably-sync.js pattern, cleaner separation |
| 2026-04-13 | Ably payload threshold: 50 bins | Full data for <=50, IDs-only for >50 (aligned with PRD chunking limit) |

## Codex PRD Review (2026-04-13)

### Blockers Resolved
1. **Access control model** - Verified that existing API endpoints use `checkStoreGroup()` (not `uri_backstock`). Workbook users can already call them. Added explicit access control model section to PRD.
2. **API endpoint compatibility** - Confirmed existing `/api/:typeNum/backstock/*` routes accept non-admin users. No changes needed. Noted inconsistent auth as future security hardening opportunity.

### Important Findings Addressed
3. Added performance SLAs (grid load <2s, search <300ms, operations <500ms)
4. Clarified delete vs hide/empty in acceptance criteria
5. Added error/rollback UX expectations for mass edit, printing, and bulk create
6. Added admin-to-workbook data consistency edge case (Scenario 11)
7. Added Ably payload size risk and mitigation (chunking for 50+ bins)

### Enhancement Findings (Noted, Not Blocking)
8. Quantitative baseline evidence - Not available yet; success metrics include measurement plan
9. Role qualifiers - User stories use "store employee" which is correct for workbook context
10. Baseline metrics - Will be established at feature flag enablement time

### Changes Made to PRD
- Added "Access Control Model (Validated)" section replacing generic assumption
- Added performance SLA acceptance criteria to Feature 2
- Clarified delete capability in Feature 4 description
- Added success/failure feedback expectations to Features 4 and 7
- Added 6 new edge cases (Scenarios 10-14) covering: API 403, admin-created bins, print failures, bin deletion, audit tracking disabled
- Added 2 new risks: Ably payload sizing and admin/workbook data inconsistency
- Updated assumptions with Ably chunking and admin sync trade-off

## Codex SDD Review (2026-04-13)

### Blockers Resolved
1. **CSV export not specified** - Added complete CSV export flow (Feature 10): client-side generation, filter-aware export dialog, UTF-8 BOM for Excel, filename convention, analytics tracking
2. **Ably channel naming inconsistent** - Clarified: uses existing store channel (`{typeNum}`), events namespaced by EVENT NAME with `backstock:` prefix (not channel name). Aligned payload threshold from 20→50 to match PRD
3. **Audit tab disabled behavior** - Added: tab shows "(Inactive)" label, content message, no API call, still clickable for UX clarity

### High-Priority Findings Addressed
4. **Hide Empty / Show Hidden toggle logic** - Added complete state machine: two independent toggles, client-side filtering, session-only persistence
5. **Comma-search UX** - Added: comma-split, whitespace trim, inclusive OR matching, help text, 300ms debounce
6. **Mid-session flag-off** - Added: graceful degradation, flag check on re-entry, redirect + toast, no real-time kill
7. **Zero bins empty state** - Added: "No Backstock Bins Yet" illustration, Create/Bulk Create CTAs, separate state for "all filtered out" vs truly empty
8. **Category badge click-to-filter** - Added: clickable badges, chip display, removable filters, AND stacking
9. **Double-submit prevention** - Added: _isSubmitting flag, button disable + spinner, re-enable on success/error

### Medium Findings Addressed
10. **Feature 11 scope** - Explicitly scoped: Ably covers bin mutations only, not locations/categories/config
11. **Component naming** - Standardized to `BackstockFloatingBar` throughout (was mixed FloatingActionBar/FloatingBar)
12. **Payload threshold** - Aligned SDD (was 20) to PRD value (50 bins)

### Changes Made to SDD
- Added "Detailed UI Behaviors" section with 8 behavior specifications
- Added CSV export endpoint note and BackstockManager.exportCsv() behavior
- Clarified Ably channel naming with explicit NOTE comment
- Added 6 new test scenarios (Scenarios 8-13)
- Updated test coverage requirements with all new items
- Fixed component naming inconsistency in diagrams

## Codex Plan Review (2026-04-13)

### Important Findings Addressed (7)
1. **Ably admin mutation guard** (HIGH) — Added source guard to T4.3.2: only publish Ably events when `workbookBackstockEnabled` flag is ON, preventing unnecessary traffic for non-enabled stores
2. **Direct URL with flag OFF** (HIGH) — Added server-side flag check to T1.5.1: route handler checks flag before rendering, redirects to workbook home when OFF
3. **Missing tracking events** (HIGH) — Added `workbook_backstock_flag_toggled` and `workbook_backstock_ably_sync` events to T5.3.1 with placement guidance
4. **Migration naming** (HIGH) — Clarified naming convention: uses `{specId}_{sequence}_{description}` format (not date-prefixed), updated T1.3.1
5. **File count mismatch** (MEDIUM) — Fixed summary section: was "14 new/9 modified", now correctly "16 new/11 modified"
6. **T3.2.3 Ably dependency in Phase 3** (MEDIUM) — Refactored to hook-point pattern: Phase 3 adds `showStaleDataWarning()` method, Phase 4 (T4.4.3) wires it to Ably events
7. **Slim 2 POST convention incomplete** (MEDIUM) — Added explicit Slim 2 convention notes to T3.2.2 (manage bin), T3.5.3 (bin creation), and Context Priming gotchas

### Enhancement Findings (Noted, Applied Where Practical)
8. **Ably channel naming** (HIGH) — FALSE POSITIVE: SDD already corrected. Added clarifying note to Context Priming to prevent future confusion
9. **Mid-session flag toggle data source** (MEDIUM) — Made T2.7.1 more explicit about re-entry flag check mechanism
10. **SDD inconsistent auth risk** (MEDIUM) — Added T6.4.3 to document the known limitation as a security hardening opportunity
11. **Error-state testing** (LOW) — Added T2.9.5 and T3.9.8 for explicit error state verification
12. **Large tasks** (LOW) — Accepted: tasks are detailed enough with sub-references for implementation
13. **Parallel opportunities** (LOW) — Accepted: current parallelism is sufficient; Phase 5 already allows parallel execution

### Changes Made to Implementation Plan
- Fixed file count summary (16 new, 11 modified)
- Updated migration naming from date-prefix to spec-prefix convention
- Added server-side flag check to routing task (T1.5.1)
- Added Ably source guard to publish injection task (T4.3.2)
- Refactored stale-data warning to hook-point pattern (T3.2.3)
- Added Slim 2 POST convention to manage-bin and bin-creation tasks
- Added 2 missing tracking events to analytics task (T5.3.1)
- Added Ably channel naming clarification to Context Priming gotchas
- Made mid-session flag check more explicit (T2.7.1)
- Added security hardening documentation task (T6.4.3)
- Added error-state test items (T2.9.5, T3.9.8)

## Phase 6 Validation Summary (2026-04-21)

### T6.1 - Automated Test Suite
- BackstockAbly unit tests: 13/13 pass, 64 assertions
- Store feature flag tests: 37/37 pass, 152 assertions
- Full unit suite: 8,291 tests pass (all failures pre-existing)
- PHPStan: 0 errors on all new/modified files

### T6.2 - E2E User Flows (18 tests, all pass)
- SPA navigation, grid loading (477 bins), search (single + comma-separated)
- Bin selection, floating action bar (9 buttons), manage bin modal (5 tabs)
- CSV export, locations modal, categories modal, add bin, bulk create
- Hide Empty / Show Hidden toggles, column filtering
- Nav away + re-entry lifecycle, Ably connection lifecycle
- Zero console errors throughout all testing

### T6.3 - Performance (Skipped)
- Dev via ngrok not representative of production
- Functional performance confirmed via E2E (grid loads, search responds, pagination works)

### T6.4 - Security Validation (All pass)
- Page route: guest redirect, checkStoreGroup(), feature flag check (flag checked AFTER auth)
- API routes: store-scoped via typeNum, 9 new checkStoreGroup() guards
- 16 feature flag checks on Ably publish paths
- 3 template-level flag gates (sidebar, HTML container, JS modules)

### T6.5 - Edge Cases (All verified)
- 4 UI states (loading, empty, grid, error) with proper transitions
- Comma search edge cases: empty terms, trailing comma, dedup, not-found tracking
- Ably: intentional disconnect flag, suspended/failed handlers, duplicate message detection

### T6.6 - PRD Acceptance Criteria (All 11 features verified)

### T6.7 - Final Build
- CSS build: 356.96 KB (71% of limit), version hash 2dabf88d
- 13 modified files + 12 new files tracked

## Context

Expose the full Backstock Bins Management experience (matching `/admin/:typeNum/backstock`) as a new SPA view within the Workbook at `/:typeNum/workbook/backstock`. Controlled by a per-store feature flag toggled from admin store settings. When enabled, all workbook users can search, filter, create, edit, and perform mass actions on bins with real-time Ably sync.

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