fy59/trainlog
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Align documentation with current TUI state

Browse source
This commit is contained in:
fy59 2026-09-06 09:59:00 +02:00
parent 3d99be00f5
commit 2d47805431
4 changed files with 83 additions and 42 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

66
docs/database.md
View file

@ -3,9 +3,12 @@
## 1. Status
```text
GATE_2_REVIEW_01=IMPLEMENTED
GATE_2=IN_PROGRESS
DATABASE_SCHEMA_V1=DRAFT
DATABASE_SCHEMA_V2=IMPLEMENTED
SESSION_TYPE_PERSISTENCE=IMPLEMENTED
SESSION_EDIT_PERSISTENCE=IMPLEMENTED
BODY_OBSERVATION_EDIT=IMPLEMENTED
TRAINLOG_FORMAT_V1=FROZEN
```
Gate 2 review #1 establishes the persistence foundation.
@ -26,17 +29,29 @@ Trainlog database schema version uses SQLite:
PRAGMA user_version;
```
Initial schema:
Current schema:
```text
DATABASE_SCHEMA_V1=1
DATABASE_SCHEMA_V2=2
```
A new database starts with `user_version = 0` and is initialized atomically to version 1.
A new database starts with `user_version = 0` and is initialized atomically to
the current schema.
The implemented historical path is:
```text
0 -> 2 fresh initialization
1 -> 2 transactional migration
```
Schema v2 adds local session classification while leaving the frozen Trainlog
JSON v1 exchange contract unchanged.
A database newer than the running binary understands is rejected.
Historical migrations are not invented. They must be explicitly implemented and tested when a schema version 2 is introduced.
Every future schema change requires an explicit migration and dedicated
coverage; metadata-only version rewriting is not an accepted migration.
## 4. Connection rules
@ -83,9 +98,14 @@ id
session_id UNIQUE
started_at
ended_at nullable
session_type training | max_test
notes nullable
```
`session_type` is a local SQLite concern in schema v2. Existing schema-v1 rows
migrate to `training`; no historical workout is retroactively inferred to be a
max test.
Body data is stored separately so standalone body observations can use the same representation.
### 5.3 `session_exercises`
@ -195,7 +215,15 @@ ROLLBACK
primitives.
The future JSON import service must perform catalog reconciliation and all session inserts inside one transaction.
The JSON import service must perform catalog reconciliation and all session inserts inside one transaction.
Persisted session correction also uses an explicit transaction. Editing a
session replaces only its `session_exercises` / `performed_sets` children and
preserves the parent session row, stable `session_id`, timestamps,
`session_type`, session notes, and any linked body observation.
Body-observation correction preserves observation identity, timestamp, and
optional session link.
A hard conflict or validation failure leaves the database unchanged.
@ -207,20 +235,24 @@ Canonical persistent units remain:
- body circumference: centimeters;
- duration/rest: seconds.
## 9. Gate 2 review #1 boundary
## 9. Current Gate 2 persistence boundary
Review #1 intentionally does not implement:
Implemented persistence includes:
- JSON parsing;
- Unicode exercise-name normalization;
- local catalog reconciliation;
- full session insert APIs;
- body-observation CRUD;
- ncurses.
- SQLite schema v2;
- transactional schema migration v1 -> v2;
- Unicode-aware canonical exercise catalog support;
- complete session insertion;
- session detail loading;
- exact bounded editable-session loading;
- transactional replacement of session exercise/set children;
- body-observation creation, listing, exact lookup, and update;
- stable local identifiers for exercises, sessions, and body observations.
Those belong to subsequent Gate 2 work.
The database remains independent from ncurses rendering.
This split keeps the first compiled C change small enough to review thoroughly.
The frozen Trainlog JSON v1 format remains a separate compatibility boundary
and is not version-coupled to SQLite schema v2.
## 10. Validation

12
docs/reviews/session_edit_persistence.md
View file

