From 84250399ddb2db3181407b273d63476cc7587531 Mon Sep 17 00:00:00 2001 From: brother7 <7brother7@gmail.com> Date: Tue, 8 Sep 2026 23:26:08 +0800 Subject: [PATCH] docs: integrate reset card wallet --- .project-docs/20-architecture/data-flow.md | 1 + .../20-architecture/system-overview.md | 1 + .project-docs/30-worklog/current-state.md | 17 +++++++ ...08-integrate-reset-card-wallet-9c4e2a71.md | 51 +++++++++++++++++++ .project-docs/40-domain/business-rules.md | 8 +++ 5 files changed, 78 insertions(+) create mode 100644 .project-docs/30-worklog/tasks/20260908-integrate-reset-card-wallet-9c4e2a71.md diff --git a/.project-docs/20-architecture/data-flow.md b/.project-docs/20-architecture/data-flow.md index 6182cdc..5bdae78 100644 --- a/.project-docs/20-architecture/data-flow.md +++ b/.project-docs/20-architecture/data-flow.md @@ -14,6 +14,7 @@ | Hosted Game Resource operation and delivery | Eligible parent `makelore.game-resource` generate call plus one explicit confirmation | frozen Plugin adapter → Main delivery coordinator → one `GameResourceClient` submission → internal status polling → all terminal downloads → `assets/generated/game-resource//` in the frozen original project | Server policy owns pricing、payer、Admission 与 Provider receipt state；Main owns the durable local delivery receipt and filesystem. `submission_unknown` 不会作为新请求重放。重启或重试只恢复下载/保存，共享项目写租约仅在终态落盘期间持有；Agent 只收到一张进度/结果卡片，不暴露 status/save 工具，也不要求第二次确认。 | | 桌面认证生命周期 | Renderer 登录、刷新与注销请求 | Host API → Main Works Session → Works Square `/api/auth/{login,mobile-login,refresh,logout}` → one-feel auth | Main 加密持有并先持久化轮换 token；客户端不携带 OAuth client secret；连续 7 天未使用才清除会话，终止性 `400`/`401` fail closed | | Account Token Points V2 | 已登录账号菜单、窗口 focus 或重新可见 | Renderer → Main `/api/works/billing/points` → Works Square `/api/billing/points` → safe balance projection | 可管理会员的账号获得规范字符串点数与套餐/周期元数据；非管理者的精确字段全部置空，只投影 `shared_available`、共享/青少年类型和升级责任。旧 rolling-window usage API 与 stale event 不再参与。 | +| Expiring reset-card wallet | 已登录账号展开卡包或明确点击一张可用卡 | Renderer → Main `/api/works/billing/reset-cards[/{card_id}/redeem]` → Works Square `/api/billing/reset-cards[/{card_id}/redeem]` → strict card projection | 卡包延迟加载并显示运营赠卡的可用、已过期、已使用状态；Main 丢弃内部字段和未知错误文本，Renderer 对已到期或共享钱包禁用操作。只有服务端成功或幂等重放后才刷新卡包与 Token Point V2 余额；付费重置卡不经过此库存流。 | | 用户模块入口策略 | 会话恢复 / 登录 / 刷新 | Electron Main → Works `/api/auth/me` → 三布尔安全投影 → Renderer auth store → 卡片/路由/provider gate | 缺失对象或字段默认 `true`；`design` 映射 `painting`；额外旧字段被忽略；终止性 `401` 清理 Main/Renderer 会话；全局 `/settings` 不受 Code gate | | 项目创建 | 新建项目对话框中的目录选择 | Renderer 内部默认 `interactive_ai_app` → Host API → Main 生成 UUID 并原子初始化 | 普通用户不选择类型、模板或项目身份；只生成 `.makelore/project.json` 与 `knowledge/`，随后直接进入 `/chat`。既有 `custom`/历史类型和底层兼容入口仍保留 | | 旧项目身份补齐 | 有效 `.makelore/project.json` 仅缺 `projectId` | Main serialized config read/repair → canonical UUID persisted once | 并发读取共享同一次修复；原始 UUID、bind/independent-copy 控件不进入普通 UI。其他缺失或无效 metadata 仍是配置错误；`initialized` 不阻断有效项目 | diff --git a/.project-docs/20-architecture/system-overview.md b/.project-docs/20-architecture/system-overview.md index 5d59b9b..6cd2c0f 100644 --- a/.project-docs/20-architecture/system-overview.md +++ b/.project-docs/20-architecture/system-overview.md @@ -15,6 +15,7 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展 | Project Release Builder | Main-owned 安全快照、本地 npm/Vite 构建、双归档与 artifact contract | 固定 npm 11.6.2；Vite 由项目 lockfile 锁定；产物与预检使用同一内存字节 | | Works Session & Remembered Password | Main-owned 登录、刷新、注销、七天真实活动滑动续期与可选密码回填 | 登录、刷新、注销统一经过 Works Square；轮换凭据由 Main 安全持有和持久化。记住密码使用独立的 packaged-only OS 加密记录，不进入 Renderer 持久状态或 Works Square；客户端不携带 OAuth client secret | | Token Points V2 | Main-owned `/api/works/billing/points` 安全投影 → Renderer 账号菜单 | 会员管理者可查看套餐、本周与总余额及刷新时间；非管理者只获得 `shared_available` 粗粒度状态，套餐、周期和精确点数统一投影为 `null` | +| Reset Card Wallet | Main-owned `/api/works/billing/reset-cards` list/redeem 安全投影 → Renderer 账号菜单卡包 | 仅展示 Works Square 的 owner-scoped 运营赠卡，客户端派生已到期状态但不计算重置额度、不乐观成功；服务端确认后同步刷新卡包与 Token Point V2 余额。付费重置卡仍由支付成功立即履约，不进入卡包。 | | Module Access Policy | Main-owned `/api/auth/me` projection → Renderer auth state → module chooser/router | Renderer 只接收 Code/Canvas/Robot 三个布尔值；缺失对象或字段默认开启，服务端 `design` 映射客户端 `painting`，额外旧字段被忽略 | | Submission Binding | 保存云端已接受的精确 app/version/review/hash 绑定 | schema v2 只记录成功提交；旧中间态迁移为 `legacy_retired`，不恢复后台任务 | | Play URL Projection | 校验服务端公共播放地址 | 只接受同源 HTTPS 和精确 `/apps/{app_id}/`；优先 `play_url`，`runtime_url` 仅一版本回退 | diff --git a/.project-docs/30-worklog/current-state.md b/.project-docs/30-worklog/current-state.md index 6c9a080..540e668 100644 --- a/.project-docs/30-worklog/current-state.md +++ b/.project-docs/30-worklog/current-state.md @@ -4,6 +4,23 @@ This file is the integrated default-branch snapshot. Feature tasks record progre ## Integrated Through +- Expiring reset-card wallet source commit + `01525834fd326a0fbcd6f537b11d6f278470f992` from task + `20260908-reset-card-wallet-client-6c3e8a1f` is integrated onto local `main` by + task `20260908-integrate-reset-card-wallet-9c4e2a71`. The account menu now owns a + lazy-loaded reset-card wallet backed by Main-owned list/redeem routes and the Works + Square billing authority. It shows available, elapsed, and redeemed Operations + grants with explicit local-time expiry, blocks known-expired and family-shared + redemption attempts, and refreshes both the card list and authoritative Token Point + V2 balance only after server-confirmed fulfillment. Paid reset-card checkout remains + an immediate server-side reset and does not enter this inventory. Source verification + passed 78 focused tests, typecheck, scoped and full lint, all Vite production targets, + and 3/3 Electron E2E runs. The full unit run's only failure was the previously + recorded Pi real-process two-second cold timing assertion, which passed 6/6 in + isolation; no Pi code was changed. A compatible Works Square deployment with + migration `20260908_reset_card_grants_0087` and a rebuilt client remain release + gates; no package, deployment, production mutation, remote push, or publication is + claimed. - AI Design confirmation-handoff client source commit `1a52831b26a226ee675c815e8975b4258a10fa18` from task `20260908-design-confirmation-handoff-client-8c3f1a72` is integrated as product diff --git a/.project-docs/30-worklog/tasks/20260908-integrate-reset-card-wallet-9c4e2a71.md b/.project-docs/30-worklog/tasks/20260908-integrate-reset-card-wallet-9c4e2a71.md new file mode 100644 index 0000000..6606b3d --- /dev/null +++ b/.project-docs/30-worklog/tasks/20260908-integrate-reset-card-wallet-9c4e2a71.md @@ -0,0 +1,51 @@ +# Task: Integrate Makelore reset card wallet + +## Identity + +- Task ID: 20260908-integrate-reset-card-wallet-9c4e2a71 +- Mode: Integration +- Branch: codex/20260908-integrate-reset-card-wallet-9c4e2a71-integrate-reset-card-wallet +- Worktree: D:\Datas\OthersProjects\.codex-worktrees\makelore\20260908-integrate-reset-card-wallet-9c4e2a71 +- Base commit: 01525834fd326a0fbcd6f537b11d6f278470f992 +- Owner: codex +- Status: In Progress + +## Scope + +- Integrate exact client source commit + `01525834fd326a0fbcd6f537b11d6f278470f992` from Feature task + `20260908-reset-card-wallet-client-6c3e8a1f` onto local `main`. +- Promote the Main-owned reset-card proxy boundary, account-menu wallet flow, and + paid-versus-granted-card distinction into canonical project memory. +- Verify the exact integrated tree, advance `main` by fast-forward only, and preserve + the three adopted foreign task records in the primary worktree byte-for-byte. + +## Intent And Constraints + +- Keep Works credentials, DTO filtering, and safe error mapping in Electron Main; + Renderer must not call Works Square directly or receive internal grant/audit data. +- Keep server-confirmed redemption authoritative and refresh both cards and Token Point + balance after fulfillment; do not introduce optimistic success or local allowance + calculation. +- Preserve youth-owned entitlement support and family-shared redemption blocking; + Works Square remains the final ownership authority. +- Preserve paid reset-card immediate fulfillment as a separate non-inventory flow. +- Do not change product code during Integration, package or publish an installer, + deploy a service, push a remote branch, or touch the three adopted task records. + +## Outcome + +- Not completed. + +## Verification + +- Not run. + +## Follow-ups + +- None recorded. + +## Promotion Candidates + +- In progress: promote reset-card wallet facts to `current-state.md`, + `system-overview.md`, `data-flow.md`, and `business-rules.md`. diff --git a/.project-docs/40-domain/business-rules.md b/.project-docs/40-domain/business-rules.md index 361765e..41f0844 100644 --- a/.project-docs/40-domain/business-rules.md +++ b/.project-docs/40-domain/business-rules.md @@ -5,6 +5,14 @@ - Marketplace Release A is curated: only Operations publishes packages. Users may acquire an eligible Plugin for free; only server-declared metered operations may later consume Token Points, and system-included Data Service remains zero-charge. +- Operations-granted reset cards are owner-scoped, expiring inventory and are distinct + from paid reset-card checkout, which Works Square fulfills immediately without + inventory. Renderer may display only the strict public card projection, derive an + elapsed available card as expired, and request redemption for the signed-in owner; + it must not calculate the reset allowance, expose internal grant/audit fields, treat + a shared wallet as redeemable, or claim success before Works Square confirms it. + Confirmed fulfillment refreshes both the card list and authoritative Token Point V2 + balance. - Account Library, Device Installation, project enablement, Agent assignment, runtime authorization, and billing are separate states. No read, install, acquisition, or assignment may silently advance another state. The code-owned project-wide identities