generated from me/template-mit
Lots of DB content as well as some love to the frontend and fetcher sections.
me committed
1 parent
fdb6b8838e
commit
6cf39d2672
1 file changed
+220
-9
+220
-9
@@ -34,19 +34,71 @@ Developer: Hyperling
|
||||
|
||||
Language/Framework: Flutter
|
||||
|
||||
### Planned Versions
|
||||
|
||||
**0.1**
|
||||
: Basic listview app, hardcode limited production API key.
|
||||
|
||||
**0.2**
|
||||
: Change main page to a Celtic Wheel type layout with season signifier.
|
||||
|
||||
**1.0**
|
||||
: Integrate with a backend cache server which provides aggregated data.
|
||||
|
||||
**1.1**
|
||||
: Add settings page and other nice to haves.
|
||||
|
||||
### Requirements
|
||||
|
||||
- App shall start with a Main page only, then have a Settings page added later.
|
||||
- App shall come with a limited use API key. This key shall not be used by any
|
||||
other module of this project. Developers should use their seperate API key when
|
||||
using Postman, testing the Weather Fetcher, etc.
|
||||
|
||||
### Pages
|
||||
|
||||
#### Main
|
||||
|
||||
*Initial Versions - Simple Data Entry*
|
||||
|
||||
---
|
||||
|
||||
8 sections which contain (three?) data input fieldss:
|
||||
|
||||
- Zip Code
|
||||
- Lat & Long (or should the lat/long just be used to lookup the zip code?)
|
||||
- Nickname
|
||||
|
||||
*Formal Versions - Wheel Layout*
|
||||
|
||||
---
|
||||
|
||||
Circular layout representing the Celtic season wheel with 'LAST_UPDATE_DATE'
|
||||
in the center so the user knows when the highs and lows were last refreshed.
|
||||
|
||||
"Hand" which points to the current season. Accurate to the day preferably, so
|
||||
if we're at September 1 it's pointing in between Summer CQ and Fall Equinox.
|
||||
|
||||
- Initially can just highlight the current half quarter and start making the next
|
||||
one glow as it gets approached. So for June 21, Spring2 and Summer1 would both
|
||||
glow at 50% since that's the day they transition. Then by mid July it would only
|
||||
be Summer1 which glows, and at the end of July Summer1 would be dim and Summer2
|
||||
would be glowing more.
|
||||
|
||||
#### Settings
|
||||
|
||||
**Not required in initial versions of the app, focus on pulling data first!**
|
||||
|
||||
1. Server
|
||||
1. 'Server'
|
||||
- Toggle: 'Use Cache Server'
|
||||
- TRUE:
|
||||
- Radio Group: 'Aggregation Mode'
|
||||
- 'Mean / Average'
|
||||
- 'Mode / Most Common'
|
||||
- 'Median / Center-Most'
|
||||
- 'Today Only'
|
||||
- 'Tomorrow Only'
|
||||
- 'Week : Mean / Average'
|
||||
- 'Week : Median / Center-Most'
|
||||
- 'Week : Mode / Most Common'
|
||||
- 'Only : Today'
|
||||
- ?'Only : Tomorrow'
|
||||
- ?'Only : Today + 7'
|
||||
- FALSE:
|
||||
- TextEdit: 'API Key' (REQUIRED)
|
||||
- 'If not using the cache server, you'll need to provide your own API key for TBD weather service.'
|
||||
@@ -66,27 +118,186 @@ Language/Framework: Flutter
|
||||
- Greather Than
|
||||
- Checkbox: 'Equal To'
|
||||
|
||||
|
||||
### Description
|
||||
|
||||
### Requirements
|
||||
|
||||
## 2. Database
|
||||
|
||||
|
||||
|
||||
### Description
|
||||
|
||||
### Requirements
|
||||
|
||||
- All temperature data shall be stored in Fahrenheit. Decimals are okay.
|
||||
- All date data shall be displayed as 'YYYY-MM-DDTHH24:MI:SS' GMT
|
||||
(or 'YYYY-MM-DDTHH24:MI:SS+0000') in any reporting or data transfers. Time zones
|
||||
will be handled at the frontend. The 'T' in the center is a dead character. Example:
|
||||
```shell
|
||||
$ echo "Actual Time: `date`" && echo "Report Time: `date -u +'%Y-%m-%dT%H:%M:%S%z'`"
|
||||
Actual Time: Wed Aug 19 10:49:52 AM MST 2026
|
||||
Report Time: 2026-08-19T17:49:52+0000
|
||||
```
|
||||
- Database shall be set to case insensitive, so that `SELECT column FROM loc`
|
||||
and `select COLUMN from LOC` are the same command.
|
||||
- Database shall have a daily purge script followed by statistics rebuilding.
|
||||
The records to be removed will look like (TBD: `IS_PURGED = true`). The purge
|
||||
will cascade through any child tables. Bonus points if they exist, are scheduled,
|
||||
and gets executed from inside the DB rather than needing to run outside files.
|
||||
- Database object script(s) for the primary initialization as well as patches
|
||||
shall be reproducible and rerunnable, meaning they drop then create all database
|
||||
objects, constraints, schedules, etc being added in the revision. Example:
|
||||
```sql
|
||||
-- Undo Section --
|
||||
-- Allowed to have failures if the objects don't exist yet.
|
||||
SET ERRORS OFF / ON ERROR CONTINUE / ETC;
|
||||
DROP TABLE example_child;
|
||||
DROP TABLE example;
|
||||
|
||||
-- Apply Section --
|
||||
-- All commands must succeed successfully in order to continue.
|
||||
SET ERRORS ON / ON ERROR EXIT / ETC;
|
||||
CREATE TABLE example
|
||||
( example_id INT PRIMARY KEY
|
||||
, example_data VARCHAR
|
||||
);
|
||||
CREATE TABLE example_child
|
||||
( example_child_id INT PRIMARY KEY
|
||||
, example_id INT FOREIGN KEY (example.example_id)
|
||||
, more_example_data VARCHAR
|
||||
);
|
||||
```
|
||||
- Scripts shall have a consistent style and formatting. Developer may use the
|
||||
style of their choice.
|
||||
|
||||
### Tables
|
||||
|
||||
- Database and schema names shall be short and easy to remember, otherwise they
|
||||
are the developer's choice. Bonus points if the DB does not require them to
|
||||
access the tables, or a setting / parameter can be set to default to them.
|
||||
```sql
|
||||
-- yucky
|
||||
select * from db_name.schema_name.table_name;
|
||||
-- preferred
|
||||
select * from table_name;
|
||||
```
|
||||
|
||||
#### Table 1: `loc`
|
||||
|
||||
| Column Name | Type | Constraints | Calculated? |
|
||||
| --- | :-: | :---: | :-----: |
|
||||
| loc_id | INT | PK | - |
|
||||
| zip_code | STRING | UNIQUE | - |
|
||||
| last_accessed_date | DATE | - | - |
|
||||
| needs_purged | - | - | CASE WHEN sysdate < last_accessed_date + 90 THEN true ELSE false ESAC |
|
||||
|
||||
#### Table 3: `loc_weather_agg`
|
||||
|
||||
| Column Name | Type | Constraints | Calculated? |
|
||||
| --- | :-: | :---: | :-----: |
|
||||
| loc_weather_agg_id | INT | PK | - |
|
||||
| loc_weather_id | INT | FK (loc_weather.loc_weather_id) | - |
|
||||
| weekly_mean_high | DECIMAL | - | - |
|
||||
| weekly_mean_low | DECIMAL | - | - |
|
||||
| weekly_median_high | DECIMAL | - | - |
|
||||
| weekly_median_low | DECIMAL | - | - |
|
||||
| weekly_mode_high | DECIMAL | - | - |
|
||||
| weekly_mode_low | DECIMAL | - | - |
|
||||
| tomorrow_high | DECIMAL | - | - |
|
||||
| tomorrow_low | DECIMAL | - | - |
|
||||
| extended_high | DECIMAL | - | - |
|
||||
| extended_low | DECIMAL | - | - |
|
||||
|
||||
Today's high and low are accessible when joining to the `LOC_WEATHER` table, which
|
||||
is necessary anyways to get to the `WEATHER_DATE` and `ZIP_CODE`.
|
||||
|
||||
Extended high and low are for `WEATHER_DATE + 7`, so a week from the date.
|
||||
|
||||
### Roles
|
||||
|
||||
Object grants shall be given to roles, and the roles then assigned to users. Example:
|
||||
```sql
|
||||
CREATE ROLE myrole;
|
||||
GRANT SELECT, INSERT, UPDATE ON example TO myrole;
|
||||
CREATE USER me;
|
||||
GRANT myrole TO me;
|
||||
```
|
||||
|
||||
#### Role 0 : `librarian`
|
||||
|
||||
- Grant `SELECT` on all `loc*` tables.
|
||||
|
||||
#### Role 1: `weatherman`
|
||||
|
||||
- Grant `INSERT` and `UPDATE` on all `loc_weather*` tables.
|
||||
|
||||
#### Role 2: `reporter`
|
||||
|
||||
- Grant `INSERT`, `UPDATE` on `loc`.
|
||||
|
||||
#### Role 3: `garbageman`
|
||||
|
||||
- Grant `DELETE` on all `loc*` tables.
|
||||
- Grant ability to build statistics on all `loc*` tables.
|
||||
- Depending on the DB used, may also need grants on keys and constraints in order to rebuild the stats on their indexes or other stat-holding objects.
|
||||
|
||||
#### Role 4: `developer`
|
||||
|
||||
- Grant `ALL` on the applicable schema.
|
||||
- CANNOT access or alter `SYSTEM` type schemas, views, etc.
|
||||
|
||||
### Users
|
||||
|
||||
#### User 1: `dbuser`
|
||||
|
||||
- Granted the `librarian` and `developer` role.
|
||||
- Used by the main contributors of the project to test in stage environments.
|
||||
- Used by the project owner(s) in production to apply patch scripts.
|
||||
|
||||
#### User 2: `climate`
|
||||
|
||||
- Granted the `librarian` and `weatherman` role.
|
||||
- Used by a local process to add and aggregate weather data.
|
||||
|
||||
#### User 3: `geo`
|
||||
|
||||
- Granted the `librarian` and `reporter` role.
|
||||
- Used by a local process to pull weather data and post new locations.
|
||||
|
||||
#### User 4: `purge`
|
||||
|
||||
- Granted the `librarian` and `garbageman` role.
|
||||
- User / schema who owns the purge routines if they are intalled in the DB.
|
||||
- Otherwise, this is the user who logs in and runs external purge scripts.
|
||||
|
||||
#### As Needed: leetbro, hackersis, othercoolalias
|
||||
|
||||
Contributors to this project may have their accounts created in test and stage
|
||||
environments as necessary. Otherwise the contributors known as DB admins shall
|
||||
handle all applicable DB support and modifications.
|
||||
|
||||
## 3. Weather Fetcher
|
||||
|
||||
### Description
|
||||
|
||||
### Requirements
|
||||
|
||||
- Assume the database is local, just as would be during local devlopment. Will
|
||||
not need to access via domain name or a special port, only localhost:defaut_port.
|
||||
- Program shall use its own API key(s) to access the weather data. May use a
|
||||
pool of keys if necessary to alleviate bandwidth or throttling.
|
||||
|
||||
#### Aggregations
|
||||
|
||||
For each `ZIP_CODE`, calculate the following:
|
||||
|
||||
- Weekly Mean
|
||||
- Weekly Median
|
||||
- Weekly Mode
|
||||
|
||||
## 4. Response API
|
||||
|
||||
### Description
|
||||
|
||||
### Requirements
|
||||
|
||||
-
|
||||
Reference in new issue
Block a user