# Specification: 047-backstock-category-customization

## Status

| Field | Value |
|-------|-------|
| **Created** | 2026-04-21 |
| **Current Phase** | COMPLETED - All 7 phases + E2E validated |
| **Last Updated** | 2026-04-22 |

## Documents

| Document | Status | Notes |
|----------|--------|-------|
| product-requirements.md | completed | All questions resolved via discovery |
| solution-design.md | completed | All 5 ADRs confirmed |
| implementation-plan.md | completed | 7 phases, ~100 tasks (reviewed, 5 gaps filled) |

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

## Decisions Log

| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-04-21 | Per-store visibility | Each store independently manages DRS visibility |
| 2026-04-21 | Groups replace mainCategory | Group ID stored as mainCategory, not auto-populating tags |
| 2026-04-21 | Sum all DRS in group for reporting | Approximation is better than zero data from custom cats |
| 2026-04-21 | Hide from dropdown only | Existing bin assignments preserved when hiding categories |
| 2026-04-21 | Multiple groups per DRS allowed | More flexible organization, accept reporting overlap |
| 2026-04-21 | Short names for all types | DRS, custom, and groups all get optional short name |
| 2026-04-21 | Floor plan shows group name | Group name displayed, drill-down reveals members |
| 2026-04-21 | Hidden DRS still in groups | Hiding is standalone-only, groups unaffected |
| 2026-04-21 | Grouped DRS hidden from dropdown | DRS in groups only accessible via group selection |
| 2026-04-21 | No auto-migration to groups | Existing bins keep individual assignments |
| 2026-04-21 | Plan review: 0 blockers, 5 important gaps filled | Added MobileAPI, FloorPlanAPI, audit logging, workbook route, tracking events |

## Plan Review Summary (2026-04-21)

**Blockers:** 0
**Important gaps found and fixed:** 5
1. Added MobileApiController integration (T4.4) — getCategoriesWithBinCounts() needs group support
2. Added FloorPlanApiController integration (T4.3) — getCategories() and bulkUpdateAssignments() need group handling
3. Added audit logging tasks (T4.5) — bsActions logging for group CRUD and visibility changes
4. Added workbook backstock route update (T3.4.3.6) — workbook category endpoint needs CategoryConfigService
5. Added PRD tracking events (T7.6) — all 7 tracking events from PRD now have implementation tasks

**Enhancements applied:** 2
1. Tagged Phase 2 test tasks as `[parallel: true]`
2. Added CSS consideration note for Phase 5 modal styling

**Verdict:** Ready for Phase 1 implementation.

## Implementation Complete (2026-04-22)

All 7 phases implemented, reviewed, and E2E validated on dev2.buyerkiosk.com:

| Phase | Description | Tests |
|-------|-------------|-------|
| 1 | Foundation (Models, Enums, Migrations) | Unit tests pass |
| 2 | Service Layer (CategoryConfigService) | Unit tests pass |
| 3 | Backend Integration (Repositories, API) | 9 endpoints, all secure |
| 4 | Reporting Integration | Audit logging verified |
| 5 | Frontend Settings UI (Config Manager) | 4-tab modal working |
| 6 | Frontend Dropdown & Visual Indicators | Sectioned DDL in 3 views |
| 7 | Integration & E2E Validation | 330 tests, browser validated |

**Key metrics**: 330 Backstock unit tests pass (993 assertions), CSS build hash 77d812ac, 7 tracking events, 9 API endpoints, all `catch(\Throwable)` verified.

## Context

Enhance the backstock module's main category system with four key capabilities:

1. **Show/Hide DRS Categories** - Not all POS subcategories are relevant to every store. Allow stores to toggle which DRS categories appear in the main category dropdown.

2. **Custom Categories** - Add ability to create custom categories for organizational purposes. These won't be tracked in floor plan reporting but help with backstock organization. Includes a `shortName` field for use in report tables instead of long names.

3. **Category Groups** - Allow grouping multiple DRS categories into named groups (e.g., "Girls Tops" grouping all girls tops subcategories). Groups can be selected as the main category for a bin instead of individual categories.

4. **Floor Plan Reporting Integration** - When a bin uses a category group, reporting can map to the underlying DRS categories for sales/buys analysis. This provides better data than custom categories which have no DRS mapping at all.

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