From f5da563c29926912a95037740b3c1d53d9b0e713 Mon Sep 17 00:00:00 2001 From: ImBenji Date: Wed, 25 Mar 2026 17:18:10 +0000 Subject: [PATCH] first commit --- README.md | 189 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..fef86f6 --- /dev/null +++ b/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`