@ -4,7 +4,7 @@
```text
SESSION_EDIT_PERSISTENCE=IMPLEMENTED
SESSION_EDIT_TUI=NEXT
SESSION_EDIT_TUI=IMPLEMENTED
TRAINLOG_FORMAT_V1=FROZEN
DATABASE_SCHEMA_V2=UNCHANGED
```
@ -31,3 +31,13 @@ exercise/set values in bounded caller-owned buffers. It refuses insufficient
capacity instead of silently truncating editable data.
No schema migration and no JSON v1 change are required.
## TUI integration
The persistence foundation is now used by the ncurses editor.
A persisted workout can be reopened from history or session detail, corrected,
and saved without deleting/recreating the parent `sessions` row.
Draft editing and persisted editing share the same bounded exercise/set model.
Cancelling with Escape leaves the stored workout unchanged.

25
docs/roadmap.md
View file

@ -35,11 +35,11 @@ Current TUI capabilities:
Current remaining Gate 2 direction:
1. finish the current visual/navigation checkpoint;
2. validate persisted editing on the real database;
3. detect Android over USB/ADB;
4. build the minimal Android recorder;
5. exercise frozen JSON v1 import/export end to end.
1. detect Android over USB/ADB;
2. build the minimal Android recorder;
3. transfer/export one frozen Trainlog JSON v1 document over USB;
4. import it transactionally into the canonical SQLite store;
5. validate the complete Android -> JSON -> TUI -> SQLite path.
Measured-max semantics remain a later independent analytics contract.
@ -122,8 +122,10 @@ DASHBOARD_12_MONTHS=IMPLEMENTED
```text
TUI_EXERCISE_PERFORMANCE=IMPLEMENTED
MEASURED_MAX_TRACKING=NEXT
PREVIOUS_SESSION_DEFAULTS=AFTER
TUI_SESSION_EDIT=IMPLEMENTED
TUI_BODY_OBSERVATION_EDIT=IMPLEMENTED
ANDROID_USB_DETECTION=NEXT
MEASURED_MAX_TRACKING=LATER
```
## Session type / measured max foundation
@ -149,14 +151,17 @@ classified as a max test.
```text
SESSION_EDIT_PERSISTENCE=IMPLEMENTED
SESSION_EDIT_TUI=NEXT
BODY_OBSERVATION_EDIT=AFTER
USB_PHONE_DETECTION=AFTER_EDITING
SESSION_EDIT_TUI=IMPLEMENTED
BODY_OBSERVATION_EDIT=IMPLEMENTED
USB_PHONE_DETECTION=NEXT
```
Recorded session exercise/set correction uses atomic replacement of child rows
while preserving the parent session row and linked body observations.
The TUI exposes correction both while reviewing an in-progress draft and after
persistence. Escape cancels without committing partial edits.
## Body observation record workflow
```text

22
docs/tui.md
View file

@ -392,8 +392,8 @@ are not required for the Android transport milestone.
<!-- TRAINLOG_GLOBAL_BODY_GRAPH_NEXT -->
## 21. Global body evolution graph — implemented
`F4 Corps` keeps its current per-metric graph and gains a global normalized
overlay view.
`F4 Corps` provides a record-oriented observation history plus a global
normalized overlay view.
The global graph must not overlay raw kilograms and centimeters directly.
@ -429,20 +429,14 @@ recorded value for each available metric.
## 22. Dashboard graph v2 — implemented
The dashboard body-weight graph becomes a richer summary.
The dashboard body graph is implemented as a compact rolling 12-month
multi-metric summary.
It will show:
- current body weight;
- change from first recorded weight;
- change from previous recorded weight;
- minimum recorded weight;
- maximum recorded weight;
- recent weight graph;
- latest waist measurement when available;
- latest left/right asymmetry alert when meaningful.
It shows available body metrics normalized to their first visible value in the
window, while the legend preserves each latest raw value and percentage change.
The dashboard remains intentionally compact.
The complete multi-metric overlay belongs to `F4 Corps`.
The dashboard remains intentionally compact. Detailed absolute observation
history and the complete normalized overlay belong to `F4 Corps`.
## 23. Current implementation cursor