# PLAN-K2: Card purchases, Android

## 1. Goal
Card purchases in the Android app (FR-22, SPEC §9.12, D-169, D-170, D-172, D-173): the Kortköp tab as the second bottom destination, Anslut kort in Settings with the SJ Prio artwork, the BankID connect flow in a Custom Tab, the purchase sheet with "Skapa utgift", suggested matches and "Ignorera", "Från kortköp" on account detail, the card line on expense detail, offline-capable link changes, Room version 2. A UI-contract change (`:core:model` is a contract file, §14.8) with data layer, fakes, features and goldens.

## 2. Read first
1. SPEC §9.12 (CP-1 to CP-14, with K0's answers in v0.36), FR-22, §9.9, §9.11 (the suggestion on the prefilled description), §13.2 (four destinations), §13.3 rows S-5, S-7, S-8, S-13, S-23 to S-27 and the "Card purchase strings" table, §14.2 (§14.2.1 card entities, §14.2.3 version 2, §14.2.4 "Changes in v0.35"), §14.3.3 and §14.3.4 E-36 to E-44, §14.4.1, §14.5.8, §6.2 (module table, layering, feature convention), §14.7, §14.8 (compatibility); D-169, D-170, D-172, D-173, D-177 to D-180 (K0's results and the artwork).
2. K1's `contracts/openapi.yaml` operations E-36 to E-44, `contracts/examples/E-36-*` to `E-44-*`, `contracts/test-vectors/match_card_purchase.json` (on `main` once K1 lands; until then the spec).
3. `docs/ux/design-spec.md` §2 (tokens), §3.4, §3.5 (ledger rows), §3.6 (banners), §3.11 (scaffolding), S-4, S-5, S-8, S-13, S-16 (for list and banner patterns); `docs/ux/strings.csv`.
4. Files: `android/core/model/**`, `android/domain/**`, `android/data/**` (`KvittDatabase`, sync engine, `KvittApi`, `DataBindingsModule`), `android/core/fakes/**`, `android/core/design/**` (`KvittNavigationBar`, `KvittDestination`), `android/feature/{account,expense,settings}/**`, `android/app/**` (`nav/KvittApp.kt`, the manifest's intent filters), `android/README.md`.
5. `CLAUDE.md` (Android gate, layering, anti-patterns, screenshots, the phone, personal data).

## 3. Already established
- The UI contract of §14.2.4 "Changes in v0.35" is binding (names and members); additions need a decision, proposed in the report.
- New module `:feature:cards` (`android/feature/cards/`, package `se.hagstedt.kvitt.feature.cards`), included in `android/settings.gradle.kts`, following the feature convention (D-017): one entry composable per screen, navigation as lambdas, ViewModels on `:core:model` interfaces only, strings prefixed `cards_`.
- `:core:design`: `KvittDestination.Cards` between `Home` and `Analytics`, icon `credit_card` (Material Symbols, outlined like the others), label `nav_cards`; every top-level screen's bar shows four items, so the S-3, S-4, S-11, S-13 goldens change (re-record and open each).
- Card artwork (D-173, D-180): the owner's picture is committed at `android/feature/cards/src/main/res/drawable-nodpi/card_sj_prio_mastercard.png` (1313 × 829, cropped to the card, aspect 1.584; transparent only at its rounded corners and in the semicircular notch on the right edge, as on the physical card). `CardArt(imageKey, name, modifier)` in `:feature:cards` maps `sj_prio_mastercard` to `R.drawable.card_sj_prio_mastercard` from the first commit and draws it at its own aspect ratio inside the card box (`ContentScale.Fit`), without clipping or a background, so its own corners and notch show; content description the card's name. For any unknown key it draws the fallback card: aspect ratio 1.586:1, corner radius 16 dp, fill the `green` category token's light value in both themes, the card name in white (contrast 4.95:1), no other text. The goldens use the committed picture; one golden covers the fallback (a fake catalogue entry with an unknown image key). The picture shows the SJ and Mastercard logos; the owner cleared that use (2026-10-24, the "Licences first" step). Do not edit or re-encode the PNG.
- Custom Tab: `androidx.browser` (catalog entry, latest stable at implementation time, documented usage confirmed from the official docs). The deep link `kvitt://cards/connected?attempt=<id>` is an intent filter on `MainActivity` (exported already); `:app` routes it.
- Room version 2 with `MIGRATION_1_2` and its test (§14.2.3), the exported `2.json` committed. The revoke wipe includes the card tables.
- The card cycle (§14.2.4 `:data`) runs after every household sync cycle and after `refresh`; pending link changes go out after the household push (CP-9).
- `matchCardPurchase` in `:domain` passes `match_card_purchase.json` in the vector test.
- No card content in any log, debug builds included; no notification for card purchases (D-171).
- Strings: the keys of §13.3's table are added to `docs/ux/strings.csv` (en and sv) by this plan, with any TalkBack keys it needs (listed in the report); then to the modules' `strings.xml`.

## 4. Owned paths
From SPEC §14.7 (row K2): `android/feature/cards/**` (new), and as a contract-change plan `android/core/model/**`, `android/domain/**`, `android/data/**` (with `android/data/schemas/**`), `android/core/fakes/**`; `android/core/design/**` (the destination and `nav_cards` only), `android/feature/account/**` (S-5's action), `android/feature/expense/**` (S-7's prefill and link, S-8's line), `android/feature/settings/**` (S-13's row), `android/app/**` (navigation, deep link, bindings), `android/settings.gradle.kts`, `android/gradle/libs.versions.toml`, `docs/ux/strings.csv` (the card keys). Nothing in `server/**`, `contracts/**`, `web/**`, `SPEC.md`, `docs/decisions.md`.

## 5. Deliverables
- `:core:model` `model/Cards.kt` and the members of §14.2.4; `ContractTest` updated.
- `:domain` `matchCardPurchase` with its vector test.
- `:data`: DTOs for E-36 to E-44 with round-trip tests over K1's examples; `CardRepositoryImpl`; the card cycle with `MockEngine` tests (paging, tombstones, pending rows skipped on pull, the E-44 outcomes of §14.2.1, a 404 from E-40 as "no card support", `cursor_ahead`); `prefill` (CP-9) tests; the local unlink when an expense is deleted locally; Room 2 and the migration test.
- `:core:fakes`: `FakeCardRepository` and `fakes/cards/` scenarios for every state of S-23 to S-27 (§14.2.4 list).
- `:feature:cards`: S-23 (with the sheet and the second sheet "Välj en annan utgift"), S-24, S-25 (polling E-38 every 2 seconds while open and resumed, the Custom Tab, the return link), S-26 (with the disconnect dialog), S-27; screenshot tests of every state in the D-098 variants (sv light, sv dark, en light, plus `_sv_light_200` for the long states); state-holder unit tests.
- `:feature:expense`: S-7 with the optional `cardPurchaseId` argument (prefill, then `link` after a successful save; a foreign-currency purchase leaves the amount empty with the S-23 note), S-8's line "Från kortköp: <merchant>, <date>" with "Ta bort koppling"; goldens for the new states.
- `:feature:account`: S-5's overflow item "Från kortköp" while `hasConnection`; `:feature:settings`: S-13's row "Anslut kort" with its subtitle; goldens re-recorded where they change.
- `:app`: the fourth destination, routes for S-23 to S-27, the S-7 argument, the deep link, the binding in `DataBindingsModule`.

## 6. Steps
1. Worktree: from `/Users/jhag/projects/kvitt`, `git worktree add .claude/worktrees/agent-k2 -b agent-k2 main`; in it `git reset --hard main`; copy `android/local.properties` and `android/app/google-services.json` from the main checkout (never commit them); `tools/install-git-hooks.sh`.
2. Confirm SPEC v0.36 (K0's answers) is on `main`; if not, stop and report. K2 may start before K1 lands, on the spec and fakes; before its gate it rebases on K1 (DTO tests need K1's examples, the vectors file is K1's). If K1 has not landed when everything else is done, stop and report rather than inventing examples.
3. `python3 tools/dependency-report/latest.py`; record the lines.
4. Model, domain, data (Room 2 first, with its test), fakes, `:feature:cards`, the edits in the other features and `:app`, strings, goldens (open every changed PNG).
5. Phone (only if the brief names this agent for it; one agent on the phone at a time): confirm the ids (`adb shell pm list packages | grep se.hagstedt.kvitt`), `installDebug` of the debug app against the development stack for the screens and offline behaviour; the real BankID flow needs the release app against the Pi with K1 deployed (§8). Never clear the real app's data.
6. Gate (§7). Commit on `agent-k2`, `git rebase main`, rerun the gate. Never merge, push or remove the worktree.

## 7. Gate
The Android gate, from `android/`: `PATH=/opt/homebrew/opt/openjdk@25/bin:$PATH ../tools/gradle-serial.sh check`. Green: `BUILD SUCCESSFUL` in this session, test counts from fresh XML, screenshot verification passing.

## 8. HUMAN steps (relayed by the orchestrator in chat)
1. After K1 is deployed on the Pi and the K2 release APK is installed (Auto Blocker off for the update, back on afterwards): Inställningar › Anslut kort › SJ Prio Mastercard › 30 dagar › "Anslut med BankID"; BankID opens, sign; back in Kvitt "Kortet är anslutet" and the Kortköp tab lists your purchases (yes/no each).
2. Kortköp › a purchase › "Skapa utgift" › "Spara": the expense is in its account and the purchase is under "Kopplade" (yes/no).
3. On a purchase your partner already entered: the row shows "Koppla till …"; tap it: under "Kopplade" (yes/no).
4. Flight mode on: ignore a purchase, then flight mode off: it stays ignored after a sync (yes/no).
5. An account › menu › "Från kortköp": a purchase › "Spara": the expense is in that account (yes/no).
6. Inställningar › Anslut kort › SJ Prio Mastercard › "Koppla från" › "Koppla från": the Kortköp tab shows "Anslut ditt kort" and the linked purchases are kept under "Kopplade" after reconnecting (yes/no).
7. On the partner's phone (after she connects her card, PLAN-K1 §8 step 5): Kortköp shows only her purchases, and none of yours anywhere (yes/no).

## 9. Out of scope
- The server, the contract files, the web (K1, K3). A card notification (OQ-7), bulk add (OQ-8), automatic linking (D-171).
- Changes to `docs/ux/design-spec.md` (the report proposes the S-23 to S-27 design-spec sections for a docs agent).

## 10. Report
- Branch `agent-k2`, head commit after rebasing; gate lines; tests; goldens added and re-recorded (names).
- Proposed decision entries and spec text for anything beyond §14.2.4 (numbered from the brief); the strings added to `strings.csv` (keys); proposed design-spec sections for S-23 to S-27.
- Dependency-report lines; HUMAN steps outstanding worded for relay; open questions with SPEC section numbers.

## 11. Numbering
Room version 2; decisions from the start prompt (`TODO(spec)` if none was given). Proposed spec text goes into SPEC **v0.39** (v0.36 recorded K0's results, v0.38 K1's report; K3's goes into v0.40).