first commit

README.md

@@ -0,0 +1,189 @@
+# Bus Running Record (BRR) App
+
+A Flutter mobile app for rail replacement controllers to generate and fill Bus Running Reports (BRRs) from schedule documents. Eliminates manual data entry by parsing schedule files and providing a streamlined interface for completing required fields.
+
+## Features
+
+### Implemented (MVP)
+
+- **Schedule Upload & Parsing**
+  - Upload .docx schedule documents
+  - Parse Arriva schedule format to extract trip data
+  - Extract trip numbers, duty numbers, running numbers, fleet numbers, and scheduled times
+  - Error handling for invalid/unparseable files
+
+- **Trip List View**
+  - Display all parsed trips in scrollable list
+  - Show pre-filled data from schedule
+  - Expandable trip cards for detailed view
+  - Real-time completion status tracking
+
+- **Data Entry Interface**
+  - Quick entry for actual departure time and fleet number
+  - "Same as scheduled" and "As planned" buttons for quick filling
+  - Auto-save functionality using local storage
+  - Input validation
+
+- **BRR Export**
+  - Generate Excel (.xlsx) files in BRR template format
+  - Include all trip data (scheduled and actual)
+  - Preserve BRR template formatting
+  - Share functionality via system share sheet
+
+## Architecture
+
+### Project Structure
+
+```
+lib/
+├── main.dart                    # App entry point with routing
+├── models/                      # Data models
+│   ├── trip.dart               # Trip data model
+│   ├── brr_metadata.dart       # BRR metadata model
+│   └── brr_state.dart          # App state model
+├── parsers/                     # Schedule parsers
+│   ├── schedule_parser.dart    # Parser interface
+│   └── arriva_schedule_parser.dart  # Arriva format parser
+├── exporters/                   # Excel exporters
+│   ├── brr_exporter.dart       # Exporter interface
+│   └── arriva_brr_exporter.dart # Arriva BRR exporter
+├── services/                    # Business logic services
+│   ├── brr_export_service.dart # Export service with validation
+│   └── storage_service.dart    # Local storage service
+├── validators/                  # Data validators
+│   └── trip_validator.dart     # Trip data validator
+├── pages/                       # UI screens
+│   ├── home_page.dart          # Upload screen
+│   └── trip_list_page.dart     # Trip list and editing screen
+└── exceptions/                  # Custom exceptions
+    └── schedule_parse_exception.dart
+```
+
+### Key Components
+
+#### Parsers
+- **ArrivaScheduleParser**: Parses Arriva .docx schedules using regex patterns
+  - Handles regular trips and finishing trips
+  - Extracts all required fields from trip lines
+  - Time formatting (HHMM → HH:MM)
+
+#### Exporters
+- **ArrivaBRRExporter**: Generates Excel files in BRR format
+  - Creates proper header structure
+  - Populates trip data
+  - Applies cell formatting and column widths
+  - Saves to device storage
+
+#### Services
+- **BRRExportService**: Validates and exports BRRs
+  - Pre-export validation
+  - Error handling and reporting
+- **StorageService**: Auto-save using SharedPreferences
+  - Persists trip data locally
+  - Restores state on app restart
+
+## Dependencies
+
+- **flutter**: Flutter framework
+- **go_router**: Navigation and routing
+- **file_picker**: Document file selection
+- **docx_to_text**: Parse .docx files
+- **excel**: Generate Excel files
+- **share_plus**: Share files via system share sheet
+- **path_provider**: File system access
+- **shared_preferences**: Local data persistence
+
+## Getting Started
+
+### Prerequisites
+
+- Flutter SDK 3.10.0 or higher
+- Dart SDK 2.18 or higher
+- Android Studio / Xcode for platform-specific builds
+
+### Installation
+
+1. Clone the repository
+2. Install dependencies:
+   ```bash
+   flutter pub get
+   ```
+3. Run the app:
+   ```bash
+   flutter run
+   ```
+
+### Building for Release
+
+**Android:**
+```bash
+flutter build apk --release
+```
+
+**iOS:**
+```bash
+flutter build ios --release
+```
+
+## Usage
+
+1. **Upload Schedule**
+   - Tap "Upload Schedule (.docx)" on home screen
+   - Select an Arriva schedule .docx file
+   - App will parse and display trip count
+
+2. **Fill Trip Data**
+   - View list of all parsed trips
+   - Tap a trip card to expand
+   - Enter actual departure time and fleet number
+   - Use quick-fill buttons for common cases
+   - Data auto-saves as you work
+
+3. **Export BRR**
+   - Tap "Export BRR" when all trips are complete
+   - Excel file is generated and saved
+   - Option to share via email, messaging, etc.
+
+## MVP Scope
+
+This is the MVP (Minimum Viable Product) version focused on:
+- Arriva schedule format only
+- Basic validation
+- Local storage only
+- No cloud sync
+- No user authentication
+
+## Future Enhancements
+
+- Support for multiple TOC formats (First, Stagecoach, National Express)
+- Multi-route support in single session
+- Historical BRR archive
+- Analytics and reports
+- Real-time collaboration
+- Cloud sync
+- Photo upload with OCR
+- Integration with radio/messaging systems
+
+## Testing
+
+The app has been developed according to the MVP specification in `MVP.md`.
+
+### Test Scenarios
+
+1. Upload valid Arriva schedule → correct trip parsing
+2. Parse trips → all fields populated correctly
+3. Enter actual times/fleet → data saved
+4. Export BRR → valid Excel file generated
+5. Re-open app → previous data persisted
+
+## Contributing
+
+This is a private project developed for rail replacement controllers.
+
+## License
+
+Private - All rights reserved
+
+## Credits
+
+Developed according to specifications in `MVP.md`