docs(16.3-02): complete admin SPA API tokens card plan

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-11 02:07:48 +02:00
parent e17207a00d
commit fd07e2637f
1 changed files with 190 additions and 0 deletions
--- a/.planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/16.3-02-SUMMARY.md
+++ b/.planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/16.3-02-SUMMARY.md
@@ -0,0 +1,190 @@
+---
+phase: 16.3-backend-admin-personal-api-tokens-with-scopes
+plan: 02
+subsystem: ui
+tags: [admin-spa, api-tokens, account, vue, reka-ui, phrasebook, show-once]
+
+requires:
+  - phase: 16.3-backend-admin-personal-api-tokens-with-scopes
+    provides: account token API, OpenAPI/TS types, plan 01 api_tokens phrase seeds
+provides:
+  - "ApiTokensPanel on /account after the profile form"
+  - "ApiTokenCreateDialog two-step create with show-once plaintext"
+  - "List states, show-revoked toggle, revoke via shared ConfirmDialog"
+  - "SPA api_tokens.* phrase keys (en/pl) and myaccount.menu_description"
+  - "Rebuilt modules/boardwalk/dist and My account docs"
+affects: [16.3-03, 16.3-04]
+
+actuals:
+  tokens: 17683
+  tasks: 3
+  commits: 4
+plan_head_before: 93a3112fb7a9c9d181607b473fde1f051eea778b
+plan_head_after: e17207a
+
+tech-stack:
+  added: []
+  patterns:
+    - "Account panel shares AccountView useConfirm(); ConfirmDialog stays at z-[90]"
+    - "Plaintext only in dialog-local ref; cleared on Done, confirmed close, onBeforeUnmount"
+
+key-files:
+  created:
+    - admin/src/components/account/ApiTokensPanel.vue
+    - admin/src/components/account/ApiTokenCreateDialog.vue
+    - admin/tests/account/ApiTokensPanel.test.ts
+  modified:
+    - admin/src/views/AccountView.vue
+    - admin/src/components/ui/ConfirmDialog.vue
+    - admin/src/api/types.ts
+    - admin/tests/views/AccountView.test.ts
+    - admin/tests/fixtures/lang.json
+    - modules/phrasebook/backend/lang/en/lang.yaml
+    - modules/phrasebook/backend/lang/pl/lang.yaml
+    - modules/boardwalk/dist
+    - docs/backend/users-and-permissions.md
+    - docs/backend/admin-spa.md
+
+key-decisions:
+  - "Panel/dialog split per plan: ApiTokensPanel owns list/revoke; ApiTokenCreateDialog owns plaintext"
+  - "Hint renders as g15_… plus API hint (last4); scope chips use server label/known"
+  - "expired from API drives Expired chip (server clock)"
+
+patterns-established:
+  - "My account cards outside the profile form share one ConfirmDialog"
+  - "Show-once secrets stay in dialog state only — never toasts, storage, URL or list rows"
+
+requirements-completed: [SC-3, SC-5]
+
+coverage:
+  - id: D1
+    description: "My account API tokens card lists, creates (show-once) and hides plaintext"
+    requirement: SC-3
+    verification:
+      - kind: unit
+        ref: admin/tests/account/ApiTokensPanel.test.ts#tracer: list, create, show once, hide
+        status: pass
+    human_judgment: false
+  - id: D2
+    description: "List loading/empty/error, show-revoked toggle, revoke via ConfirmDialog"
+    requirement: SC-3
+    verification:
+      - kind: unit
+        ref: admin/tests/account/ApiTokensPanel.test.ts#list states
+        status: pass
+      - kind: unit
+        ref: admin/tests/account/ApiTokensPanel.test.ts#revoke
+        status: pass
+    human_judgment: false
+  - id: D3
+    description: "Create dialog scope *, 422 focus, clipboard copy/fallback, close-without-copy"
+    requirement: SC-3
+    verification:
+      - kind: unit
+        ref: admin/tests/account/ApiTokensPanel.test.ts#dialog rules
+        status: pass
+    human_judgment: false
+  - id: D4
+    description: "My account docs describe the API tokens SPA card"
+    requirement: SC-5
+    verification:
+      - kind: other
+        ref: go test -count=1 ./cmd/summer -run TestDocsTree
+        status: pass
+    human_judgment: false
+
+duration: 9min
+completed: 2026-10-11
+status: complete
+---
+
+# Phase 16.3 Plan 02: Admin SPA API tokens card Summary
+
+**My account API tokens card with list states, two-step show-once create/copy, revoke via shared ConfirmDialog, phrase keys, dist and docs.**
+
+## Performance
+
+- **Duration:** 9 min
+- **Started:** 2026-10-10T23:57:24Z
+- **Completed:** 2026-10-11T00:06:49Z
+- **Tasks:** 3
+- **Files modified:** 17
+
+## Accomplishments
+- `ApiTokensPanel` after the profile form on `/account`; Create token, list, show-revoked, revoke
+- `ApiTokenCreateDialog`: name/expiry/scopes → show-once plaintext, copy with clipboard fallback, close-without-copy confirm
+- Full `backend::lang.api_tokens.*` en/pl copy, Polish lang fixture, rebuilt `modules/boardwalk/dist`, My account docs
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Tracer — list, create, show once, hide** - `5a6a190` (feat)
+2. **Task 2: List states, show-revoked, revoke, ConfirmDialog wrap** - `1c930b6` (feat)
+3. **Task 3: Dialog rules smoke tests and My account docs** - `e17207a` (feat)
+
+**Plan metadata:** (this commit)
+
+## Component contracts
+
+| Component | Props | Emits |
+|-----------|-------|-------|
+| `ApiTokensPanel` | `confirm: ReturnType<typeof useConfirm>` | — |
+| `ApiTokenCreateDialog` | `open`, `confirm` | `update:open`, `created`, `closed` |
+
+## Smoke test names
+
+- `tracer: list, create, show once, hide`
+- `list states` (skeleton→empty; load failure)
+- `revoke` (DELETE confirm; 404 gone; show-revoked)
+- `dialog rules` (`*` posts `["*"]`; 422 scopes focus; clipboard; close-without-copy)
+
+## Files Created/Modified
+- `admin/src/components/account/ApiTokensPanel.vue` — card, list states, revoke
+- `admin/src/components/account/ApiTokenCreateDialog.vue` — two-step create dialog
+- `admin/src/views/AccountView.vue` — panel after `</form>`, shared confirm
+- `admin/src/components/ui/ConfirmDialog.vue` — `[overflow-wrap:anywhere]` on description
+- `admin/tests/account/ApiTokensPanel.test.ts` — tracer, list, revoke, dialog rules
+- `modules/phrasebook/backend/lang/{en,pl}/lang.yaml` — SPA api_tokens keys
+- `docs/backend/users-and-permissions.md`, `docs/backend/admin-spa.md` — My account tokens card
+
+## Decisions Made
+- Followed plan/UI-SPEC component split and date formatting (CellValue shapes).
+- `expired` from the API drives the Expired chip; client clock is not used for that label.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Polish lang fixture for new phrase keys**
+- **Found during:** Task 1 (AccountView / panel tests use `langFixture` Polish bundle)
+- **Issue:** Plan listed en/pl YAML only; without `admin/tests/fixtures/lang.json` keys, SPA strings fall back to key paths and assertions on Polish copy fail.
+- **Fix:** Injected all `backend::lang.api_tokens.*` Polish strings and updated `myaccount.menu_description` in the fixture.
+- **Files modified:** `admin/tests/fixtures/lang.json`
+- **Verification:** AccountView and ApiTokensPanel tests pass with Polish copy
+- **Committed in:** `5a6a190` (Task 1)
+
+---
+
+**Total deviations:** 1 auto-fixed (1 blocking)
+**Impact on plan:** Required for green admin tests; no scope creep.
+
+## Issues Encountered
+None
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+SPA half of SC-3 is in place. Ready for 16.3-03 (Journal scopes + ResolveBackend writes) and 16.3-04 (full unit/backstop matrix).
+
+## Self-Check: PASSED
+
+- Key files exist on disk
+- Commits grepped for 16.3-02: 3 task commits
+- Task acceptance greps and plan verification commands re-run green (typecheck, full admin vitest 1228, check-admin-dist, TestDocsTree)
+
+---
+*Phase: 16.3-backend-admin-personal-api-tokens-with-scopes*
+*Completed: 2026-10-11*