From 5e7318c7f6db47e68308b79b55074732d5c616a6 Mon Sep 17 00:00:00 2001 From: Daniel Bedeleanu Date: Wed, 22 Apr 2026 15:56:47 +0300 Subject: [PATCH] Planning reset: v2 roadmap and phase 4-7 structure --- .planning/PROJECT.md | 81 ++++++++++++++++++++++++++ .planning/REQUIREMENTS.md | 80 ++++++++++++++++++++++++++ .planning/ROADMAP.md | 117 ++++++++++++++++++++++++++++++++++++++ .planning/STATE.md | 91 +++++++++++++++++++++++++++++ .planning/config.json | 24 ++++++++ 5 files changed, 393 insertions(+) create mode 100644 .planning/PROJECT.md create mode 100644 .planning/REQUIREMENTS.md create mode 100644 .planning/ROADMAP.md create mode 100644 .planning/STATE.md create mode 100644 .planning/config.json diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md new file mode 100644 index 00000000..d8b4f408 --- /dev/null +++ b/.planning/PROJECT.md @@ -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)* diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md new file mode 100644 index 00000000..94094732 --- /dev/null +++ b/.planning/REQUIREMENTS.md @@ -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* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 00000000..1d222da2 --- /dev/null +++ b/.planning/ROADMAP.md @@ -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* diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 00000000..e2855a32 --- /dev/null +++ b/.planning/STATE.md @@ -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* diff --git a/.planning/config.json b/.planning/config.json new file mode 100644 index 00000000..52d6b93b --- /dev/null +++ b/.planning/config.json @@ -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" +}