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