Planned and executed phase001
This commit is contained in:
@@ -0,0 +1,153 @@
|
||||
# Vehicle Tracker Application Design
|
||||
|
||||
## Goal
|
||||
A web application to replace manual spreadsheet tracking of vehicle maintenance
|
||||
and fuel usage of a shared fleet.
|
||||
|
||||
## Architecture & Philosophy
|
||||
* **Language:** Ruby on Rails
|
||||
* **Style:** Snake_case
|
||||
* **Principle:** Keep it simple. Do not over-optimize. CRUD is the priority.
|
||||
* **Database:** Relational, tracking "Events" linked to specific "Entities."
|
||||
* **Tests:** We should be test driven in our development. No feature should
|
||||
be created without a test.
|
||||
|
||||
## Data models
|
||||
|
||||
### 1. User
|
||||
|
||||
This table will contain information about the users of the app. Mostly used to
|
||||
know who updated what. This table will include:
|
||||
|
||||
* *Fields:* `name`, `email`
|
||||
|
||||
|
||||
### 2. Vehicle
|
||||
|
||||
This table will contain information about the vehicles (assets) that we
|
||||
track. They have no strict ownership relationship as they can be used/driven by
|
||||
multiple operators. The vehicle information will include:
|
||||
|
||||
* *Fields:* `make`, `model`, `year`, `color`, `vin`,
|
||||
`licence_place`, `current_odometer`, `fuel_tank_size`
|
||||
|
||||
### 3. MaintenanceSchedule
|
||||
Configures the maintenance rules for a specific vehicle. This allows the
|
||||
"overdue" check to be automated by comparing the current schedule against the
|
||||
actual history.
|
||||
* *Fields:* `vehicle_id`, `maintenance_type`, `mileage_interval`,
|
||||
`time_interval`
|
||||
* *Relationship:* Belongs to Vehicle
|
||||
|
||||
### 4. FuelEntry
|
||||
Records specific refueling events.
|
||||
* *Fields:* `vehicle_id`, `odometer` (at time of fill), `gallons_pumped`,
|
||||
`price_paid`, `date`, `updated_by_user_id` (Tracks who submitted)
|
||||
* *Relationship:* Belongs to Vehicle
|
||||
|
||||
### 5. MainetnanceEntry
|
||||
Records maintenance and repair history.
|
||||
* *Fields:* `vehicle_id`, `odometer` (at time of service), `description`
|
||||
(Should exactly match a `maintenance_type` value from the
|
||||
MaintenanceSchedule), `cost`, `date`, `updated_by_user_id` (Tracks who
|
||||
submitted)
|
||||
* *Relationship:* Belongs to Vehicle
|
||||
|
||||
## Data Relationships
|
||||
|
||||
* **Vehicle** has_many **MaintenanceSchedules**
|
||||
* **Vehicle** has_many **FuelEntries**
|
||||
* **Vehicle** has_many **MaintenanceEntries**
|
||||
* **User** has_many **FuelEntries** (as the actor)
|
||||
* **User** has_many **MaintenanceEntries** (as the actor)
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Scenario A: Fueling
|
||||
1. User navigates to `Vehicle#show`.
|
||||
2. User fills form with Odometer, Gallons, Price.
|
||||
3. User submits -> `FuelEntry` is saved to DB.
|
||||
4. `current_odometer` is updated on the Vehicle record.
|
||||
|
||||
### Scenario B: Maintenance
|
||||
1. User navigates to `Vehicle#show`.
|
||||
2. User fills form with Description, Cost, Date.
|
||||
3. User submits -> `MaintenanceEntry` is saved to DB.
|
||||
|
||||
### Scenario C: Overdue Alerts
|
||||
1. On `Vehicle#show`, query the most recent `MaintenanceEntry`.
|
||||
2. Compare `MaintenanceEntry.date` vs `Date.today`.
|
||||
3. If difference > 6 months, display alert message to User.
|
||||
|
||||
Note that there is in the MaintenanceSchedule data, there is a `time_interval`
|
||||
field that defines the length of time for maintenance. There is also a milage
|
||||
that should be used as well and it is an or operation for them.
|
||||
|
||||
## User Authentication
|
||||
|
||||
Because this is an internal application, I plan on something like this:
|
||||
|
||||
The server will every month generate a key. This key will be printed out in a
|
||||
QR code format. The users will then scan the QR code to collect the key. When
|
||||
they make a request, this key is sent along with it and is used to verify the
|
||||
user. Ideally each user would use the QR code to prove that I know them, enter
|
||||
a name and then get a session token that is used instead of sending the raw QR
|
||||
code. The idea is that it is proof that I know who they are by them posessing
|
||||
information that only I have (the QR code) and then in the future they should
|
||||
use the token to prove who they are.
|
||||
|
||||
Again, because this is an internal application, there should not be any
|
||||
passwords. Users are not really created to be logged in, more because I need to
|
||||
track who is doing what with the equipment.
|
||||
|
||||
## Database choice
|
||||
|
||||
I have no hard requirements. I would prefer the database to be easy to use for
|
||||
development. This application will really only ever have up to 100 users so I
|
||||
do not need high performance. SQLite should work fantastic in this case.
|
||||
|
||||
## Test framework
|
||||
|
||||
The test framework is rspec. You can run the tests with `bin/rails test`
|
||||
|
||||
## Vehicle ownership
|
||||
|
||||
Vehicles can be used by multiple operators. We do not need to track who is
|
||||
driving though. We just want to know about who is submitting updates and
|
||||
enteries.
|
||||
|
||||
## Rails information
|
||||
|
||||
```
|
||||
$ rails --version
|
||||
Rails 8.1.3.1
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
This will be a local development deployment. Once we are ready, it will be
|
||||
packaged into a Docker container and put on a production server. This container
|
||||
is designed to run behind a reverse proxy that is already in place.
|
||||
|
||||
|
||||
# Final notes
|
||||
|
||||
The relationship between the user and vehicle is minimal. This is on purpose
|
||||
because we really are only using the user to track who is making changes. We do
|
||||
not really care if it is the actual driver or not.
|
||||
|
||||
For overdue alerts, we will send notifications to the users using a
|
||||
notification service. This is not yet set up so we will not worry about it. We
|
||||
can leave stubs though for that to happen. The notification service just
|
||||
requires a curl request so it is simple to add later. For now, just log it into
|
||||
the console so that we can test it is working.
|
||||
|
||||
For data access, it would be nice to have 'admin' and 'regular' users however
|
||||
that is a distinction that we do not yet need. Remember to keep things simple
|
||||
but flexible in the future. Do not wall us in with how code is done.
|
||||
|
||||
Each edit by the users will be a seperate database entry. There should be no
|
||||
user editing the same entry at any time. The only possible issue that I can see
|
||||
is if we have two users in the same vehicle and they both submit a fuel
|
||||
entry. In this case, we would just delete one of the entries. At no point in
|
||||
time should two users be editing the same record.
|
||||
Reference in New Issue
Block a user