diff --git a/.planning/phases/5-core-v2-features/5-CONTEXT.md b/.planning/phases/5-core-v2-features/5-CONTEXT.md new file mode 100644 index 00000000..790d0625 --- /dev/null +++ b/.planning/phases/5-core-v2-features/5-CONTEXT.md @@ -0,0 +1,207 @@ +--- +phase: 5 +name: Core V2 Features +scope: Revised (Batch Operations removed, Quick Quantity Adjustment added) +created: 2026-04-22 +--- + +# Phase 5 Context: Core V2 Features + +**Goal:** Implement must-have v2 features based on field feedback from Phase 4 deployments. + +**Status:** Context finalized, ready for planning + +--- + +## Scope (Locked) + +### REMOVED +- **Batch Operations** — Not applicable to sequential scanning workflow. Users process one item at a time: scan → verify → save → next item. Bulk multi-select/edit fundamentally conflicts with this workflow. + +### ADDED +- **Quick Quantity Adjustment** — Streamline check-in/check-out experience by eliminating modal friction + +### MAINTAINED +- **Search & Filtering** — Find items quickly in inventory +- **Export/Reports** — Admin tools for procurement and audit compliance + +--- + +## Feature Decisions + +### 1. Quick Quantity Adjustment + +**Decision: Hybrid UI approach** + +- **Keep +/- buttons** — Large tap targets for glove-friendly field operations +- **Add tap-to-edit on number display** — User can click/tap the quantity number to open inline input field for direct typing/pasting +- **Toggle between button taps and direct input** — Users choose fastest method for their situation + +**User workflow:** +1. User scans item → Item recognized in inventory +2. Quantity adjustment UI shown (no modal needed) +3. User either: + - Taps +/- buttons repeatedly, OR + - Taps number display → types quantity directly → Enter to confirm +4. Quantity saved immediately + +**Benefit:** Faster for field work, accommodates different user preferences, no modal overhead + +--- + +### 2. Search & Filtering + +#### 2a. Search UI & Flow + +**Decision: Modal-based search with item list** + +- **Search button** — New "Search" button on main inventory page (alongside existing "Scan" button) +- **Search modal** — Opens dedicated modal with: + - Search input field (text entry) + - Matched items displayed as vertical list below +- **Result interaction** — User taps matched item → opens existing quantity adjustment modal +- **Reuses workflows** — Leverages existing item details and quantity modal (no new modals) + +**Search triggers on:** Keystroke (real-time matching) OR Enter/Submit button + +**User workflow:** +1. User taps "Search" button on main page +2. Modal opens with search input +3. User types search text +4. Matched items appear as list below input +5. User taps an item → quantity adjustment modal opens +6. User adjusts quantity or views item details + +--- + +#### 2b. Search Scope + +**Decision: Search across all text fields** + +Search matches against these item fields: +- Item Name +- Part Number +- Barcode +- Description +- Category +- Notes +- Any future fields added to items + +**Rationale:** Field users may have different identifiers on hand. Broad search increases likelihood of finding the item quickly. + +--- + +#### 2c. Filtering + +**Decision: No filtering in Phase 5. Deferred to Phase 6+** + +- Search returns all matches across all categories and locations +- If field feedback shows filtering is critical, add Category + Location filters in next phase +- Keep Phase 5 scope focused on core search functionality + +--- + +### 3. Export/Reports + +**Audience:** Admins only (not field users) + +**Access:** Admin Dashboard (manual trigger, no scheduled exports) + +#### 3a. Inventory Snapshot Export + +**Purpose:** Procurement — Help admins decide what to buy next + +**Contents:** +- All current item fields (Name, PN, Category, Quantity, Location, Description, Type, Notes, etc.) +- Include ANY future fields added to items +- Single snapshot of current inventory state +- Users can open CSV/Excel and exclude unwanted columns + +**Filename format:** `inventory_snapshot_YYYY-MM-DD.csv` and `.xlsx` + +--- + +#### 3b. Audit Trail Export + +**Purpose:** Compliance & accountability — Track who changed what and when + +**Contents:** +- All audit log information (Date/Time, User, Item, Action, Quantity Changed, Notes, etc.) +- Include ANY future audit fields added to the system +- Complete transaction history from start of system +- Users can open CSV/Excel and exclude unwanted columns + +**Filename format:** `audit_trail_YYYY-MM-DD.csv` and `.xlsx` + +--- + +#### 3c. Export Format + +**Decision: Both CSV and Excel (.xlsx) formats** + +- **CSV** — Universal format, opens in any spreadsheet app +- **Excel** — More user-friendly (formatting, colors, filtering capabilities) +- **Filenames include timestamp** — Users can track which export is from which date +- **Both available simultaneously** — Admin chooses which format to download + +**Examples:** +- `inventory_snapshot_2026-04-22.csv` +- `inventory_snapshot_2026-04-22.xlsx` +- `audit_trail_2026-04-22.csv` +- `audit_trail_2026-04-22.xlsx` + +--- + +## Upstream Dependencies & Constraints + +### From Phase 4.1 (Spare Parts Search) +- Inventory list view is available and functional +- Item details modal exists and works +- Quantity adjustment modal exists (will be reused/adapted for quick adjust) + +### Technical Constraints (from PROJECT_ARCHITECTURE.md) +- Frontend: Next.js 15+, Tailwind CSS, TypeScript strict mode +- Backend: FastAPI, SQLite, Pydantic v2 +- UI: Premium fidelity (no UPPERCASE, Tailwind only, Lucide icons) +- Testing: Vitest for frontend, Pytest for backend + +### Non-negotiables (from AI_RULES.md) +- All API endpoints must have tests +- TypeScript strict mode +- No UPPERCASE in UI +- No decorative gradients or bold fonts +- Icon affordances (ChevronDown for dropdowns, etc.) + +--- + +## Deferred Ideas (Not Phase 5) + +- **Advanced filtering** (Category, Location, Date range) — Add if field feedback shows need +- **Bulk operations** — Confirmed not needed for sequential scanning workflow +- **Scheduled/automated exports** — Manual exports sufficient for Phase 5 +- **Real-time sync visualization** — Deferred to Phase 6+ +- **Export to cloud storage** — CSV/Excel download sufficient for Phase 5 + +--- + +## Questions for Planning + +When the planner reads this context, they should be able to answer: + +1. **Quick Quantity Adjustment** — Should this replace the modal entirely, or coexist alongside it for viewing item details? +2. **Search real-time vs submit** — Should search results update as user types, or require Enter/button click? +3. **Export generation** — Should exports be generated in-memory or queued as background jobs? +4. **Excel creation** — Library/method to generate .xlsx from Python backend? + +--- + +## Next Steps + +1. **Planning:** `/gsd-plan-phase 5` — Create detailed task breakdown for these three features +2. **Research:** Identify libraries for Excel export, validate search performance patterns +3. **Execution:** Implement features following task plan +4. **Verification:** UAT with field users for quick adjust UX, export format validation + +--- + +**Status:** ✓ Context complete, ready for planning phase