# Specification: 042-backstock-mass-edit-bins

## Status

| Field | Value |
|-------|-------|
| **Created** | 2026-03-26 |
| **Current Phase** | Phase 2 COMPLETED — Phase 3 ready |
| **Last Updated** | 2026-03-26 |
| **Branch** | feature/backstock-mass-edit-bins |

## Documents

| Document | Status | Notes |
|----------|--------|-------|
| product-requirements.md | completed | Codex-reviewed 2026-03-26. All blockers resolved. 12 features specified. |
| solution-design.md | completed | Codex-reviewed 2026-03-26. 2 blockers resolved, 3 important items fixed, 2 enhancements added. Ready for implementation plan. |
| implementation-plan.md | completed | Codex-reviewed 2026-03-26. 7 phases, ~135 tasks. 3 blockers + 4 important items resolved. Backend-first → Grid migration → comma search → floating bar → modals + AJAX → E2E validation. |

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

## Decisions Log

| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-03-26 | Created on new branch | User requested isolated feature branch |
| 2026-03-26 | PRD completed | All 12 features specified with full edge cases. Decisions: full reset for empty, floating bar UI, name+UUID search, always confirm, partial success, filtered select all, separate category/tag actions, bidirectional hide/unhide, individual audit entries, auto-select on comma search, full toolkit (labels, age, notes) |
| 2026-03-26 | PRD Codex review completed | **2 blockers resolved, 4 important items fixed.** Key decisions: (1) Comma search uses exact match on bin name and UUID (not partial). (2) Mixed active+hidden selection uses split action — separate Hide/Unhide buttons with independent counts and modals. (3) Same permission gate for mass and single-bin edits (no new permission). Also added: standardized mass action UX pattern, per-feature dependencies table, selection persistence rules, double-submit protection, success metric baselines with measurement points. PRD is ready for SDD. |
| 2026-03-26 | SDD completed | **7 ADRs confirmed.** Key decisions: (1) Separate API endpoint per action type (9 endpoints). (2) Multiple JS files — 2 new (floatingBar.js, massEditModals.js) + main.js refactor. (3) Client-side comma search filtering. (4) No DB schema changes. (5) Bootstrap 5 modals for complex forms. (6) Selection cleared on filter change (except comma search). (7) **Migrate DataTables → Syncfusion EJ2 Grid** — follows TeamMemberGrid.js pattern, eliminates custom SelectionManager via native persistSelection + getSelectedRecords(). Architecture: layered extension of existing backstock module, transaction-wrapped batch processing, BatchResult response pattern. |
| 2026-03-26 | SDD Codex review completed | **2 blockers resolved, 3 important items fixed, 2 enhancements added.** Blockers: (1) PRD DataTables constraint updated to reflect approved Syncfusion Grid migration (ADR-7). (2) Security: removed userId from client API payload — sourced exclusively from $app->user->id server-side. Important: (3) Added explicit Action::create() logging for hide/unhide (Bin::hide()/activate() don't log internally). (4) Added full analytics event instrumentation mapping (6 PRD events mapped to frontend emit points with properties). (5) Fixed comma search UUID match counting bug in not-found reporting. Enhancements: (6) Documented select-all cross-page behavior with Syncfusion config details. (7) Added selection lifecycle reset documentation (in-memory only, clears on refresh/navigation). SDD is ready for Implementation Plan. |
| 2026-03-26 | PLAN completed | **7 phases defined with ~120 tasks.**  |
| 2026-03-26 | Phase 1 COMPLETED | All 9 BackstockFactory batch methods implemented with unit tests. 33 tests, 77 assertions passing. PHPStan clean. |
| 2026-03-26 | Phase 2 COMPLETED | All 9 REST endpoints implemented in backstock.php with helper functions (parseMassEditRequest, buildMassEditMessage). 24 route-level tests passing (43 mass edit tests total, 258 backstock tests total). PHPStan clean. userId sourced from session, checkStoreGroup on all routes. Files: backstock.php (routes), BackstockMassEditRoutesTest.php (tests), MassEditRouteHelpers.php (support). |
| 2026-03-26 | PLAN Codex review completed | **3 blockers resolved, 4 important items fixed.** Blockers: (1) Missing PRD Feature 2 "Selected X of Y" UI and header checkbox indeterminate state — added tasks in Phase 5 (T5.3.2 updated, T5.5.3-T5.5.4 added, T5.6.9-T5.6.11 browser tests). (2) Selection persistence on sort conflict (PRD says persist, SDD gotcha said clear) — resolved: Syncfusion `persistSelection` handles natively, added explicit test T3.4.8 and T3.7.8a. (3) Comma-search exception to filter clearing not explicit — added `isCommaSearchActive` flag (T3.4.7) and Phase 4 wiring (T4.2.10). Important fixes: (4) Analytics events underspecified — added `trackEvent()` utility task (T6.3.9), explicit per-event wiring tasks (T6.3.10-T6.3.12), moved `comma_search_used` to Phase 4 (T4.2.11), added `select_all_used` to Phase 5 (T5.5.4), `floating_bar_action_clicked` (T5.3.7). (5) Missing `massEditModals.js` include + include-order enforcement — fixed in T3.2.4. (6) No `[parallel: true]` tags — added to Phases 1, 3, 4, 5 + parallel execution map. (7) No Risks section or Definition of Done — added both. Plan is ~135 tasks across 7 phases. Ready for implementation. Phase structure: (1) Backend factory methods + unit tests (9 batch methods). (2) Backend API routes (9 endpoints). (3) Syncfusion Grid migration (DataTable → Grid, preserve all existing features). (4) Comma-separated search. (5) Floating action bar. (6) Mass edit modals + AJAX integration. (7) E2E validation + polish. Key sequencing: Phases 1-2 (backend) can partially overlap with Phase 3 (frontend Grid migration). Phases 4-6 are sequential (each depends on prior). Phase 7 validates everything. All tasks trace to PRD acceptance criteria and SDD specifications. |

## Context

Add mass edit capabilities to the backstock overview report (`backstock/home.html`). Features:
- Migrate from DataTables to Syncfusion EJ2 Grid (following TeamMemberGrid.js pattern)
- Multi-row selection via native Grid checkbox selection (`persistSelection: true`)
- Mass actions: change location, empty bins, change category/tag, hide/unhide bins, print labels, update age date, add notes
- Comma-separated bin # search to find specific bins for bulk actions
- Select All functionality for current page/filtered results
- Floating action bar for mass action triggers
- New bulk API endpoints (9 endpoints, current endpoints are single-bin only)

### Key Architecture Findings
- DataTable replaced by Syncfusion EJ2 Grid — native checkbox selection, persistSelection, getSelectedRecords()
- TeamMemberGrid.js (1495 lines) provides proven blueprint for Grid + bulk actions pattern
- All data is server-side rendered then filtered client-side
- Unified save endpoint exists (`/bin/:id/save-all/`) but is single-bin
- Bulk create pattern exists as precedent (`/bulkCreate`)
- Related tables: bsBins, bsLocations, bsCategories, bsBin_Cat, bsActions

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