makelore/.project-docs/30-worklog/tasks/20260906-trace-makelore-usage-3d7a5c1e.md

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: 5c61110f46
• 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.