docs(会员计费): 同步评审第 13–20 项的契约与实现口径

- 后端架构文档：充点商品写入口收敛为 9 个字段，退役列保留且写死 0；首充赠送统一为 0 - 技术设计 §2.5/§5.7：补 ProfileMembershipStatusToken 与 5 个 token 枚举的 ts-rs 生成说明 - 技术设计 §11.4：AgcModelResolveError 增 NoModelForTier，模型解析错误统一走 typed AppError - 决策记录：新增第 13–20 项收口条目，含影响范围与验证结论
2026-10-04 21:56:26 +08:00
parent 14c147722a
commit 264f214fe5
3 changed files with 27 additions and 9 deletions
@@ -9683,3 +9683,14 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 决策（行为变化）：兑换码的 `兑换码不存在` / `已停用` / `未生效` / `已过期` / `次数已用完` / `不适用于当前账号` / `奖励无效` 由原来的 502 变为 400 且带机器码；procedure result 新增字段属 wire 契约变更，要求 module 与 api-server 同版本部署。
 - 影响范围：`server-rs/crates/module-runtime/src/domain.rs`、`server-rs/crates/spacetime-module/src/runtime/active/profile.rs`、`server-rs/crates/spacetime-client/src/{active.rs,active/mapper/runtime_profile.rs}`、生成绑定、`server-rs/crates/api-server/src/runtime_profile.rs`、`docs/technical/【技术设计】泥点三池与会员计费后端设计-2026-10-02.md` §5.8、本文件。
 - 验证：`npm run spacetime:generate`；`cargo check -p api-server`；`cargo test -p api-server runtime_profile::tests` 41 passed；`cargo test -p module-runtime`、`cargo test -p spacetime-client`、`cargo test -p spacetime-module` 全通过；`npm run check:spacetime-schema`、`npm run check:encoding`、`git diff --check` 通过。
+
+## 2026-10-03 会员计费评审第 13–20 项收口：契约枚举化、生成类型、计费与结算防御
+
+- 背景：评审剩下一批 medium / low 的契约与防御性缺陷，用户逐项确认后一次性修复；每项单独提交，便于回溯。
+- 决策（契约枚举化，13/14/18）：`shared-contracts` 新增 `ProfileMembershipStatusToken`（`normal` / `active`），`AdminProfileMembershipPayload` 的 `plan` / `status` / `cycle_kind` 改用 token 枚举；5 个会员 token 枚举补 `ts_rs::TS` + `ts(export, ...)`，前端 `packages/shared/src/contracts/runtime.ts` 与 `apps/admin-web/src/api/adminApiTypes.ts` 改为生成类型别名 / re-export，禁止手写联合类型；`AdminAgcModel.access` 由裸 `String` 改为 `ProfileMembershipModelAccessToken`，未知值反序列化即拒。
+- 决策（计费防御，15/16）：`quote_runtime_profile_membership_upgrade` 显式拒绝价格 / 每期泥点 `<=`，堵住 0 元升级；`advance_beijing_months_clamped` 去掉 `expect`，超出 i64 微秒可表示范围（约 ±29 万年）时按方向饱和到 `i64::MAX` / `i64::MIN`，不改签名以免牵动 `membership_cycle_window` / `membership_expires_at`。
+- 决策（错误链 typed，17）：`resolve_llm_router_client` 返回 `Result<_, AppError>`，`load_owner_llm_catalog` 的 `503 + MODEL_ACCESS_UNAVAILABLE` 与 `resolve_requested_for` 的 `MODEL_UNAVAILABLE` 不再被拍平成中文，Chat Completions 与 `/api/llm/models`、代理端点错误码对齐。
+- 决策（去掉退役入参，19）：后台 upsert 请求 DTO 与 SpacetimeDB procedure 入参移除 `bonus_points` / `duration_days`，`profile_recharge_product_config` 退役列保留、写死 0；删除 `RuntimeProfileFieldError::InvalidRechargeProductFields`；后台表单去掉「首充赠送」，假数据同步。
+- 决策（结算归一，20）：`frozen_membership_cycle_matches` 比较双方都取 `max(1)`，修复 `cycle_index == 0` 迁移行被永久判成「会员状态已变化」的问题；不新增写库副作用。
+- 影响范围：`shared-contracts/{runtime,admin}.rs`、`module-runtime/{domain,commands,errors}.rs` 与 `module-runtime/src/{membership/upgrade,membership/cycle,agc_model_access}.rs`、`spacetime-client/{active,active/mapper/runtime_profile,module_bindings}`、`spacetime-module/src/runtime/active/profile.rs`、`api-server/src/{runtime_profile,llm/mod,agc_models}.rs`、`packages/shared/src/contracts/runtime.ts`、`apps/admin-web/src/api/adminApiTypes.ts`、`apps/admin-web/src/pages/AdminRechargeProductPage.tsx`、`scripts/admin-web-fake-api.mjs`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、本文件。
+- 验证：`cargo test -p api-server` 1206 passed；`-p module-runtime` / `-p spacetime-client` / `-p spacetime-module` 全通过；`npm run spacetime:generate`、`npm run check:spacetime-schema`（92 表）、`npm run check:generated-bindings`（117 文件）、`npm run admin-web:typecheck`、`npm run typecheck`、`npm run check:encoding`、`git diff --check` 通过。