docs: integrate permanent point wallet into main

.project-docs/20-architecture/data-flow.md

@@ -1,5 +1,15 @@
 # Data Flow
 
+## Permanent wallet and recharge
+
+账号菜单 / PointWallet → `src/lib/works-billing.ts` → Main 固定 `/api/works/billing/*` 路由 → Works Square 账务 API。Main 持有认证与账号绑定，通过 `shared/works-billing.ts` 的公开 DTO 投影余额、产品、订单及流水；充值沿用 Renderer capability，Renderer 不传付款人、价格、Token 或任意上游地址。账号切换后 Main 与账号绑定的 UI 丢弃迟到结果，打开菜单和窗口 focus 刷新当前账号。
+
+本人点数与 AI 编程已选付款来源分开呈现。`shared_available` 为布尔值时只向 Renderer 提供另一付款方的可用性，精确余额置空；为 `null` 时保留本人规范字符串余额，即使 `family_shared=true` 且来源为 `self` / `shared_group`。充值资格来自服务端，不能用旧会员管理权限或共享标记推算。云智能体创建者付款与 Plugin 个人付款不受 AI 编程来源选择改变。
+
+明确充值 → 稳定 request identity 创建订单 → 冻结订单金额/点数与支付信息 → GET 恢复/查询原订单 → 服务端确认入账 → 刷新本人余额与流水。请求结果不明时保留原 identity，不自动重放 POST；已有待支付/人工核对订单先恢复，不能另建替代订单。商品改价不改变旧订单，支付二维码或用户声称支付不构成到账证据。网页续付和付款来源管理只打开固定账号页。
+
+规则与证据见[永久点数规则](../40-domain/business-rules.md#permanent-token-points)及[集成记录](../30-worklog/tasks/20260922-integrate-permanent-points-client-38f5b921.md)。
+
 ## Game Audio generation and local delivery
 
 Project-enabled optional bundled Game Audio → frozen eligible parent tool → one explicit
@@ -55,8 +65,7 @@ Main 在接收带图消息时立即将上传 attachment id 放入 optimistic use
 | Plugin workspace navigation | Project Configuration `插件` ResourceCard or compatibility URL | `/project-config/plugins` → Project Configuration remains mounted → same-page wide Plugin sheet → unified Plugin stores/Main routes | Code sidebar has no standalone Plugin entry. `/plugins` and old Plugin URLs only preserve query/filter intent while redirecting; embedding does not merge acquisition, install, project enablement, assignment, runtime authorization, or billing lifecycles. |
 | 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/<executionId>/` 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 余额；付费重置卡不经过此库存流。 |
+| Permanent Token Point Wallet | 已登录账号菜单、窗口 focus、明确充值或恢复订单 | Renderer → Main `/api/works/billing/*` → Works Square 固定账务 API → safe wallet/order projection | 本人精确余额与另一付款方可用性分开；稳定充值身份、冻结订单、原单恢复与服务端确认入账遵循上方数据流。会员、周额度与重置卡流程已移除。 |
 | 用户模块入口策略 | 会话恢复 / 登录 / 刷新 | 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` 不阻断有效项目 |
@@ -128,4 +137,4 @@ Main 在接收带图消息时立即将上传 attachment id 放入 optimistic use
 
 ## Last Updated
 
-2026-09-15
+2026-09-22

.project-docs/20-architecture/module-map.md

@@ -16,7 +16,7 @@
 | `shared/project-config.ts`, `electron/coding-projects/{project-config,project-service}.ts`, and `src/components/layout/Sidebar.tsx` | 规范 `ProjectType`、Main-owned UUID 与目录式最小项目创建 | 普通新建只要求目录，内部默认 `interactive_ai_app`，Main 自动生成 UUID；有效旧配置仅缺 `projectId` 时串行修复。既有 `custom` 和历史类型仍兼容，`initialized` 不再是导航 gate |
 | `resources/coding-plugins/project-scaffold/` and `tests/project-scaffold/` | 官方 bundled Scaffold Plugin、固定六文件模板、确定性 Node 脚本、发布要求参考与回归测试 | 通过既有 Pi `bash` write lease 和 `MAKELORE_NODE_EXECUTABLE` 显式运行；脚本信任来自固定客户端资源，而非下载 artifact；不覆盖、不安装依赖、不联网，也不复制 build/upload/review 实现 |
 | `src/lib/works-square.ts` | Renderer 侧 Works Square Host API 契约与安全错误映射 | 不接触 Token、ZIP、本地绝对路径或自动部署状态 |
-| `electron/api/routes/works.ts`, `src/lib/works-square-token-points.ts`, and `src/components/layout/Sidebar.tsx` | Token Points V2 的 Main-owned 上游代理、安全 DTO 投影、格式化与账号菜单状态 | 管理者可见规范字符串点数与周期；非管理者只见粗粒度可用性。旧 rolling-window usage contract 和 Renderer stale event 已删除。 |
+| `electron/api/routes/works-billing.ts`, `shared/works-billing.ts`, `src/lib/works-billing.ts`, `src/components/account/PointWallet.tsx` and `src/components/layout/Sidebar.tsx` | 永久词元点数的 Main-owned 认证与公开 DTO、个人余额、充值/订单恢复、流水及账号菜单 | 本人余额精确可见；另一付款方用 `shared_available` 表示可用性，不以 `family_shared` 或旧会员权限推测。显式充值意图复用请求身份，服务端确认后到账；旧订阅/重置卡入口及 DTO 已移除。 |
 | `electron/api/routes/works.ts` | Works Host API、Renderer capability 门禁、上游安全投影 | 发布凭据、打包、上传与本地绑定均在 Main 内完成 |
 | `electron/services/project-release-builder.ts` | Main-owned 安全快照、本地 npm/Vite 构建、source+built 双归档与 v1 contract | 固定 npm 11.6.2；项目 Vite 由 lockfile 决定；Vite config/plugins 以桌面用户权限执行 |
 | `electron/services/publish-runtime.ts` | 安装包内 npm 闭包定位与 Electron Node 执行 | 不回退全局 npm/PATH；缺失或版本不符 fail closed |
@@ -91,4 +91,4 @@
 
 ## Last Updated
 
-2026-09-07
+2026-09-22

.project-docs/20-architecture/system-overview.md

@@ -28,8 +28,7 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
 | Project Scaffold Skill | 显式生成固定版本的交互式 AI 应用起步文件，并提供发布准备度指导 | 官方 `makelore.project-scaffold` bundled Marketplace Plugin；账号已获取且项目启用后自动提供给每个父 Agent，不需要伙伴分配，child 为空；它不是创建或聊天前置条件。完整预检、不覆盖、受控回滚，不安装依赖、不联网、不构建、不上传、不提审。 |
 | 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 余额。付费重置卡仍由支付成功立即履约，不进入卡包。 |
+| Permanent Token Point Wallet | Main-owned `/api/works/billing/*` 固定路由、安全投影 → Renderer 账号菜单与 PointWallet | 本人精确余额、充值、冻结订单恢复与流水；另一付款方仅投影可用性。真实新注册赠 100 点，充值 1 元兑 50 点、永不过期，旧权益取消。Main 持有认证，稳定请求身份避免模糊结果重复下单；只有服务端确认后才显示入账，旧会员/重置卡入口已移除。 |
 | Module Access Policy | Main-owned `/api/auth/me` projection → Renderer auth state → module chooser/router | Renderer 接收 Code/Canvas/Robot/Agents 四个布尔权限；服务端 `design` 映射客户端 `painting`，云模块两端均为 `cloud_agents`；缺失对象/字段默认开启，额外字段被忽略 |
 | Submission Binding | 保存云端已接受的精确 app/version/review/hash 绑定 | schema v2 只记录成功提交；旧中间态迁移为 `legacy_retired`，不恢复后台任务 |
 | Play URL Projection | 校验服务端公共播放地址 | 只接受同源 HTTPS 和精确 `/apps/{app_id}/`；优先 `play_url`，`runtime_url` 仅一版本回退 |
@@ -126,4 +125,4 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
 
 ## Last Updated
 
-2026-09-15
+2026-09-22