# Specification: 005-store-navigation-redesign

## Status

| Field | Value |
|-------|-------|
| **Created** | 2026-02-05 |
| **Current Phase** | Phase 6 COMPLETED (Codex Reviewed) - Ready for Phase 7 |
| **Last Updated** | 2026-02-05 |

## Documents

| Document | Status | Notes |
|----------|--------|-------|
| product-requirements.md | completed | v1.1 - Codex reviewed, blockers resolved |
| solution-design.md | completed | v1.1.0 - Codex reviewed, blockers resolved |
| implementation-plan.md | completed | v1.1 - Codex reviewed, all blockers resolved |

**Status values**: `pending` | `in_progress` | `completed` | `skipped`

## Mockups

Interactive HTML mockups created:
- `mockups/navigation-concepts.html` - Three navigation pattern concepts (tabs, accordions, sidebar)
- `mockups/refined-bottom-tabs.html` - Refined bottom tabs design with all interactions

## Codex PRD Review (2026-02-05)

### Key Findings

**Blockers Resolved:**
1. ✅ Permission behavior contradictions → Added "Permission Visibility Model" section with single source of truth: hide inaccessible items entirely
2. ✅ Incomplete category→feature mapping → Added "Information Architecture" section with definitive mapping table
3. ✅ Badge data sources undefined → Added "Data Sources for Badges and Store List" section with providers, update mechanisms, latency expectations

**Important Issues Resolved:**
4. ✅ Problem impact claims unvalidated → Reframed as hypothesis with validation plan
5. ✅ Deep-linking scope ambiguous → Clarified: existing routes work, push notifications don't deep link this phase
6. ✅ Subjective acceptance criteria → Tied to specific values, `AppColors`, `AppTheme` tokens
7. ✅ Tab state on back navigation unclear → Specified: preserve last-selected tab, close sheet
8. ✅ Success metrics lack operational definitions → Added calculation formulas and event mappings

### PRD Version
Updated from v1.0 to v1.1 with revision history.

## Codex SDD Review (2026-02-05)

### Key Findings

**Blockers Resolved:**
1. ✅ Store switch failure handling → Fixed: Validate before navigate, keep current store on error (PRD-compliant)
2. ✅ Active tab toggle behavior → Added: Sheet lifecycle control (toggle on active tap, close on Home tap)
3. ✅ Debounce behavior → Fixed: Timer-based debounce-last-tap pattern (process last tap, not ignore all)

**Important Issues Resolved:**
4. ✅ Sheet animation specs → Added custom AnimationController for 350ms easeOutCubic
5. ✅ Swipe threshold → Documented DraggableScrollableSheet threshold implementation for 100dp
6. ✅ Badge data sources → Confirmed Ably subscription meets latency; noted Schedule badge polling gap
7. ✅ Badge 0 rendering → Fixed provider to return null (not 0) when count unavailable or zero
8. ✅ Out-of-scope clarification → Added Section 15 documenting "Could Have" and "Won't Have" features

**Enhancements Added:**
9. ✅ Edge cases → Added Section 17 covering rotation, store removal, offline mode, history race condition
10. ✅ Analytics tracking → Confirmed time_open_ms and dismiss_method properties in events

### Architectural Decisions Confirmed
- ✅ Session-only tab state (StateProvider)
- ✅ Reuse existing permission system
- ✅ Store access history in secure storage
- ✅ Presentation-only changes with shared state pattern

### SDD Version
Updated from v1.0.0 to v1.1.0 with revision history.

## Codex PLAN Review (2026-02-05)

### Key Findings

**Blockers Resolved:**
1. ✅ Missing analytics events → Added `store_detail_load` and `nav_back_from_feature` to Phase 6
2. ✅ SDD error-handling scenarios missing → Added permission error, store list failure, protected route tests to Phase 5
3. ✅ Schedule badge update mechanism → Decided Option B (push-triggered refresh), added implementation task
4. ✅ TDD gap in Analytics phase → Added T6.2 with tests for all 7 events before implementation

**Important Issues Resolved:**
5. ✅ Missing store-switching integration test → Added `store_switching_flow_test.dart` to Phase 7
6. ✅ Swipe threshold sequencing → Moved from Phase 4 to Phase 2.3 where CategoryBottomSheet is built
7. ✅ Task granularity → Split analytics wiring into per-widget tasks (T6.4.1-T6.4.7)

**Enhancements Added:**
8. ✅ Explicit Definition of Done per phase
9. ✅ Risk table expanded with latency, race condition, permission error risks
10. ✅ Parallel opportunities tagged (Phase 6 can run with Phase 5)
11. ✅ Explicitly deferred items documented (tab query-param, quick actions, tab order)

### PLAN Version
Updated from v1.0 to v1.1 with Codex review changes.

## Decisions Log

| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-02-05 | Visual mockups before PRD | User wanted to see designs before formalizing requirements |
| 2026-02-05 | Bottom tabs + sheets pattern | Familiar iOS/Android pattern, scales well, always-visible navigation |
| 2026-02-05 | Home tab = metrics dashboard | Keep rich dashboard content on first tab, other tabs show sheets |
| 2026-02-05 | Header dropdown for store switch | Clean, out of the way, standard UX pattern |
| 2026-02-05 | Hide inaccessible items (not disabled) | Reduces cognitive load, eliminates "how to unlock" questions, matches existing pattern |
| 2026-02-05 | Preserve tab on back navigation | Better UX than always returning to Home; matches iOS/Android conventions |
| 2026-02-05 | Validate store before navigate | PRD specifies no navigation on error; keep current store selected |
| 2026-02-05 | Debounce-last-tap pattern | PRD specifies processing last tap, not ignoring during window |
| 2026-02-05 | 7-phase implementation plan | TDD structure with parallel opportunities in Phase 2 for widgets |
| 2026-02-05 | Schedule badge via push notification | Option B per SDD - real-time updates vs 60s polling |
| 2026-02-05 | Tab query-param deferred | Optional enhancement; existing routes work without changes |
| 2026-02-05 | Sheet dismiss method `scrim_or_swipe` | Flutter cannot distinguish scrim tap from swipe; unified method name |
| 2026-02-05 | Navigation pop signals dismiss type | `Navigator.pop(true)` from items prevents false dismiss logging |

## Context

**Problem**: The current store detail screen uses a "Quick Actions" chip-based navigation that doesn't scale well with the growing feature set. Users have too many flat options to choose from without logical grouping.

**Current Features (flat chips)**:
- Buy Queue
- Completed
- Buyer Stats
- Store Metrics
- Close Reports
- Shift Notes
- Today's Tasks
- Edit Tasks
- Backstock

**Proposed Navigation Categories**:
1. **Buys** - Buy Queue, Completed, Buyer Stats
2. **Sales** - Store Metrics, Close Reports
3. **Store Operations** - Today's Tasks, Shift Notes, Backstock
4. **Scheduling** - (New category for manager scheduling features)

**Additional Considerations**:
- Multi-store switching - users may have access to multiple stores
- The data cards on the current screen are well-liked
- Need to maintain mobile-first UX principles

---
*This file is managed by the specification-management skill.*