236 lines
5.2 KiB
Markdown
236 lines
5.2 KiB
Markdown
# Android Application
|
|
|
|
## 1. Purpose
|
|
|
|
The Android application is a lightweight training-session recorder.
|
|
|
|
Its design priority is low-friction data entry during a workout.
|
|
|
|
It is not the canonical history or analytics application.
|
|
|
|
## 2. Session flow
|
|
|
|
```text
|
|
Start session
|
|
|
|
|
v
|
|
record started_at
|
|
|
|
|
v
|
|
select/create exercise
|
|
|
|
|
v
|
|
enter target + planned rest
|
|
|
|
|
v
|
|
record actual sets
|
|
|
|
|
v
|
|
optional body data / notes
|
|
|
|
|
v
|
|
Finish session
|
|
|
|
|
v
|
|
record ended_at
|
|
|
|
|
v
|
|
validate + export Trainlog JSON
|
|
```
|
|
|
|
## 3. Exercise catalog
|
|
|
|
The Android application keeps a local exercise catalog so names are not retyped every session.
|
|
|
|
Creating an exercise requires:
|
|
|
|
- display name;
|
|
- tracking mode: repetitions or duration.
|
|
|
|
The application generates a stable `exercise_id`.
|
|
|
|
A new exercise used in an exported session is included in the top-level session export metadata and is therefore importable by the TUI.
|
|
|
|
The Android application must prevent accidental duplicate normalized names according to the Trainlog v1 contract.
|
|
|
|
## 4. Fast exercise form
|
|
|
|
For a repetition exercise, the basic form is conceptually:
|
|
|
|
```text
|
|
Exercise Presse à cuisses
|
|
Load mode External
|
|
Load 80 kg
|
|
Sets 4
|
|
Repetitions 5
|
|
Rest 60 s
|
|
```
|
|
|
|
For a timed exercise:
|
|
|
|
```text
|
|
Exercise Gainage ventral
|
|
Load mode None
|
|
Sets 3
|
|
Duration 45 s
|
|
Rest 60 s
|
|
```
|
|
|
|
The application should remember practical defaults from the previous use of an exercise when that reduces typing, but remembered UI defaults are not part of the exchange-format contract.
|
|
|
|
## 5. Load modes
|
|
|
|
The user chooses only when relevant:
|
|
|
|
- none;
|
|
- external;
|
|
- assistance.
|
|
|
|
`external` covers free weights and machine-displayed load.
|
|
|
|
`assistance` stores a positive assistance value.
|
|
|
|
The UI should label assistance explicitly so it cannot be confused with added resistance.
|
|
|
|
## 6. Actual work
|
|
|
|
The application should pre-populate actual sets from the target.
|
|
|
|
The user edits only what differs.
|
|
|
|
Example target:
|
|
|
|
```text
|
|
5 / 5 / 5 / 5
|
|
```
|
|
|
|
Actual:
|
|
|
|
```text
|
|
5 / 5 / 5 / 3
|
|
```
|
|
|
|
The export preserves both target and actual values.
|
|
|
|
Zero actual repetitions are valid for a real failed attempt.
|
|
|
|
A planned exercise may also have zero actual sets if it was never started.
|
|
|
|
## 7. Rest
|
|
|
|
`rest_seconds` is the planned rest duration for the exercise.
|
|
|
|
v1 does not require a running rest timer and does not serialize measured per-set rest.
|
|
|
|
A timer can be added later as UI behavior without changing the v1 format.
|
|
|
|
## 8. Timestamps
|
|
|
|
`started_at` is recorded automatically when the session starts.
|
|
|
|
`ended_at` is recorded automatically when the user finishes the session.
|
|
|
|
An active/interrupted local session may exist without `ended_at`.
|
|
|
|
The application must never invent an end timestamp merely to make export validation pass.
|
|
|
|
## 9. Body data
|
|
|
|
Optional session-associated data:
|
|
|
|
- body weight;
|
|
- neck;
|
|
- shoulders;
|
|
- chest;
|
|
- waist;
|
|
- hips;
|
|
- left/right arm;
|
|
- left/right forearm;
|
|
- left/right thigh;
|
|
- left/right calf.
|
|
|
|
The Android UI does not need to force these fields during every workout.
|
|
|
|
## 10. Notes
|
|
|
|
Session and exercise notes are optional.
|
|
|
|
The initial Android UI may omit note controls without violating v1, because the fields are optional.
|
|
|
|
## 11. Export
|
|
|
|
Before export, Android must enforce both:
|
|
|
|
- JSON structural validity;
|
|
- Trainlog v1 semantic validity.
|
|
|
|
A malformed or semantically inconsistent file must not be exported as a completed Trainlog document.
|
|
|
|
## 12. Non-goals
|
|
|
|
Initial Android versions do not need:
|
|
|
|
- analytics;
|
|
- complex graphs;
|
|
- cloud accounts;
|
|
- remote databases;
|
|
- social features;
|
|
- muscle classification;
|
|
- distance/cardio metrics;
|
|
- per-set rest measurement.
|
|
## 13. Identifier generation
|
|
|
|
When Android creates a new exercise, it generates:
|
|
|
|
```text
|
|
ex_<random UUID v4>
|
|
```
|
|
|
|
When Android creates a new session, it generates:
|
|
|
|
```text
|
|
se_<random UUID v4>
|
|
```
|
|
|
|
Display-name slugs must not be used as persistent identifiers.
|
|
|
|
The visible exercise name remains independent from identity.
|
|
|
|
## 14. Catalog conflict behavior
|
|
|
|
Android must prevent duplicate normalized names inside its own local catalog.
|
|
|
|
A valid Android export can still conflict with an independently edited TUI catalog.
|
|
|
|
The TUI owns final reconciliation.
|
|
|
|
Android must not assume that a matching display name means two different IDs may be silently merged.
|
|
|
|
<!-- TRAINLOG_ANDROID_MTP_TRANSPORT -->
|
|
## 15. USB file-transfer transport
|
|
|
|
The initial Android/Linux integration uses standard Android **file transfer
|
|
(MTP)** mode.
|
|
|
|
The Linux TUI/core accesses the device directly with `libudev` + `libmtp`.
|
|
Trainlog does not require a mounted Android filesystem.
|
|
|
|
Validated Linux-side capabilities:
|
|
|
|
```text
|
|
USB_MTP_DETECTION=PASS
|
|
MTP_STORAGE_ACCESS=PASS
|
|
MTP_WRITE=PASS
|
|
MTP_READ=PASS
|
|
MTP_ROUNDTRIP=PASS
|
|
```
|
|
|
|
The transport foundation currently uses a root `Trainlog` folder for physical
|
|
validation.
|
|
|
|
The final JSON exchange subdirectory/naming convention is defined in the next
|
|
slice before the Android recorder depends on it.
|
|
|
|
The Android application itself will only need to produce a valid frozen
|
|
Trainlog JSON v1 document and place it in the agreed exchange area.
|
|
<!-- TRAINLOG_ANDROID_MTP_TRANSPORT _END -->
|