doc(readme): make the README remotely useful

README.md

@@ -1,17 +1,42 @@
 # oeffimaster
 
-A new Flutter project.
+Aggregating information to create your own routes in public transit effortlessly.
 
-## Getting Started
 
-This project is a starting point for a Flutter application.
+## Goal of this project
+Do you ever get a route from google maps and see a 13 minute switch time, for a train that comes every ten minutes? Do you then prompt another app with better results. What if you'd normally have to wait 9 minutes for your train, but the previous train is late, so in reality you can switch with only a minutes worth of waiting? Now you can get an earlier train for the next connection, and suddenly the 3rd-fastest connection in google's algorithm becomes the fastest, and you saved 10 minutes - or could have, if you knew.
+My app will not solve this issue.
+As someone who is familiar with good chunks of the cities public transport network, I often enough *think* I can get faster to my target than the routing served by commonplace apps, but I have a hard time of knowing that for sure. Other apps allow some degree of comparing routes to one another, but it's not a priority, and editing any part of it is not supported at all.
+Oeffimaster aims to make that type of information easily accessible and aggregate it in the most helpful way, allowing comparison and editing of routes.
 
-A few resources to get you started if this is your first Flutter project:
+## Usage
+I am currently providing artifacts for linux and android. To make your own builds, you will need an api key for your network.
 
