docs(5): phase 5 context finalized - quick quantity adjust, search, exports locked
This commit is contained in:
207
.planning/phases/5-core-v2-features/5-CONTEXT.md
Normal file
207
.planning/phases/5-core-v2-features/5-CONTEXT.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user