# Specification: 004-close-reports-frontend

## Status

| Field | Value |
|-------|-------|
| **Created** | 2026-01-26 |
| **Current Phase** | IMPLEMENTATION COMPLETE |
| **Completed** | 2026-01-26 |
| **Last Updated** | 2026-01-26 |

## Implementation Summary

| Metric | Count |
|--------|-------|
| **Total Tests** | 186 |
| **Unit Tests** | 113 |
| **Widget Tests** | 41 |
| **Screen Tests** | 12 |
| **Integration Tests** | 16 |
| **Route Tests** | 4 |
| **Test Coverage** | All PRD acceptance criteria verified |

## Phase Completion Status

| Phase | Status | Tests Added | Notes |
|-------|--------|-------------|-------|
| Phase 1: Data Layer | COMPLETED | 65 tests | Models, entities, mappers, datasource, repository |
| Phase 2: State Layer | COMPLETED | 27 tests | Providers with pagination, caching, comparison |
| Phase 3: UI Layer | COMPLETED | 62 tests | Screens, widgets, expandable sections |
| Phase 4: Navigation | COMPLETED | 4 tests | Routes, permission checks, store name flow |
| Phase 5: Integration | COMPLETED | 16 tests | End-to-end flows, PRD verification, analytics |

## PRD Acceptance Criteria Verification

| Requirement | ID | Status | Verification |
|-------------|-----|--------|--------------|
| View latest close report | M1 | PASS | Latest report screen with sales, buys, labor, discrepancy sections |
| Navigate to previous days via calendar | M2 | PASS | DateSelectorModal with available dates highlighted |
| Report detail with expandable sections | M3 | PASS | ExpandableSection widgets for each metric category |
| Compare reports with delta indicators | M4 | PASS | Comparison screen with VarianceChip and delta values |
| Discrepancy indicator badge | M5 | PASS | DiscrepancyBadge shown when hasDiscrepancy is true |

## Documents

| Document | Status | Notes |
|----------|--------|-------|
| product-requirements.md | completed | PRD created 2026-01-26 |
| solution-design.md | completed | SDD reviewed 2026-01-26 |
| implementation-plan.md | completed | v2.0.0 - All phases executed |

## Files Created/Modified

### Core Services
- `lib/core/services/close_reports/close_reports_analytics_service.dart` - Analytics event tracking

### Data Layer
- `lib/data/models/close_reports/` - Freezed models (summary, detail, comparison, calendar)
- `lib/domain/entities/close_reports/` - Equatable entities
- `lib/data/models/mappers/close_reports/` - Model-to-entity mappers with cents-to-dollars conversion
- `lib/data/datasources/close_reports/` - Remote datasource with error handling
- `lib/data/repositories/close_reports_repository_impl.dart` - Repository implementation

### State Layer
- `lib/presentation/providers/close_reports/close_reports_providers.dart` - All providers:
  - `closeReportsListProvider` - Paginated list with loadMore
  - `closeReportDetailProvider` - Single report detail
  - `latestCloseReportProvider` - Latest report
  - `closeReportCalendarProvider` - Calendar dates
  - `closeReportComparisonProvider` - Report comparison with auto-swap
  - `selectedReportDateProvider` - UI state
  - `reportSectionExpandedProvider` - Section expansion state

### UI Layer
- `lib/presentation/screens/close_reports/`:
  - `close_reports_screen.dart` - Main list screen
  - `close_report_detail_screen.dart` - Detail screen
  - `close_report_comparison_screen.dart` - Comparison screen
- `lib/presentation/widgets/close_reports/`:
  - `close_report_list_tile.dart` - Report list item
  - `key_metrics_summary.dart` - Key metrics display
  - `expandable_section.dart` - Collapsible sections
  - `variance_chip.dart` - Delta indicator
  - `discrepancy_badge.dart` - Discrepancy warning
  - `quick_compare_buttons.dart` - vs Yesterday/Last Week
  - `date_selector_modal.dart` - Calendar date picker

### Test Files
- `test/data/models/close_reports/`
- `test/data/models/mappers/close_reports/`
- `test/data/datasources/close_reports/`
- `test/data/repositories/close_reports_repository_test.dart`
- `test/presentation/providers/close_reports/`
- `test/presentation/widgets/close_reports/`
- `test/presentation/screens/close_reports/`
- `test/router/close_reports_routes_test.dart`
- `test/integration/close_reports_integration_test.dart`

## Analytics Events Implemented

| Event | Trigger |
|-------|---------|
| `close_reports_viewed` | List screen loads |
| `close_report_detail_viewed` | Detail screen loads |
| `close_report_comparison_viewed` | Comparison screen loads |
| `date_selected` | User selects date from calendar |
| `close_report_calendar_opened` | Calendar modal opens |
| `close_report_section_toggled` | Expand/collapse section |
| `close_report_comparison_started` | Quick compare button tap |
| `close_reports_load_more` | Pagination triggered |
| `close_reports_retry` | Error retry button tap |
| `close_report_error` | Error occurrence |
| `close_reports_api_latency` | API call completion |

## Known Issues / Future Enhancements

1. **Discrepancy Type**: API only provides boolean flag, not discrepancy type. UI shows generic "Cash Discrepancy" label.
2. **Offline Support**: Not implemented - feature requires network connectivity.
3. **Export/Print**: Not in scope for initial release - could be added in future iteration.

## Decisions Log

| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-01-26 | ADR-1: Reuse SchedulingApiClient | Shares JWT auth infrastructure |
| 2026-01-26 | ADR-2: Cents-to-Dollars at Mapper Layer | Single conversion point |
| 2026-01-26 | ADR-3: Family Providers with Equatable Params | Type-safe caching |
| 2026-01-26 | ADR-4: Session-Scoped State Persistence | Per PRD requirements |
| 2026-01-26 | Phase 5 Complete | All integration tests passing, PRD verified |

## Context

**User Request**: Implement the frontend for the Close Reports where we can see the latest close report and get them for previous days.

**Feature Scope**:
- View latest close report for a store
- Navigate to view close reports from previous days
- Integration with existing store detail navigation

## Backend API Reference

- **API Documentation**: `docs/backend-api-updates.md` (Close Reports section)
- **Base URL**: `https://api.buyerkiosk.com/api/mobile/close-reports`
- **Endpoints**: list, detail, latest, calendar, compare

---
*Implementation completed 2026-01-26. All 5 phases executed successfully.*