-- [Learn Flutter](https://docs.flutter.dev/get-started/learn-flutter)
-- [Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
-- [Flutter learning resources](https://docs.flutter.dev/reference/learning-resources)
+## Build the project
 
-For help getting started with Flutter development, view the
-[online documentation](https://docs.flutter.dev/), which offers tutorials,
-samples, guidance on mobile development, and a full API reference.
+### Get the API key
+For the VBB network in Berlin/Brandenburg
+
+1. Installing flutter: https://docs.flutter.dev/install/quick
+2. Get an API key for VBB: https://unternehmen.vbb.de/digitale-services/api/
+    It will take some time, but they will send you an API key and the url to access it.
+    this should work for other public transit networks using the HAFAS api, but you will have to test this yourself
+
+### The build part
+Create a `.env` in the project root and add
+```env
+VBB_API_KEY=
+VBB_API_URL=
+```
+For local builds and connected devices simply run `flutter run` in your terminal.
+
+To build for linux:
+```bash
+flutter build linux -DVBB_API_KEY={API_KEY} -DVBB_API_URL={API_URL}
+
+```
+
+To build for android:
+```
+flutter build apk -DVBB_API_KEY={API_KEY} -DVBB_API_URL={API_URL}
+```

android/app/src/main/AndroidManifest.xml

@@ -1,4 +1,5 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.INTERNET"/>
     <application
         android:label="oeffimaster"
         android:name="${applicationName}"
@@ -42,4 +43,4 @@
             <data android:mimeType="text/plain"/>
         </intent>
     </queries>
-</manifest>
+</manifest>

doc/diagrams/ERDiagram.mmd

@@ -0,0 +1,64 @@
+erDiagram
+journey||--|{routesegments: "consists of"
+routesegments||--||segment: "sorts"
+segment||--|{departure: "consists of"
+departure}|--|{station: "originates from"
+departure}|--||vehicle: uses
+vehicle||..|{line: "shared data"
+segment}|--||vehicle: uses
+stationlines}|..||station: "general connections"
+stationlines}|..||line: groups
+
+
+journey {
+  int id PK
+  string startstation
+  string endstation
+}
+routesegments {
+  int id PK
+  int journey FK
+  int segment FK
+  int segmentorder
+}
+segment {
+  int id PK
+  string ref
+  int startid FK
+  int endid FK
+  string vehicleid FK
+}
+departure {
+  int id PK
+  string ref
+  string direction
+  string vehicle FK
+  string vehiclename
+  string station FK
+  string stationname
+  string arrivaltime
+  string departuretime
+}
+station {
+  string id PK
+  string name
+}
+stationlines {
+  int id PK
+  string stationid FK
+  string lineid FK
+}
+vehicle {
+  string vehicleid PK
+  string name
+  string line FK
+}
+line {
+  string lineid PK
+  string name
+  string mode
+  string destination
+  string direction
+  string fgcolor
+  string bgcolor
+}

doc/diagrams/flowchart_to_journey.mmd

@@ -0,0 +1,8 @@
+flowchart TD
+Start-->stat[Search Station]-->selstat[Select station]
+selstat-->seldep["`Select departure:
+vehicle, direction & time`"]
+seldep-->selarr["`Select arrival station:
+when & where to exit`"] --> sw{switch?} --yes-->seldep
+sw--"no"-->fin([journey details])
+

doc/diagrams/sequencediagram.mmd

@@ -0,0 +1,19 @@
+sequenceDiagram
+  participant api@{ "type": "entity"} as public transport API
+  participant ah as api_handler
+  participant ui as UI
+  participant th as transport_helper
+  participant db@{ "type":"database"} as database
+
+ui-->>ah: find Station
+ah-->>api: GET request w/ stationname
+api-->>ah: return json
+ah-->>th: provide json Map
+th-->>db: store object
+db-->>th: return id
+th-->>ah: return object
+ah-->>ui: display data
+
+
+
+

doc/project_and_design/requirements.md

@@ -1,10 +1,10 @@
-- running mobile app
-- users should be able to
-	- plan public transport in the VBB transit network
-	- create and customise routes quickly and on-the-fly
-	- edit routes from anywhere, where respective route information can be seen
-	- compare routes easily, especially between different endpoints
-- the app should offer up the information most relevant to current route planning
-	- between route steps, there should be no more than 3 taps required, optimally even just one(1), scrolling excluded
-	- e.g. only lines that connect to a station should be shown
-	- stations that a line goes through should be available as next node/ step for planning
+- [x] running mobile app
+- [ ] users should be able to
+	- [~] plan public transport in the VBB transit network
+	- [~] create and customise routes quickly and on-the-fly
+	- [ ] edit routes from anywhere, where respective route information can be seen
+	- [ ] compare routes easily, especially between different endpoints
+- [~] the app should offer up the information most relevant to current route planning
+	- [x] between route steps, there should be no more than 3 taps required, optimally even just one(1), scrolling excluded
+	- [x] e.g. only lines that connect to a station should be shown
+	- [x] stations that a line goes through should be available as next node/ step for planning

lib/api_handler.dart

@@ -6,19 +6,19 @@ import 'dart:convert';
 
 import 'transport_helper.dart';
 
+String timeOf(DateTime fullDT) {
+  // doing it this way so we always get two digits on the hour
+  String full = fullDT.toString();
+  List<String> splits = full.split(" ")[1].split(":");
+  String time = '${splits[0]}:${splits[1]}';
+  return time;
+}
+
 class ApiHandler {
   // TODO: Split next line for better Error Handling
   static final String baseUrl = dotenv.get("VBB_API_URL");
   static final String accessID = dotenv.get("VBB_API_KEY");
 
-  // TODO: function calls for the following API calls
-  //   - [x] location.name: findStations
-  //   - [ ] location.nearbystops
-  //   - [ ] location.details
-  //   - [ ] departureBoard
-  //   - [ ] multiDepartureBoard
-  //   - [ ] journeyDetails
-
   //static Future<Map<String, dynamic>> findStations(String locationName) async {
   static Future<List<Station>> findStations(
     String locationName, {
@@ -79,6 +79,7 @@ class ApiHandler {
   static Future<List<Departure>> departures(
     String stationId, {
     int? maxDepartures = -1,
+    DateTime? time,
     int? duration = 0,
   }) async {
     String urlPath = '/api/fahrinfo/latest/departureBoard';
@@ -87,7 +88,9 @@ class ApiHandler {
     Uri url = Uri.https(baseUrl, urlPath, {
       'accessId': accessID,
       'id': stationString,
-      ////'time': /current time //time from which departures will be shown
+      'time': timeOf(
+        time ?? DateTime.now(),
+      ), //time from which departures will be shown
       'duration': duration.toString(), //interval time in minutes
       'maxJourneys': maxDepartures.toString(),
       //'type': 'S', // Station/Stops only

lib/main.dart

@@ -4,12 +4,12 @@ import 'api_handler.dart';
 import 'transport_helper.dart';
 import 'dart:async';
 
-import 'package:sqflite_common_ffi/sqflite_ffi.dart'; //for testing on desktop
+// import 'package:sqflite_common_ffi/sqflite_ffi.dart'; //for testing on desktop
 
 void main() async {
   await dotenv.load();
   const String dbName = "oeffimasterTransportDb";
-  databaseFactory = databaseFactoryFfi; // for debugging and desktop test
+  // databaseFactory = databaseFactoryFfi; // for debugging and desktop test
   DbHelper.initDb(dbName);
   runApp(const MyApp());
 }
@@ -273,9 +273,11 @@ class StationList extends StatelessWidget {
 class ChooseDeparturePage extends StatefulWidget {
   final Station startStation;
   final int? journeyId;
+  final Departure? arrival;
   const ChooseDeparturePage({
     super.key,
     this.journeyId,
+    this.arrival,
     required this.startStation,
   });
 
@@ -288,7 +290,10 @@ class _ChooseDeparturePageState extends State<ChooseDeparturePage> {
   Journey? singleJourney;
 
   void loadDepartures(Station startStation) async {
-    departureList = await ApiHandler.departures(startStation.id);
+    departureList = await ApiHandler.departures(
+      startStation.id,
+      time: widget.arrival?.arrivalTime ?? DateTime.now(),
+    );
     setState(() {});
   }
 
@@ -330,17 +335,26 @@ class _ChooseDeparturePageState extends State<ChooseDeparturePage> {
                 ),
               ),
             ),
-            ElevatedButton(
-              onPressed: () {
-                if (widget.journeyId != null) {
-                  loadJourney(widget.journeyId as int);
-                }
-              },
-              child: const Text('Finish Route'),
-            ),
+            // ElevatedButton(
+            //   onPressed: () {
+            //     if (widget.journeyId != null) {
+            //       loadJourney(widget.journeyId as int);
+            //     }
+            //   },
+            //   child: const Text('Finish Route'),
+            // ),
           ],
         ),
       ),
+      floatingActionButton: FloatingActionButton(
+        onPressed: () {
+          if (widget.journeyId != null) {
+            loadJourney(widget.journeyId as int);
+          }
+        },
+        tooltip: 'Finish route',
+        child: const Icon(Icons.check),
+      ),
     );
   }
 
@@ -470,6 +484,7 @@ class _ChooseArrivalPageState extends State<ChooseArrivalPage> {
         builder: (context) => ChooseDeparturePage(
           startStation: startStation,
           journeyId: journeyId,
+          arrival: arrival,
         ),
       ),
     );
@@ -528,7 +543,31 @@ class _JourneyDetailPageState extends State<JourneyDetailPage> {
     return Scaffold(
       appBar: AppBar(title: Text('Connection Details \n$duration')),
       body: Center(
-        child: SegmentList(journey: widget.singleJourney),
+        child: Column(
+          mainAxisAlignment: MainAxisAlignment.center,
+          children: [
+            Expanded(
+              child: SizedBox(
+                height: 400,
+                child: SegmentList(journey: widget.singleJourney),
+              ),
+            ),
+            Container(
+              margin: const EdgeInsets.only(bottom: 60.0),
+              child: ElevatedButton(
+                onPressed: () {
+                  Navigator.pop(
+                    context,
+                    MaterialPageRoute(
+                      builder: (context) => JourneyOverviewPage(),
+                    ),
+                  );
+                },
+                child: const Text('View all Journeys'),
+              ),
+            ),
+          ],
+        ),
       ),
     );
   }
@@ -596,6 +635,16 @@ class _JourneyOverviewPageState extends State<JourneyOverviewPage> {
         child: Column(
           mainAxisAlignment: MainAxisAlignment.center,
           children: [
+            Container(
+              padding: EdgeInsets.only(left: 30, top: 50),
+              width: 500.0,
+              height: 100.0,
+              child: FittedBox(
+                fit: BoxFit.contain,
+                alignment: Alignment.centerLeft,
+                child: Text("Your Journeys"),
+              ),
+            ),
             FutureBuilder(
               future: loadJourneys(),
               builder: (context, snapshot) {
@@ -648,17 +697,17 @@ class _JourneyOverviewPageState extends State<JourneyOverviewPage> {
                 );
               },
             ),
-            ElevatedButton(
-              onPressed: () {
-                Navigator.push(
-                  context,
-                  MaterialPageRoute(
-                    builder: (context) => ChooseStationPage(),
-                  ),
-                );
-              },
-              child: const Text('Start a route'),
-            ),
+            // ElevatedButton(
+            //   onPressed: () {
+            //     Navigator.push(
+            //       context,
+            //       MaterialPageRoute(
+            //         builder: (context) => ChooseStationPage(),
+            //       ),
+            //     );
+            //   },
+            //   child: const Text('Start a route'),
+            // ),
           ],
         ),
       ),

lib/transport_helper.dart

@@ -41,11 +41,11 @@ class DbHelper {
   }
 }
 
-/// this class covers two database tables: "route" and "routesegments"
-/// while route will for now only hold an id, routesegments will store the
-/// m-n/ 1-n relations between routes and segments - the segments contain the most
-/// relevant info, while routesegments stores which route the segments belong to
-/// and in which order they make up a route
+/// this class covers two database tables: "journey" and "routesegments"
+/// while journey will for now only hold an id, routesegments will store the
+/// m-n/ 1-n relations between journeys and segments - the segments contain the most
+/// relevant info, while routesegments stores which journey the segments belong to
+/// and in which order they make up a journey
 class Journey {
   static const String tableName = "journey";
   // TODO: add last_viewed, last_modified and such
@@ -63,7 +63,7 @@ class Journey {
     required this.duration,
   });
 
-  /// toMap for Journey but it's just route ids for now
+  /// toMap for Journey but it's just journey ids for now
   Map<String, Object?> _toMapJourney() {
     return {"id": id, "startstation": startStation, "endstation": endStation};
   }
@@ -74,7 +74,7 @@ class Journey {
     List<Map<String, Object?>> tmp = [];
     for (final (segmentIdx, segment) in segments.indexed) {
       tmp.add({
-        "route": id,
+        "journey": id,
         "segment": segment.id,
         "segmentorder": segmentIdx,
       });
@@ -91,13 +91,13 @@ class Journey {
   }
 
   factory Journey.fromMap(
-    Map<String, Object?> routeMaps,
+    Map<String, Object?> journeyMaps,
     List<Segment> segmentMaps,
   ) {
     return Journey(
-      id: routeMaps["id"] as int,
-      startStation: routeMaps["startstation"] as String?,
-      endStation: routeMaps["endstation"] as String?,
+      id: journeyMaps["id"] as int,
+      startStation: journeyMaps["startstation"] as String?,
+      endStation: journeyMaps["endstation"] as String?,
       segments: segmentMaps,
       duration: Duration(minutes: 0),
     );
@@ -138,10 +138,10 @@ class Journey {
         segments.last.end.arrivalTime,
       );
     } else {
-      // if the route has no segments yet, at least the startStation should remain,
+      // if the journey has no segments yet, at least the startStation should remain,
       // otherwise delete the thing
       // having a startStation makes the first step faster at least
-      // no need to put a mostly empty route into the db though
+      // no need to put a mostly empty journey into the db though
       endStation = null;
       duration = Duration(minutes: 0);
     }
@@ -187,9 +187,7 @@ class Journey {
     database.execute("""CREATE TABLE IF NOT EXISTS '$tableName'(
     id            INTEGER PRIMARY KEY AUTOINCREMENT,
     startstation  TEXT,
-    endstation    TEXT,
-    FOREIGN KEY (startstation) REFERENCES station(name)
-    FOREIGN KEY (endstation) REFERENCES station(name)
+    endstation    TEXT
     );
     """);
   }
@@ -199,7 +197,7 @@ class Journey {
     String segment = Segment.tableName;
     database.execute("""CREATE TABLE IF NOT EXISTS routesegments(
     id            INTEGER PRIMARY KEY AUTOINCREMENT,
-    route         INTEGER,
+    journey         INTEGER,
     segment       INTEGER,
     segmentorder  INTEGER, -- TODO: implement sorting
     FOREIGN KEY('$tableName') REFERENCES '$tableName'(id),
@@ -216,9 +214,9 @@ class Journey {
       where: "id = ?",
       whereArgs: [id],
     );
-    assert(result.length < 2, "found more than 1 route for id $id");
-    Journey route = Journey.fromMap(result.first, await routeSegments);
-    return route;
+    assert(result.length < 2, "found more than 1 journey for id $id");
+    Journey journey = Journey.fromMap(result.first, await routeSegments);
+    return journey;
   }
 
   /// gets routesegments and hands them to the Journey.fromMap factory, works async
@@ -244,14 +242,14 @@ class Journey {
   }
 
   static Future<List<Segment>> _dbGetJourneySegments(
-    int routeId,
+    int journeyId,
   ) async {
     Database database = DbHelper.db;
     String segment = Segment.tableName;
     var tmp = await database.rawQuery("""
         SELECT * FROM '$segment'
         JOIN routesegments ON routesegments.segment = '$segment'.id
-        WHERE routesegments.route = '$routeId'
+        WHERE routesegments.journey = '$journeyId'
         ORDER BY routesegments.segmentorder ASC;
         """);
 
@@ -273,15 +271,15 @@ class Journey {
     return id_tmp;
   }
 
-  static void dbAppendJourneySegment(int routeId, int segmentid) {
+  static void dbAppendJourneySegment(int journeyId, int segmentid) {
     Database database = DbHelper.db;
-    // generate segmentorder to be 0 if no segment exists for route, otherwise
-    // take highest segmentorder+1 for given route
+    // generate segmentorder to be 0 if no segment exists for journey, otherwise
+    // take highest segmentorder+1 for given journey
     database.rawInsert(
-      """INSERT INTO routesegments(route, segment, segmentorder) VALUES
-      ($routeId, $segmentid, CASE WHEN EXISTS (
-        SELECT segmentorder FROM routesegments r WHERE r.route=$routeId) THEN (
-        SELECT segmentorder AS so FROM routesegments r WHERE r.route=$routeId
+      """INSERT INTO routesegments(journey, segment, segmentorder) VALUES
+      ($journeyId, $segmentid, CASE WHEN EXISTS (
+        SELECT segmentorder FROM routesegments r WHERE r.journey=$journeyId) THEN (
+        SELECT segmentorder AS so FROM routesegments r WHERE r.journey=$journeyId
           ORDER BY so DESC LIMIT 1) +1 ELSE 0 END);
     """,
     );
@@ -322,7 +320,7 @@ class Journey {
       database.update(
         "routesegments",
         routeSegments[i],
-        where: "route = ? AND segmentoder = ?",
+        where: "journey = ? AND segmentoder = ?",
         whereArgs: [id, i],
       );
     }
@@ -342,7 +340,7 @@ class Journey {
     Database database = DbHelper.db;
     database.delete(
       "routesegments",
-      where: "route = ? AND segmentorder = ?",
+      where: "journey = ? AND segmentorder = ?",
       whereArgs: [id, idx], // TODO: test the index
     );
   }
@@ -351,7 +349,7 @@ class Journey {
     Database database = DbHelper.db;
     database.delete(
       "routesegments",
-      where: "route = ? AND segmentorder = ?",
+      where: "journey = ? AND segmentorder = ?",
       whereArgs: [id, segments.length - 1], // TODO: test the index
     );
   }
@@ -361,7 +359,7 @@ class Journey {
     if (position <= segments.length) {
       database.delete(
         "routesegments",
-        where: "route = ? AND segmentorder >= ?",
+        where: "journey = ? AND segmentorder >= ?",
         whereArgs: [id, position],
       );
     }
@@ -493,7 +491,7 @@ class Segment {
     FROM $tableName s
     JOIN $departure start ON s.startid = start.id
     JOIN $departure end ON s.endid = end.id
-    JOIN $vehicle v ON s.vehicleid = v.id
+    JOIN $vehicle v ON s.vehicleid = v.vehicleid
     where s.id = $id;
     """,
     );
@@ -526,7 +524,7 @@ class Segment {
       "departuretime": seg["end_departuretime"] as String,
     };
     Map<String, String> vehicleMap = {
-      "id": seg["vehicleid"] as String,
+      "vehicleid": seg["vehicleid"] as String,
       "name": seg["vehiclename"] as String,
       "line": seg["vehicleline"] as String,
     };
@@ -735,7 +733,7 @@ class Vehicle {
 
   Map<String, Object?> _toMap() {
     return {
-      "id": vehicleid,
+      "vehicleid": vehicleid,
       "name": name,
       "line": vehicleLineId,
     };
@@ -745,7 +743,7 @@ class Vehicle {
     Map<String, Object?> map,
   ) {
     return Vehicle(
-      vehicleid: map["id"] as String,
+      vehicleid: map["vehicleid"] as String,
       name: map["name"] as String,
       vehicleLineId: map["line"] as String,
     );
@@ -775,7 +773,7 @@ class Vehicle {
     Database database = DbHelper.db;
     var vehicleMap = await database.query(
       tableName,
-      where: "id = ?",
+      where: "vehicleid = ?",
       whereArgs: [vehicleId],
     );
     return Vehicle.fromMap(vehicleMap.first);
@@ -792,7 +790,12 @@ class Vehicle {
 
   void dbUpdate() async {
     Database database = DbHelper.db;
-    database.update(tableName, _toMap(), where: "id=?", whereArgs: [vehicleid]);
+    database.update(
+      tableName,
+      _toMap(),
+      where: "vehicleid=?",
+      whereArgs: [vehicleid],
+    );
   }
 
   void dbDelete() async {
@@ -1173,4 +1176,4 @@ enum VehicleType {
   subway,
   regionalTrain,
   PLACEHOLDER,
-}
+}