# Task: Trace current MakeLore membership and usage display values

## Identity

- Task ID: 20260906-trace-makelore-usage-3d7a5c1e
- Mode: Feature
- Branch: codex/20260906-trace-makelore-usage-3d7a5c1e-trace-makelore-usage
- Worktree: D:\Datas\OthersProjects\.codex-worktrees\makelore\20260906-trace-makelore-usage-3d7a5c1e
- Base commit: 5c61110f465cc4172f712ad435c06041c0aed1ec
- Owner: codex
- Status: Ready for Integration

## Scope

- Trace how the account menu previously obtained membership level, five-hour usage,
  and seven-day usage, and verify the matching Works Square contract.
- Migrate the Renderer and Electron Main transport from the retired rolling-window
  DTO to `GET /api/billing/points` and the Token Point V2 balance DTO.
- Replace the obsolete percentage rows with current-week and total Token Point
  balances, while preserving explicit loading, error, exhaustion, and family-shared
  states.

## Intent And Constraints

- Keep Works credentials and billing authority in Electron Main/Works Square; the
  Renderer only formats a safe balance projection and never derives ledger values.
- Preserve the V2 privacy boundary: any non-manager receives only the coarse
  `shared_available` result, not the plan, cycle, or exact balances. This includes
  both family-shared members and youth users with a self entitlement.
- Keep the existing Renderer -> Host API -> Electron Main -> Works Square ownership
  chain and avoid unrelated account, runtime, or browser changes.
- Do not modify or deploy Works Square server code from this client feature task.

## Outcome

- Replaced the client call with `fetchWorksTokenPointBalance`, using the local route
  `/api/works/billing/points`; Electron Main now forwards authenticated requests to
  Works Square `GET /api/billing/points`.
- Added a strict Main-process V2 projection. Invalid point strings or malformed
  entitlement metadata produce a safe 502 response, and every non-managing account
  has plan, cycle, and exact point fields cleared even if upstream includes them.
- The account menu now gets the membership label from V2 `plan_name`/`plan_code`,
  removes the retired five-hour and rolling-week percentage rows, and displays
  `weekly_remaining / weekly_allowance`, `total_remaining`, and `next_refresh_at`.
- Loading and retrieval failures are distinct UI states. A failure no longer appears
  as `不限` or as a fabricated zero balance, and the user can retry explicitly.
- Shared members see `共享会员` plus only `共享额度` availability. When exhausted they
  are directed to the family administrator and are not shown a self-service upgrade
  action.
- Youth users with a self entitlement also follow the coarse-availability contract:
  they see `青少年账户`, no exact balances, and a parent-contact message instead of
  a self-service upgrade action.
- Removed the unused V1 percentage formatter/exhaustion helper and stale-event retry
  module. Initial login, focus, visibility, and account-menu refreshes remain intact.
- No Works Square server source, deployment, packaged client, or live account state
  was changed.

## Verification

- Passed focused client, Main route, formatter, privacy, error-state, and Sidebar UI
  tests:
  `pnpm exec vitest run tests/unit/works-square.test.ts tests/unit/works-routes.test.ts tests/unit/works-square-token-points.test.ts tests/unit/sidebar-token-points.test.tsx --maxWorkers=2`
  (4 files, 72 tests).
- Passed `pnpm run typecheck`.
- Passed scoped ESLint over every changed TypeScript/TSX source and test file.
- Passed `pnpm run build:vite` for Renderer, Electron Main, preload, and utility
  bundles. Vite reported only the repository's existing dynamic-import/chunk-size
  advisory warnings.
- Passed `git diff --check` and a source/test scan found no remaining account-menu V1
  symbol, retired local route, or rolling-percentage reference.
- The matching server contract and youth-account tests passed during the trace:
  `tests/test_token_points.py::test_v2_billing_contract_exposes_points_and_retires_legacy_endpoints`
  and
  `tests/test_token_points.py::test_youth_v2_billing_is_read_only_and_rejects_reset_card_checkout`
  (2 passed).

## Follow-ups

- Integrate the task branch into the intended MakeLore release branch.
- Verify that the deployed Works Square API image and database are on the V2 release
  and migration head; source inspection cannot establish live deployment state.
- A signed-in packaged-client smoke against the deployed V2 service remains useful
  release evidence; it was not run because this task does not authorize deployment,
  installation, or live-account mutation.

## Promotion Candidates

- Target canonical document: `.project-docs/30-worklog/current-state.md`.
- Proposal: record that the account menu consumes the V2 Token Point balance, shows
  weekly remaining/allowance and total available points, has explicit loading/error
  states, and exposes only coarse availability to every non-managing account.
- Evidence: focused 72-test pass, typecheck, scoped lint, production Vite build, and
  the two server V2 contract tests listed above.
- Future impact: account-menu changes must not restore the retired rolling-window
  endpoint or derive exact balances in Renderer; non-manager privacy remains a
  Main/Works contract boundary, regardless of whether the entitlement is shared.
- Semantic conflicts: none known. This replaces a client path already retired by the
  authoritative V2 server contract.
- Human confirmation required: no additional product choice is required; the user
  explicitly requested the V2 migration. Canonical promotion still belongs to an
  Integration Gate task.