Planning reset: v2 roadmap and phase 4-7 structure
This commit is contained in:
81
.planning/PROJECT.md
Normal file
81
.planning/PROJECT.md
Normal file
@@ -0,0 +1,81 @@
|
||||
# TFM aInventory
|
||||
|
||||
## What This Is
|
||||
|
||||
A unified inventory management system combining web administration, field scanning (QR/barcode), AI-powered label extraction, and offline sync. Organizations use it to maintain accurate stock levels across distributed locations with minimal friction.
|
||||
|
||||
## Core Value
|
||||
|
||||
**One-click stock accuracy with minimal manual data entry** — Users scan items, AI extracts details, offline sync prevents data loss.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Validated
|
||||
|
||||
- ✓ Item CRUD with barcode/part number tracking — v1.0
|
||||
- ✓ QR/barcode scanning with html5-qrcode (offline) — v1.1
|
||||
- ✓ AI label extraction (Gemini 2.0 Flash) — v1.3
|
||||
- ✓ Multi-AI provider support (Claude 3.5 Sonnet as fallback) — v1.9.23
|
||||
- ✓ Offline sync with IndexedDB + UUID idempotency — v1.5
|
||||
- ✓ LDAP + PBKDF2 credential caching for offline auth — v1.4
|
||||
- ✓ Admin dashboard with user/category/config management — v1.10
|
||||
- ✓ Audit logging with immutable trails (no deletion) — v1.4
|
||||
- ✓ Image adjustment modal (rotation-only) for onboarding — v1.14.6
|
||||
- ✓ PWA with service workers + manifest (iOS/Android) — v1.3
|
||||
|
||||
### Active
|
||||
|
||||
- [ ] Define v2 feature priorities (0-3 months)
|
||||
- [ ] Clarify performance/scale requirements
|
||||
- [ ] User feedback integration from field deployments
|
||||
- [ ] Mobile UX refinements (touch gestures, small-screen affordances)
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- **Cropping functionality** — Non-essential for MVP; rotation covers 90% of use case
|
||||
- **Advanced analytics** — Deferred to v3; audit logs provide raw data
|
||||
- **Multi-warehouse federation** — Single-instance per organization; federation is v3+
|
||||
- **Custom field schemas** — Predefined Item/Category structure proven sufficient
|
||||
- **Real-time collaborative editing** — Not needed; async batch operations match field workflow
|
||||
|
||||
## Context
|
||||
|
||||
**Project Status:** v1.14.6 stable, phase 3 complete
|
||||
- Core platform shipping with ImageAdjustmentModal for better UX
|
||||
- Recent focus: simplifying image handling (removed unnecessary rotation modal double-apply, fixed canvas zoom/rotation)
|
||||
- Field deployments active; user feedback indicates system is working
|
||||
|
||||
**Tech Environment:**
|
||||
- Backend: FastAPI + SQLite + SQLAlchemy (Python 3.12+)
|
||||
- Frontend: Next.js 15 + Tailwind + Lucide Icons
|
||||
- PWA: Offline-first with service workers + IndexedDB
|
||||
- AI: Gemini 2.0 Flash (primary) + Claude 3.5 Sonnet (fallback)
|
||||
|
||||
**Known Issues:**
|
||||
- Feature prioritization unclear (too many options, no v2 direction)
|
||||
- Mobile UX polish needed (gesture handling, responsive edge cases)
|
||||
- Documentation gaps around config management and deployment
|
||||
|
||||
## Constraints
|
||||
|
||||
- **Tech Stack**: FastAPI, SQLite, Next.js — established; changing requires major rewrite
|
||||
- **AI Flexibility**: Support multiple providers (Gemini/Claude); single-provider lock-in is unacceptable
|
||||
- **Offline-First**: System MUST work without network; sync is async not real-time
|
||||
- **Auth Model**: LDAP + local credential caching; enterprise directory integration required
|
||||
- **Database**: SQLite only; multi-instance deployment not supported in v1-2
|
||||
- **UI Fidelity**: Premium aesthetics (Tailwind, Lucide, no UPPERCASE, no BOLD fonts)
|
||||
|
||||
## Key Decisions
|
||||
|
||||
| Decision | Rationale | Outcome |
|
||||
|----------|-----------|---------|
|
||||
| SQLite + file-based DB | Single-instance simplicity, zero ops overhead | ✓ Good — eliminates infrastructure burden |
|
||||
| Multi-AI providers (Gemini + Claude) | Resilience + cost optimization (fallback if primary fails) | ✓ Good — proven in production |
|
||||
| Offline-first sync with UUIDs | Field work often has spotty connectivity | ✓ Good — prevents data loss |
|
||||
| PBKDF2 credential caching | Support offline login without plaintext storage | ✓ Good — enterprise security + offline UX |
|
||||
| Rotation-only image adjustment (no crop) | Crop was non-functional UI; rotation covers real use case | ✓ Good — simplified modal, fixed zoom issues |
|
||||
| Service Worker PWA | Mobile field workers need installable app | ✓ Good — works on iOS/Android |
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2026-04-22 after reset (lost priority focus)*
|
||||
80
.planning/REQUIREMENTS.md
Normal file
80
.planning/REQUIREMENTS.md
Normal file
@@ -0,0 +1,80 @@
|
||||
# TFM aInventory — V2 Requirements
|
||||
|
||||
## V1 Foundation (Validated & Stable)
|
||||
|
||||
All v1 features are locked. These are proven valuable:
|
||||
|
||||
- ✓ Item inventory with barcode/part number/quantity tracking
|
||||
- ✓ Offline QR/barcode scanning
|
||||
- ✓ AI-powered label extraction from photos
|
||||
- ✓ LDAP authentication + credential caching for offline work
|
||||
- ✓ Admin dashboard (users, categories, config, audit logs)
|
||||
- ✓ PWA with offline sync (IndexedDB + UUID idempotency)
|
||||
- ✓ Image adjustment (rotation only) in onboarding flow
|
||||
- ✓ Audit logging (immutable, never deleted)
|
||||
|
||||
## V2 Scope — Phase 4 & 5 (TBD)
|
||||
|
||||
### Must-Have (Table Stakes)
|
||||
|
||||
- [ ] **Mobile UX Polish**: Responsive gesture handling, small-screen affordance fixes, touch-friendly controls
|
||||
- [ ] **Field User Research**: Validate assumptions from 1+ deployed locations; capture pain points
|
||||
- [ ] **Documentation**: Config management guide, deployment runbook, AI provider setup
|
||||
|
||||
### Should-Have (High Value)
|
||||
|
||||
- [ ] **Batch Operations UI**: Multi-item selection + bulk actions (stock adjustment, deletion, relocation)
|
||||
- [ ] **Search & Filtering**: Find items by name/PN/barcode; filter by category or location
|
||||
- [ ] **Export/Reports**: CSV export of inventory state, audit trails for compliance
|
||||
- [ ] **Box Label Printing**: Standardized thermal label layout (improve on current SVG generation)
|
||||
- [ ] **Deployment Docs**: Runbook for single-instance setup (Docker, LDAP integration, offline mode)
|
||||
|
||||
### Nice-to-Have (Deferred to V3)
|
||||
|
||||
- [ ] Advanced analytics (inventory trends, turnover rates)
|
||||
- [ ] Multi-warehouse support (federation, inter-location transfers)
|
||||
- [ ] Custom field schemas (Item type extension)
|
||||
- [ ] Real-time sync (WebSocket updates for concurrent admin sessions)
|
||||
- [ ] Localization (multi-language UI)
|
||||
|
||||
## Success Criteria
|
||||
|
||||
### For V2 Launch
|
||||
|
||||
- [ ] Mobile UX tested with 3+ field users; zero critical usability blockers
|
||||
- [ ] Documentation complete (setup, deployment, config)
|
||||
- [ ] Batch operations reduce bulk work by 50%+ compared to v1
|
||||
|
||||
### For Ongoing Stability
|
||||
|
||||
- [ ] Zero data loss incidents in offline sync (100% UUID idempotency)
|
||||
- [ ] Audit logs complete (all CRUD ops logged, deletions traced)
|
||||
- [ ] Performance: Scan-to-save < 2 seconds; bulk sync < 30 seconds
|
||||
|
||||
## Out of Scope (Rationale)
|
||||
|
||||
- **Cropping**: Rotation covers 90% of rotated/skewed image issues; add if feedback demands it
|
||||
- **Multi-tenancy**: Single-instance per organization; federation is v3+
|
||||
- **Real-time collab**: Async batch workflow matches field ops; collab adds complexity without value
|
||||
- **Custom field schemas**: Predefined Item/Category structure has proven sufficient in deployments
|
||||
|
||||
## Assumptions
|
||||
|
||||
- **Field deployments are active**: At least 1-2 live sites using v1.14.6
|
||||
- **LDAP available**: Enterprise directory integration is mandatory (no guest mode)
|
||||
- **SQLite sufficient**: Single-instance, no sharding/replication needed for v2
|
||||
- **AI providers stable**: Gemini + Claude APIs continue to be available and affordable
|
||||
- **Offline sync works**: UUID idempotency prevents data loss (validated in v1)
|
||||
|
||||
## Acceptance Criteria Template
|
||||
|
||||
For each requirement, specify:
|
||||
|
||||
- **What**: Feature description (1-2 sentences)
|
||||
- **Why**: Business/user value
|
||||
- **How**: Technical approach (can be refined during phase planning)
|
||||
- **Done**: Success metric (tests, UX validation, performance target)
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2026-04-22 during reset*
|
||||
117
.planning/ROADMAP.md
Normal file
117
.planning/ROADMAP.md
Normal file
@@ -0,0 +1,117 @@
|
||||
# TFM aInventory — V2 Roadmap
|
||||
|
||||
**Scope**: High-level phases (v1.14.6 → v2.0 stable). 3-4 quarters. User research + field validation drives next phases.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Field Validation & UX Polish (1 month)
|
||||
|
||||
**Goal**: Validate v1.14.6 in 2-3 field deployments; fix critical mobile UX issues.
|
||||
|
||||
**Deliverables**:
|
||||
- [ ] Deploy v1.14.6 to pilot sites (1-2 organizations)
|
||||
- [ ] Collect field user feedback (usability, missing features, pain points)
|
||||
- [ ] Fix mobile UX blockers (gesture handling, responsive breakpoints, accessibility)
|
||||
- [ ] Update docs: setup guide, deployment runbook, config reference
|
||||
|
||||
**Milestones**:
|
||||
- Week 1-2: Deployment + user kickoff
|
||||
- Week 3: Feedback synthesis; prioritize v2 features
|
||||
- Week 4: Ship v1.14.7 (UX fixes + docs)
|
||||
|
||||
**Success Criteria**:
|
||||
- [ ] 3+ field users validate core workflow (scan → extract → adjust → save)
|
||||
- [ ] Zero critical UX blockers on mobile (iOS/Android)
|
||||
- [ ] Docs complete enough for new admin to deploy without support
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Core V2 Features (2 months)
|
||||
|
||||
**Goal**: Implement must-have v2 features based on field feedback.
|
||||
|
||||
**Scope** (prioritized by field feedback):
|
||||
1. **Batch Operations** (1 month): Multi-select items, bulk adjust stock, batch delete
|
||||
2. **Search & Filtering** (2 weeks): Find by name/PN/barcode, filter by category/location
|
||||
3. **Export/Reports** (1 week): CSV export, audit trail reports
|
||||
|
||||
**Milestones**:
|
||||
- Week 1-4: Batch operations (backend + UI)
|
||||
- Week 5-6: Search/filtering
|
||||
- Week 7: Export/reports
|
||||
- Week 8: Testing + polish
|
||||
|
||||
**Success Criteria**:
|
||||
- [ ] Batch operations reduce bulk work by 50%+ (measured: 10-item adjustment now <30s)
|
||||
- [ ] Search finds any item in <500ms (even with 10K+ items)
|
||||
- [ ] Export covers audit logs + inventory snapshot
|
||||
- [ ] All new features tested (unit + integration)
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Deployment & Scale (1 month)
|
||||
|
||||
**Goal**: Production-ready multi-site deployment; scale testing.
|
||||
|
||||
**Scope**:
|
||||
- [ ] Docker containerization (if not already done)
|
||||
- [ ] Deployment automation (single-command setup)
|
||||
- [ ] Scale testing (10K+ items, 5+ concurrent users)
|
||||
- [ ] Performance optimization (if needed)
|
||||
- [ ] Backup/restore procedures documented
|
||||
|
||||
**Milestones**:
|
||||
- Week 1: Docker + compose file
|
||||
- Week 2: Automated deployment + smoke tests
|
||||
- Week 3: Scale testing + bottleneck identification
|
||||
- Week 4: Performance fixes + runbook finalization
|
||||
|
||||
**Success Criteria**:
|
||||
- [ ] Single command deploys complete stack
|
||||
- [ ] System handles 10K items + 5 concurrent scans (< 2s latency)
|
||||
- [ ] Backup/restore works; zero data loss on restore
|
||||
- [ ] Deployment docs complete (admin can onboard new site)
|
||||
|
||||
---
|
||||
|
||||
## Phase 7: V2 Release & Hardening (ongoing)
|
||||
|
||||
**Goal**: Launch v2.0; continuous stability improvements.
|
||||
|
||||
**Scope**:
|
||||
- [ ] Public v2.0 release (stable tag + CHANGELOG)
|
||||
- [ ] Ongoing field monitoring (error logs, sync health, performance)
|
||||
- [ ] Hotfixes for production issues
|
||||
- [ ] Feature suggestions → v3 backlog
|
||||
|
||||
**Success Criteria**:
|
||||
- [ ] Zero data loss incidents in first 30 days
|
||||
- [ ] 99%+ sync success rate
|
||||
- [ ] < 1% error rate in AI extraction (validated by users)
|
||||
- [ ] Docs remain current (update as issues emerge)
|
||||
|
||||
---
|
||||
|
||||
## Deferred to V3
|
||||
|
||||
- **Advanced analytics**: Trends, turnover, forecasting
|
||||
- **Multi-warehouse federation**: Inter-location transfers, distributed sync
|
||||
- **Custom field schemas**: Item type extension (CNPJ custom fields, etc.)
|
||||
- **Real-time collaboration**: WebSocket updates for concurrent admin sessions
|
||||
- **Localization**: Multi-language UI (Portuguese, Spanish, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Success Definition for V2.0 Launch
|
||||
|
||||
- [ ] Phase 4: Field validation complete; UX polish shipped
|
||||
- [ ] Phase 5: Must-have features implemented + tested
|
||||
- [ ] Phase 6: Deployment automated; scale tested
|
||||
- [ ] Phase 7: v2.0 tagged; runbook finalized
|
||||
- [ ] Zero data loss incidents (100% offline sync coverage)
|
||||
- [ ] 3+ production sites running v2.0
|
||||
- [ ] Documentation complete (setup, deployment, troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2026-04-22 during reset*
|
||||
91
.planning/STATE.md
Normal file
91
.planning/STATE.md
Normal file
@@ -0,0 +1,91 @@
|
||||
# Planning State — TFM aInventory V2 Reset
|
||||
|
||||
**Date**: 2026-04-22
|
||||
**Reset Type**: Lost priority focus / refocus on v2
|
||||
**Scope Preserved**: Mission, tech stack, validated features, constraints
|
||||
|
||||
---
|
||||
|
||||
## What Changed
|
||||
|
||||
### Why Reset Was Needed
|
||||
- Current phase (3) complete; unclear what v2 should prioritize
|
||||
- Too many potential features; no clear direction
|
||||
- Field deployments active but feedback not systematized
|
||||
|
||||
### What We Kept
|
||||
✓ Core mission: inventory + scanning + AI extraction + offline sync
|
||||
✓ Tech stack: FastAPI, SQLite, Next.js (no changes planned)
|
||||
✓ v1.14.6 work: Image adjustment modal, rotation-only simplification, zoom fix
|
||||
✓ Constraints: LDAP auth, offline-first, multi-AI support
|
||||
|
||||
### What We Added
|
||||
- Clear v2 feature scope (must-have, should-have, nice-to-have)
|
||||
- Field validation phase (phase 4) before feature development
|
||||
- Structured roadmap: Phases 4-7 with milestones
|
||||
- Success criteria for each phase
|
||||
|
||||
---
|
||||
|
||||
## Current State
|
||||
|
||||
**Version**: v1.14.6 stable
|
||||
**Branch**: dev
|
||||
**Last Work**: Session 33 (ImageAdjustmentModal rotation-only, zoom fixes)
|
||||
**Deployments**: 1-2 pilot sites using v1.14.6
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Phase 4 Planning** (`/gsd-plan-phase 4`):
|
||||
- Deploy v1.14.6 to pilot sites
|
||||
- Collect field feedback
|
||||
- Fix mobile UX blockers
|
||||
- Update deployment docs
|
||||
|
||||
2. **Phase 5 Planning** (after field validation):
|
||||
- Implement batch operations
|
||||
- Add search/filtering
|
||||
- Add export/reports
|
||||
- Based on field user feedback
|
||||
|
||||
3. **Ongoing**:
|
||||
- Monitor field deployments
|
||||
- Track issues/feedback
|
||||
- Adjust roadmap based on real user needs
|
||||
|
||||
---
|
||||
|
||||
## Key Assumptions
|
||||
|
||||
- Field users are actively using v1.14.6
|
||||
- LDAP + offline-first are non-negotiable requirements
|
||||
- SQLite is sufficient for v2 scope
|
||||
- AI providers (Gemini + Claude) remain stable and affordable
|
||||
- No multi-tenant or multi-warehouse needs in v2
|
||||
|
||||
---
|
||||
|
||||
## Decision Log
|
||||
|
||||
| Date | Decision | Rationale | Status |
|
||||
|------|----------|-----------|--------|
|
||||
| 2026-04-22 | Reset planning to phases 4-7 | Lost focus on v2 direction; field feedback needed | Active |
|
||||
| 2026-04-22 | Phase 4: Field validation first | Gather real user needs before building v2 features | Planned |
|
||||
| 2026-04-22 | Defer cropping, analytics, federation | Not needed for v2; revisit in v3 | Out of scope |
|
||||
|
||||
---
|
||||
|
||||
## Risk Register
|
||||
|
||||
| Risk | Impact | Mitigation |
|
||||
|------|--------|-----------|
|
||||
| Field users have different priorities than assumed | High | Phase 4 validation; adjust roadmap based on feedback |
|
||||
| SQLite hits scale limits with 10K+ items | Medium | Phase 6 scale testing; optimize queries if needed |
|
||||
| AI provider costs become prohibitive | Medium | Monitor usage; have fallback provider (Claude if Gemini fails) |
|
||||
| LDAP integration blocks new deployments | Medium | Phase 4 docs; simplify setup; provide troubleshooting guide |
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2026-04-22 after reset*
|
||||
24
.planning/config.json
Normal file
24
.planning/config.json
Normal file
@@ -0,0 +1,24 @@
|
||||
{
|
||||
"project": "TFM aInventory",
|
||||
"version": "2.0",
|
||||
"reset_date": "2026-04-22",
|
||||
"workflow": {
|
||||
"granularity": "high-level-phases",
|
||||
"git_strategy": "commit-planning-changes",
|
||||
"agent_preference": "claude"
|
||||
},
|
||||
"status": {
|
||||
"current_phase": 4,
|
||||
"current_version": "v1.14.6",
|
||||
"last_session": "Session 33 - ImageAdjustmentModal Integration",
|
||||
"branch": "dev"
|
||||
},
|
||||
"preserved": [
|
||||
"project_mission_vision",
|
||||
"tech_stack_decisions",
|
||||
"completed_features_as_validated",
|
||||
"known_constraints"
|
||||
],
|
||||
"reset_reason": "lost_track_of_priorities",
|
||||
"next_action": "gsd-plan-phase 4"
|
||||
}
|
||||
Reference in New Issue
Block a user