jacobh2
d39eb2c79b
Records the owner's UX-sprint decisions UX-1 to UX-8 of docs/ux/proposed-decisions.md: D-047 direction Kalas muted, D-048 three tabs, D-049 category suggestion (§9.11, suggestCategory, contracts/category-keywords.csv, suggest_category.json), D-050 S-1 display-name field, D-051 colour token values from Kalas (slate, amber TODO(U2)), D-052 smaller UX rules, D-053 finer Splitwise mapping, D-054 fourteen default categories with server schema 2 (migration 0002, §14.1.1). Adds milestone group M12 (PLAN-M12a/b/c, prompts), the CLAUDE.md UX-sprint note, and rewrites HANDOFF. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TQd3pEP9UeN2uifbHknQ7B
94 lines
11 KiB
Markdown
94 lines
11 KiB
Markdown
# PLAN-M7f: Feature settings
|
||
|
||
## 1. Goal
|
||
Build `:feature:settings`: the settings hub (S-13), profile (S-14), categories (S-15), recurring expenses (S-19), devices (S-20), invites (S-21) and about (S-22), against the `:core:model` interfaces and `:core:fakes`. Every state of every screen is screenshot-tested in Swedish and English, light and dark.
|
||
|
||
## 2. Read first
|
||
1. `docs/ux/design-spec.md`: tokens, component inventory, and the sections for S-13, S-14, S-15, S-19, S-20, S-21, S-22.
|
||
2. `docs/ux/strings.csv` (keys for these screens) and `docs/ux/screens/S-13-*`, `docs/ux/screens/S-14-*`, `docs/ux/screens/S-15-*`, `docs/ux/screens/S-19-*`, `docs/ux/screens/S-20-*`, `docs/ux/screens/S-21-*`, `docs/ux/screens/S-22-*`.
|
||
3. SPEC §13.2 Navigation model and §13.3 Screens (rows S-13, S-14, S-15, S-19, S-20, S-21, S-22 and the states paragraph).
|
||
4. SPEC §14.2.4 UI contract: `ProfileRepository`, `CategoryRepository`, `RecurringRepository`/`RecurringTemplate`, `DeviceRepository`/`Device`, `InviteRepository`/`Invite`, `AboutRepository`/`AboutState`, `UpdateRepository`, `SessionRepository` (role), `ConnectivityRepository`, `ExpenseDraft`, `OnlineResult`.
|
||
5. SPEC §4 FR-2 AC-2.1, AC-2.2, AC-2.11; FR-3 Devices and revocation (AC-3.1, AC-3.2); FR-4 Profiles (AC-4.1 to AC-4.5); FR-7 Categories (AC-7.1 to AC-7.7); FR-9 Recurring expenses (AC-9.1, AC-9.7, AC-9.8); FR-16 (check for update); §8.3 (code display), §8.4 Authorization rules, §9.6, §9.7, §9.9.
|
||
6. SPEC §6.2 (module table), §9.8 Formatting, §9.9 Online-only actions, §11.2 (row M7f), §11.3 (note M7x), §14.7.
|
||
7. Files: `android/core/model/**`, `android/core/design/**` (read only), `android/core/fakes/**`, `android/build-logic/**`, `CLAUDE.md` (BUILD AND VERIFY: Screenshots; ARCHITECTURE RULES; ANTI-PATTERNS).
|
||
|
||
## 3. Already established
|
||
- Features depend only on `:core:model`, `:core:design` and `:core:fakes`; `:core:fakes` only in test, screenshot-test and debug-preview configurations, never in a release build. Features never depend on `:data` or `:domain` (§6.2, §11.3, CLAUDE.md Layering).
|
||
- Screens consume the `*State` classes through the repository interfaces of §14.2.4; no field may be added except through a contract change (§14.2.4, §14.8).
|
||
- Fake scenarios go only in `android/core/fakes/src/main/kotlin/se/hagstedt/kvitt/fakes/<feature>/` (§11.3, §14.7).
|
||
- Strings live in the module's `src/main/res/values/strings.xml` and `values-sv/strings.xml` with keys from `docs/ux/strings.csv`; no string outside that file unless the report proposes it as a decision entry for the orchestrator (§13.4, §14.7, AC-19.1).
|
||
- No hard-coded colours, sizes or strings; tokens and shared components come from `:core:design`, which features may not edit (CLAUDE.md, §14.7). Money and dates go through `MoneyFormatter` and `DateFormatter` (§9.8).
|
||
- Online-only actions are disabled with "Needs connection" when offline (§9.9); a REST failure shows "Could not reach the server".
|
||
- Feature convention (§6.2, D-017): one composable entry point per screen, taking a `hiltViewModel()`-provided ViewModel and its navigation as plain lambdas; the feature never references another feature or the `NavHost`; ViewModels get repositories through the `:core:model` interfaces. Navigation graph, deep links and Hilt bindings are in `:app` (M8).
|
||
- M2b created this module's shell with one empty entry composable (D-004); this plan owns it and replaces it with the real entry points.
|
||
- Keys are prefixed by the feature name; lint `MissingTranslation` is an error in this module (§6.2, §13.4, D-017).
|
||
- The states each screen must have are the ones `docs/ux/design-spec.md` lists for it (§13.3).
|
||
- Shared UI (D-019): the expense editor fields (S-19) come from `:core:design`, built by M6; never copy or re-implement it here.
|
||
- Layout and visuals follow `docs/ux/design-spec.md`; TalkBack labels as it specifies; 48 dp targets, 200 % font scale reflow (§13.1).
|
||
- No placeholder text in previews or screenshots; goldens are committed; open every changed PNG before committing (CLAUDE.md).
|
||
- Hub rows: Profile, Categories, Recurring expenses, Devices, Invite partner or Pair a device (admin only), Sync status (opens S-16 via `:app`), About; own and partner's avatar and name (§13.3 S-13, §8.4).
|
||
- Profile: own name and picture only, from the Android photo picker, online only (AC-4.2, AC-4.3, §9.9).
|
||
- Categories: list with icon, colour, name and an archived section; editor with "Reset name" for defaults, the 33 icons and 14 colour swatches of §9.7 (D-054); reorder by drag; delete blocked with the reason (`category_in_use`, `category_is_default`), archive offered instead; all online only (FR-7, §13.3 S-15).
|
||
- Recurring: list with description, amount, account, "Every month on day 25", next date, paused badge; editor with the expense fields of S-7 except date, plus day of month, first month (default per AC-9.8, up to 12 months back), optional last month, pause switch; online only (FR-9, §13.3 S-19).
|
||
- Every settings write is online: a refused value comes back as `OnlineResult.Failed` with the §14.3.2 code and `field` (for example `validation_failed` on `name`), shown inline at that field (§9.6, §14.2.4, §14.3.2).
|
||
- Devices: rows per AC-3.1 ("This device" marked); revoke with confirmation; the current device cannot be revoked; admin sees all, member own (AC-3.1, AC-3.2).
|
||
- Invites (admin): "Invite partner" only before the partner joins, "Pair another device" for either user; a created invite shows the code in groups of 4, the link, expiry and an Android share action; pending invites with cancel (AC-2.1, AC-2.2, AC-2.11, §13.3 S-21).
|
||
- About: version name and code, server URL, server version from `/health` (null offline), open-source licences, "Check for update" (§13.3 S-22).
|
||
|
||
## 4. Owned paths
|
||
From SPEC §14.7, verbatim: `android/feature/settings/**` (owner M7f), and from the `android/core/fakes/**` row: "M7x add files only under `fakes/<feature>/`", here `android/core/fakes/src/main/kotlin/se/hagstedt/kvitt/fakes/settings/` (§11.3). Catalog entries and module includes may be added (§14.7, `android/gradle/**` row).
|
||
|
||
Edit nothing outside these paths; a needed change elsewhere is a contract request to the orchestrator.
|
||
|
||
## 5. Deliverables
|
||
- `android/feature/settings/build.gradle.kts`: dependencies `:core:model`, `:core:design`; `:core:fakes` for tests and debug only.
|
||
- `android/feature/settings/src/main/kotlin/se/hagstedt/kvitt/feature/settings/**`: the screens of this module and their state holders.
|
||
- `android/feature/settings/src/main/res/values/strings.xml`, `values-sv/strings.xml`: keys from `docs/ux/strings.csv`.
|
||
- `android/core/fakes/src/main/kotlin/se/hagstedt/kvitt/fakes/settings/**`: a scenario per state below.
|
||
- Screenshot tests and committed goldens for every screen × state × light/dark × sv/en.
|
||
- Unit tests for the state holders (input handling, enablement rules, error mapping).
|
||
|
||
Screens and states. Required states for every screen below (SPEC §13.3): **loaded**, **empty**, **offline** (with pending changes), **loading** (first sync only), **error** (a failed online action), and for lists **long content** (long Swedish names, 7-digit amounts), each where it applies. A state that `docs/ux/design-spec.md` marks not applicable for a screen is skipped and named in the report. Each state is screenshot-tested in light and dark, Swedish and English. Screen-specific states from §13.3 "Must show" are added per screen:
|
||
- **S-13**: admin; member; partner not yet joined; offline; long content (long names).
|
||
- **S-14**: with picture; initials only; upload in progress; error (`image_invalid`, `payload_too_large`, network); "Needs connection".
|
||
- **S-15**: list with archived section; editor for a default category (Reset name) and a custom one; icon grid; colour swatches; reorder in progress; delete not allowed with each reason; error; "Needs connection"; long content.
|
||
- **S-19**: list with active and paused templates; empty; editor new and edit (each split mode); start period in the past (backfill); end period set; error `validation_failed`; "Needs connection"; long content.
|
||
- **S-20**: admin with both users' devices incl. a revoked one; member with own devices; revoke confirmation; error `cannot_revoke_current_device`; "Needs connection"; loading.
|
||
- **S-21**: admin before partner joins; after partner joined (device invites only); created invite with code, link, expiry, share; pending list with cancel; error `household_full`; "Needs connection"; empty.
|
||
- **S-22**: online with server version; offline (server version unknown); check-for-update result states.
|
||
|
||
## 6. Steps
|
||
1. Worktree. From the main checkout `/Users/jhag/projects/kvitt`: `git worktree add .claude/worktrees/agent-m7f -b agent-m7f main`, then in `.claude/worktrees/agent-m7f`: `git reset --hard main`. Copy `android/local.properties` from the main checkout (add `sdk.dir=/opt/homebrew/share/android-commandlinetools` if missing; never overwrite or commit). Run `tools/install-git-hooks.sh`.
|
||
2. Read §2 in order. Confirm M6 has landed (`android/core/design/` has components on `main`); if not, stop and report. If a component the design spec assigns to `:core:design` is missing, file a contract request; do not build it inside the feature.
|
||
3. Run `python3 tools/dependency-report/latest.py`; record the lines. No new library is expected; any one added is at its latest stable version from official docs; record it.
|
||
4. Write the fake scenarios under the feature's `fakes/<feature>/` directory for every state listed in §5.
|
||
5. Write the state holders and screens, one screen at a time, with strings from `docs/ux/strings.csv` in both languages.
|
||
6. Write the screenshot tests; record goldens; open every PNG and compare with `docs/ux/screens/`.
|
||
7. Run the gate (§7). Commit on `agent-m7f`, `git rebase main`, rerun the gate. Never merge, push or remove the worktree.
|
||
|
||
## 7. Gate
|
||
From SPEC §11.2, verbatim: "as M7a", that is "Android gate with screenshot tests of every state, sv and en, light and dark".
|
||
Command, from `android/`: `PATH=/opt/homebrew/opt/openjdk@25/bin:$PATH ../tools/gradle-serial.sh check`.
|
||
Green means: `BUILD SUCCESSFUL` in this session; screenshot verification passes for `:feature:settings`; the report lists, per screen, every state × light/dark × sv/en golden; unit tests 0 failures in fresh XML.
|
||
|
||
## 8. HUMAN steps
|
||
From SPEC §11.2, verbatim: "none".
|
||
|
||
## 9. Out of scope
|
||
- Other screens: S-1, S-2, S-3, S-18 (M7a); S-4, S-5, S-6, S-16, S-17 (M7b); S-7, S-8 (M7c); S-9, S-10 (M7d); S-11, S-12 (M7e).
|
||
- Navigation graph, deep links, Hilt bindings, notifications (M8); real repositories (M5).
|
||
- Editing `:core:design` (requests go to the orchestrator) or `:core:model`; any dependency on `:data` or `:domain`.
|
||
- Fake scenarios outside this plan's `fakes/<feature>/` directories.
|
||
|
||
## 10. Report
|
||
- Branch `agent-m7f`, head commit hash after rebasing on `main`.
|
||
- Gate output: BUILD line, actionable tasks line, screenshot task result, test counts from fresh XML.
|
||
- Screens × states table with golden file names; states skipped as not applicable.
|
||
- Versions added (if any) with sources; dependency-report lines.
|
||
- Strings used that are missing from `strings.csv` (should be none) and design-spec mismatches.
|
||
- Proposed decision entries (never written to `SPEC.md` or `docs/decisions.md` by this agent) or `TODO(spec)` occurrences.
|
||
- Contract requests (`:core:design`, `:core:model`), open questions, spec gaps (with section numbers).
|
||
|
||
## 11. Numbering
|
||
Decision ids, spec version and schema version are assigned by the orchestrator in the start prompt; use `TODO(spec)` if none was given.
|