Merge branch 'feat/pricing-plan-fix' into feat/pricing-plan

docs/project-memory/shared-memory/team-conventions.md

@@ -57,6 +57,7 @@
 - 对已明确退役且无现役调用方、公开契约、持久化数据、活跃实例或迁移要求的对象，直接清理实现、专属测试和说明，将权威文档更新为当前状态；历史由 Git 保存。公开契约、持久化数据和正式迁移按实际需求保留最小兼容及对应测试。
 - 修改 `/api/external/v1` 时，同批更新 `docs/openapi/genarrative-external-v1.openapi.json` 与契约测试。
 - 修改 SpacetimeDB schema 时遵守字段追加/default 约束，同步 migration、表目录、生成绑定，并运行 schema 检查；删除、改名、重排或改类型前先确认迁移计划。
+- `shared-contracts` 响应 DTO 只增不删：新增字段一律可选（`Option`，或带安全 `#[serde(default ...)]`），身份 / 状态字段保持必填；删除、改名、改类型或改必填属性前先确认版本化计划，不保留仅服务旧客户端的 legacy shim。详见后端架构文档「shared-contracts DTO 变更规则」。
 - 日志不递归输出完整配置、应用状态或 provider client；新增字段默认不进入安全摘要。所有 provider 配置类型（`LlmConfig`、`OssConfig`、`WechatConfig`、`WechatPayConfig`、`MattingConfig`、`VolcengineSpeechConfig`、`Hyper3dSettings`、`VectorEngineImageSettings`、`VectorEngineAudioSettings`）都必须手写脱敏 `Debug`：只输出枚举、数值、布尔、有界标识与 `<redacted>` 占位，凭据、私钥、路径与 URL 一律不递归格式化，并各带一条哨兵值回归用例（`cargo test -p platform-* debug`）。新增同类配置必须照此办理，不允许直接 `derive(Debug)`。
 - HTTP 横切能力集中在 Axum/Tower 中间件：正常与降级路由复用追踪层；指标与 trace 使用 `MatchedPath` 模板及固定兜底，不把请求 ID、实际资源 ID 或 query 放入指标标签。在途请求通过 RAII guard 覆盖 Future 取消与 panic unwind；请求执行和响应体存活分别计量，不能把 handler 耗时当作 SSE 全生命周期。
 - 业务依赖在组合根显式装配，Axum `FromRef` 只抽取可浅拷贝的窄能力。项目元数据与 External API 鉴权不持有完整 `AppState`，测试经相同接口注入替代依赖。集中鉴权仍保留方法级 fallback、公开入口、MCP 和 body limit 顺序；Provider span 跳过完整参数，不隐藏计费、重试、幂等或事务规则。

docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md

@@ -151,6 +151,14 @@ npm run check:server-rs-ddd
 
 本地联调和人工排障不要使用 `spacetime --root-dir`。本地数据隔离使用项目脚本或 `--data-dir`；发布目标显式传 `--server` / `--server-url`。
 
+## shared-contracts DTO 变更规则
+
+1. 面向前端 / AGC 壳的**响应** DTO 只增不删：新增字段一律可选——`Option<T>`，或非 `Option` 时带 `#[serde(default ...)]` 且默认值安全（空集合 / `0` / `false` / 最小合法值）。这样「客户端先于服务端发布」的滚动升级不会因为旧服务端缺字段而整包解析失败；这是兼容未来版本的手段，不是给当前旧客户端保留 legacy shim。
+2. 身份与状态类字段（例如 `ProfileMembershipResponse.plan` / `status`、`enabled`）保持必填，不给默认值：fail-open 会把付费会员误显示成非会员或反过来，静默错误比整包失败更难排查。
+3. 未知 token 值继续走 `deserialize_forward_compat_*` 兜底；它与「缺字段默认值」是两条独立路径，都要有契约测试（旧服务端缺字段、新服务端多发未知取值各一条）。
+4. 删除字段、改名、改类型或改必填属性属于破坏性变更，必须先确认版本化 / 迁移计划并更新权威文档；除非明确要求新旧客户端混跑，否则不为旧客户端保留 legacy shim。
+5. 响应 DTO 的 serde 属性不影响 ts-rs 绑定；字段集合或类型变化必须重新生成绑定并运行 `npm run check:generated-bindings`。
+
 ## 账户充值数据契约
 
 1. `profile_recharge_product_config` 是泥点和会员商品配置真相源，默认商品只在表为空时由 SpacetimeDB 播种。`module-runtime` 中的默认商品 helper 只作为空库种子和兼容入口，不再作为运行期业务真相。