102 lines
5.5 KiB
Markdown
102 lines
5.5 KiB
Markdown
# 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.
|