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
|
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
|
#### Settings
|
||||||
|
|
||||||
**Not required in initial versions of the app, focus on pulling data first!**
|
**Not required in initial versions of the app, focus on pulling data first!**
|
||||||
|
|
||||||
1. Server
|
1. 'Server'
|
||||||
- Toggle: 'Use Cache Server'
|
- Toggle: 'Use Cache Server'
|
||||||
- TRUE:
|
- TRUE:
|
||||||
- Radio Group: 'Aggregation Mode'
|
- Radio Group: 'Aggregation Mode'
|
||||||
- 'Mean / Average'
|
- 'Week : Mean / Average'
|
||||||
- 'Mode / Most Common'
|
- 'Week : Median / Center-Most'
|
||||||
- 'Median / Center-Most'
|
- 'Week : Mode / Most Common'
|
||||||
- 'Today Only'
|
- 'Only : Today'
|
||||||
- 'Tomorrow Only'
|
- ?'Only : Tomorrow'
|
||||||
|
- ?'Only : Today + 7'
|
||||||
- FALSE:
|
- FALSE:
|
||||||
- TextEdit: 'API Key' (REQUIRED)
|
- TextEdit: 'API Key' (REQUIRED)
|
||||||
- 'If not using the cache server, you'll need to provide your own API key for TBD weather service.'
|
- '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
|
- Greather Than
|
||||||
- Checkbox: 'Equal To'
|
- Checkbox: 'Equal To'
|
||||||
|
|
||||||
|
|
||||||
### Description
|
### Description
|
||||||
|
|
||||||
### Requirements
|
### Requirements
|
||||||
|
|
||||||
## 2. Database
|
## 2. Database
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### Description
|
### Description
|
||||||
|
|
||||||
### Requirements
|
### 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
|
## 3. Weather Fetcher
|
||||||
|
|
||||||
### Description
|
### Description
|
||||||
|
|
||||||
### Requirements
|
### 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
|
## 4. Response API
|
||||||
|
|
||||||
### Description
|
### Description
|
||||||
|
|
||||||
### Requirements
|
### Requirements
|
||||||
|
|
||||||
|
-
|
||||||
Reference in new issue
Block a user