Files
makelore/.project-docs/30-worklog/tasks/20260908-reset-card-wallet-client-6c3e8a1f.md
T

5.3 KiB

Task: Integrate expiring reset-card wallet into Makelore desktop

Identity

  • Task ID: 20260908-reset-card-wallet-client-6c3e8a1f
  • Mode: Feature
  • Branch: main
  • Worktree: D:\Datas\OthersProjects\makelore
  • Base commit: 91ae7912ab
  • Owner: codex
  • Status: Ready for Integration

Scope

  • Add Electron Main-owned Works Square proxy routes for listing and redeeming expiring reset-card grants.
  • Strictly project the public reset-card DTO before it reaches Renderer and preserve only a closed set of redemption error codes.
  • Add a reset-card wallet to the existing account menu with available, expired, and redeemed states, explicit expiry, and manual redemption.
  • Refresh both the reset-card wallet and authoritative Token Point V2 balance after successful redemption.
  • Add focused Main route, Renderer API, component, and user-visible interaction coverage.

Intent And Constraints

  • Keep Works credentials and upstream response shaping behind the existing Host API/Main route boundary; do not add direct Renderer-to-Works requests or new IPC contracts.
  • Treat Works Square /api/billing/reset-cards and /api/billing/reset-cards/{card_id}/redeem as the authority; the client must not calculate reset allowances or mutate card state optimistically.
  • Operations-granted cards are manually redeemed inventory with an explicit expiry. Existing paid reset-card immediate fulfilment is unchanged and is not represented as desktop inventory.
  • Allow a self-owned youth entitlement to redeem its card, but disable redemption while the current balance is family-shared; the server remains the final ownership authority.
  • Derive an available card as expired when its expires_at is no longer in the future so stale UI cannot invite a known-invalid redemption.
  • A successful or idempotently replayed redemption must refresh the card and balance authorities. Definitive failures must remain retryable by the user without inventing a new mutation identity or local success.
  • Use the existing Makelore light visual system, compact account-menu disclosure, tabular dates, specific transitions, and at least 40px redemption targets.
  • Preserve and do not commit the three adopted foreign task records from 20260901-20260902.

Outcome

  • Added Main-owned reset-card list/redeem routes that authenticate upstream with the existing Works token, strictly project the public card DTO, derive elapsed available cards as expired, and expose only a closed set of safe redemption errors to Renderer.
  • Added typed Renderer helpers for the Host API routes without introducing direct Renderer-to-Works requests or a new IPC contract.
  • Added an account-menu reset-card wallet with lazy loading, available-card count, explicit local-time expiry, available/expired/redeemed states, retry handling, and a 40px manual redemption action.
  • Kept operations-granted cards separate from the existing Token Point balance rows and existing immediate paid reset-card flow.
  • Prevented known-expired or family-shared-wallet redemptions in the client while retaining the server as the final authority; successful server fulfillment refreshes both the authoritative card list and Token Point V2 balance.
  • Added Main route, Renderer helper, component, and Electron interaction coverage, including strict projection, safe error mapping, local expiry, shared-wallet behavior, single redemption, and post-redemption balance refresh.

Verification

  • pnpm exec vitest run tests/unit/works-routes.test.ts tests/unit/works-square.test.ts tests/unit/sidebar-token-points.test.tsx --maxWorkers=2 — 3 files / 78 tests passed.
  • pnpm exec eslint electron/api/routes/works.ts src/lib/works-square.ts src/components/layout/Sidebar.tsx tests/unit/works-routes.test.ts tests/unit/works-square.test.ts tests/unit/sidebar-token-points.test.tsx tests/e2e/reset-card-wallet.spec.ts — passed with no warnings or errors.
  • pnpm run typecheck — passed.
  • pnpm run lint:check — passed with 0 errors and the repository's 5 existing warnings in unchanged Home/Makelore files.
  • pnpm run build:vite — Renderer, Main, Preload, and utility production builds passed; only the repository's existing Browserslist/import/chunk-size warnings were emitted.
  • pnpm exec playwright test tests/e2e/reset-card-wallet.spec.ts --repeat-each=3 — 3/3 Electron runs passed.
  • pnpm test — 224 files / 1,952 tests passed and 2 skipped before the existing Pi real-process cold timing assertion measured 2,124ms against its 2,000ms threshold; the same file then passed 6/6 in isolation with one worker, and the separately invoked pressure test passed 1/1. This recurring unrelated timing shape is already recorded in prior project tasks and does not intersect the reset-card paths.
  • git diff --check — passed.

Follow-ups

  • Deploy the Works Square reset-card backend and apply Alembic revision 20260908_reset_card_grants_0087 before shipping or enabling this client wallet against that environment.
  • Rebuild/release Makelore together with the compatible server version, then smoke-test one Operations grant, one desktop redemption, and the resulting authoritative weekly balance refresh.

Promotion Candidates

  • During Integration, update the canonical desktop billing data-flow/current-state documentation with the Main-owned reset-card proxy boundary and account-menu wallet behavior.