189 lines
5.4 KiB
Markdown
189 lines
5.4 KiB
Markdown
# 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`
|