结论先行

这份 v1 不能作为独立开发者从零交付的“对接全集”。它更像是“业务域索引 + 若干关键约定”，但还缺少能让外部开发者稳定完成开发、联调、验收和上线的四类核心契约：

  1. 可执行 API 契约不完整：缺少完整请求/响应 schema、枚举、错误体、鉴权矩阵、分页与时间规范。
  2. 运行时契约缺失：缺少 token 生命周期、刷新、限流、超时、重试、幂等、上传限制、回调和轮询策略。
  3. 跨端与安全边界不清：三端、BFF、FastAPI、微信、图片域名之间的 CORS、域名、Cookie、CSRF、角色和数据隔离均未闭合。
  4. 业务闭环存在明显缺口：退款、支付异常、库存/排期、消息触达、商户入驻、财务结算、风控审计等未形成可直接接线的端点和状态契约。

① 外部开发者从零对接还缺什么

P0：不补齐就无法可靠开发或验收

1. 完整 OpenAPI/JSON Schema 不可替代

材料只说有 api-v1.2.md、api-v1.3-matrix.md，但正文没有逐端点的：

依据：材料只给了“端点组”和少量示例，例如订单创建请求，但没有覆盖 355+ 端点的可执行 schema。“契约 v1.2 详细 schema 为准”把关键资料外置，不能满足本包作为独立交付包的目标。

要求：v2 至少提供可导入的 openapi.json/yaml，并保证与线上路由、返回体、状态码一致。

2. 鉴权生命周期、刷新和登出协议缺失

已写 Bearer <token>，但没有说明：

依据：认证章节只有登录端点和 Authorization 头，没有生命周期与刷新规则；三端认证主体明显不同，但没有 token audience、scope 或角色隔离定义。

风险：独立开发者无法正确实现登录态、自动续期、401 重试和多账号切换。

3. 鉴权角色矩阵和资源隔离缺失

需要明确每个端点的：

依据：材料出现“本商户 scope”“RBAC”“system 角色”，但没有端点级角色矩阵，也没有对象级数据隔离规则。

4. 错误响应没有统一形状

材料同时规定：

但没有给出失败响应示例，例如：

{
  "code": "ORDER_STATUS_INVALID",
  "message": "订单当前不可取消",
  "details": {},
  "request_id": "..."
}

也没有说明：

依据：当前只列了 HTTP 状态码，没有错误 body 契约；“业务失败已抛错”不是前端可执行规范。

5. 枚举和状态机不完整，且存在互相冲突

材料给出部分状态，但没有形成机器可读枚举和迁移矩阵。

明显问题包括：

依据：材料明确标注 WIP-302、WIP-286、WIP-290，说明部分状态和端点仍在变更；同时正文存在订单状态描述不一致。

要求：给出每个枚举的值、含义、展示文案、允许迁移、触发方、是否终态。

6. 时间、时区和日期格式缺失

订单字段包含 booked_at、confirmed_at、startDate，但没有说明：

依据：材料只定义了金额单位，没有定义时间格式和时区；而订单、支付、账期、48 小时结算都依赖时间计算。

7. 幂等、并发、重试和超时规则不完整

只明确了订单“60s 幂等判重”和支付回调“验签+幂等”，但没有说明：

依据：订单和微信回调是高风险写操作，但仅给出局部幂等说明，未形成全局写接口策略。

8. 限流、并发和配额没有定义

材料未涉及：

依据：材料完全没有限流和容量契约；355+ 端点由独立开发者接入，必须知道失败和重试边界。

9. CORS、域名和三端平台网络配置缺失

这属于明显缺项。

需要明确：

依据：生产 API、staging 内网地址、图片独立域名均已列出，但没有网络访问和跨域配置说明。小程序不能直接使用任意内网地址，浏览器也不能默认跨域调用。

10. 文件上传协议不完整

只写了：

POST /api/miniapp/upload

但没有定义：

依据：材料明确说服务器硬盘存储、弃 COS，但没有容量、备份、删除和访问策略；这是生产稳定性与安全风险。

P1：不补齐会造成大量返工

11. 分页规范不完整

虽定义了 page/page_size，但缺少：

依据：只有分页响应示例，没有边界、排序和筛选协议。

12. 搜索、筛选、排序字段没有列出

商品、订单、商户、账单、分销结算等页面都需要筛选，但材料没有为各端点定义：

13. API 版本、兼容性和变更机制缺失

材料同时有 api-v1.2、api-v1.3、WIP 修复项，但没有说明：

依据：当前契约版本与实际修复状态并存，存在“文档正确但线上不同”的风险。

14. Webhook、轮询和异步任务策略缺失

支付回调有 /pay/notify，但没有说明：

依据：材料给了支付状态查询，但没有定义其调用策略；状态机中大量状态显然可能异步变化。

15. 安全规范缺失

未说明：

依据：用户、手机号、支付、商户财务数据均在业务范围内，但材料没有安全基线。

16. 本地化、展示和文案规则缺失

虽然文案走 site-texts，但没有定义：

② 架构三原则的漏洞

原则一：FastAPI 唯一真源——方向正确，但边界不够严

漏洞 1：BFF 的“渲染增强”边界模糊

材料说 NestJS 可以做 BFF/SSR/渲染增强，但没有定义哪些逻辑允许放在 BFF：

风险：虽然禁止“重写业务逻辑”，但实际项目很容易把价格、库存、订单状态、佣金等业务判断复制到 NestJS，形成隐形双源。

应补充：BFF 允许/禁止清单。BFF 可以做协议转换、聚合、缓存、展示裁剪；不得计算价格、库存、佣金、支付结果、状态迁移、权限结论。

漏洞 2：没有定义 BFF 的 API 版本和契约责任

如果 NestJS 包装 FastAPI，前端到底依赖：

风险：出现第三套响应包装、字段别名和错误码，最终“唯一真源”只剩数据库意义，API 契约反而多源。

漏洞 3：没有防止 BFF 缓存造成数据陈旧

订单、支付、核销、库存、佣金均为强时效数据。若 NestJS 做 SSR 或缓存，必须定义：

依据：材料允许“渲染增强”，但没有缓存边界。

漏洞 4：未定义事务和跨接口编排边界

例如下单可能涉及：

  1. 预检；
  2. 锁价；
  3. 创建订单；
  4. 支付；
  5. 分销归因；
  6. 福钥抵扣。

如果 BFF 串联这些调用，失败时没有补偿策略。BFF 不应自行补偿业务事务，必须由 FastAPI 提供原子接口或明确 saga/补偿协议。

原则二：鉴权透传——不足以保证安全

仅透传 Authorization 不能解决：

结论：应从“透传 Authorization”升级为“身份与权限链路契约”，包括 token audience、scope、内部信任边界、header 白名单、日志脱敏和服务间认证。

原则三：文案与配置走 site-texts——仍存在配置漂移风险

漏洞 1：哪些内容算配置没有定义

除了页面文案，还可能包括：

材料只明确“新页面文案走 site-texts”，没有定义业务配置是否也必须由后端返回。

漏洞 2：site-texts 本身的缓存、发布和版本机制缺失

没有说明：

漏洞 3：不能把业务规则伪装成文案配置

例如“支付超时时间”“佣金比例”“抵扣比例”不能仅以文本或任意 JSON 下发后由前端解释。业务规则必须由 FastAPI 计算并返回结果，前端只展示。

③ 双响应包装的坑，以及最干净的处理方式

判断：双包装对新页面开发是坑，而且不应让三端各自兼容

当前约定：

{ "code": 0, "data": ... }

和：

{ "ok": true, "data": ... }

这会带来四类问题：

  1. 成功判断歧义：code=0、ok=true、HTTP 2xx 三套标准。
  2. 失败判断不一致：某些接口可能 HTTP 200 但业务失败，某些接口用 4xx。
  3. 类型推导复杂：统一客户端必须处理联合类型，业务代码容易绕过 util 直接读取。
  4. BFF 可能再包一层：最终出现 {ok:true,data:{code:0,data:...}}。

依据：材料明确要求客户端“统一处理”，但没有规定统一后的内部类型和失败处理方式；“业务失败已抛错”也没有给出异常模型。

最干净的方案

方案 A：FastAPI 在兼容期统一输出，推荐

新页面只面向一套规范：

{
  "success": true,
  "data": {},
  "request_id": "req_xxx"
}

失败统一为：

{
  "success": false,
  "error": {
    "code": "ORDER_STATUS_INVALID",
    "message": "订单当前状态不可取消",
    "details": {}
  },
  "request_id": "req_xxx"
}

HTTP 状态码表达大类，业务错误码表达具体原因。

历史接口在 FastAPI 网关或兼容层转换，不把兼容逻辑暴露给业务页面。

方案 B：短期由 NestJS SDK 统一，不能散落在页面

如果暂时不能改 FastAPI：

不建议让 c/b/a 三端各自实现一份解包逻辑。

④ 三端业务域是否漏掉

明显缺失或描述不足的业务域

1. 退款/售后域：明显缺失

订单状态有：

refunding → refunded

但没有完整退款端点组：

结论：退款状态存在，但退款业务域没有形成可对接契约。

2. 支付域不完整

已有支付下单、微信回调、支付状态查询，但缺少：

依据：材料仅覆盖 prepay_id、notify、status，且明确线上订单状态仍有 WIP-302。

3. 库存、排期、可售性域缺失

预检返回 conflicts/pass，但没有说明：

结论：预检和下单存在，但库存/排期闭环未暴露。

4. 商户入驻和资料管理不完整

有民宿申请、商户审核，但缺少：

依据：merchant-console/merchants 当前部分 404，且商户认证只写“staff token 登录流”。

5. 退款、财务、结算闭环不完整

有商户 bills、分销结算单批量打款，但未说明：

6. 消息域描述过于笼统

/messages 只有“3-10 端点”，未明确：

7. 核销域缺少完整码生命周期

已有 scan、confirm、revoke、batch，但未说明：

8. 用户、账户和隐私域缺失

c 端需要：

材料只列了 user 数据字段，没有用户端业务端点。

9. 审计、操作日志和风控域未形成接口

材料提到“审计留痕”，但没有：

10. 搜索、推荐、首页聚合域未说明

新页面通常需要首页、分类、搜索、推荐和运营位，但材料只有商品列表、site-texts、CMS，没有明确：

材料未涉及：是否已有这些接口不能据此断言不存在，但当前信息包没有提供。

⑤ 信息包 v2 必须补充清单，按优先级

P0：上线前必须补

A. 一份可执行、可校验的 API 契约

B. 统一错误契约

定义：

{
  "success": false,
  "error": {
    "code": "ORDER_STATUS_INVALID",
    "message": "订单当前状态不可取消",
    "details": {}
  },
  "request_id": "req_xxx"
}

同时明确：

C. 鉴权和角色矩阵

必须提供表格：

端点/域游客C 用户商户员工商户管理员运营财务超管数据范围
订单详情否/本人本人本商户本商户全部只读/账务全部order_id 归属
退款审核否否/申请可选是是否是商户或全局

并补充：

D. 网络与环境接入说明

必须写清：

E. 完整枚举和状态迁移矩阵

至少覆盖：

每个状态需包含：

同时立即解决 confirmed 与 pending_payment 的线上不一致。

F. 时间、金额和数据类型规范

G. 写接口可靠性规范

为所有写接口补充：

H. 支付和退款闭环

必须补：

I. 文件上传契约

P1：开发阶段必须补

J. 分页、筛选、排序协议

K. 异步状态和轮询协议

L. BFF 边界和契约

明确：

允许：

禁止：

M. site-texts 和配置治理

N. 测试和验收资产

当前提到 curl、L3、golden path，但还应提供：

P2：上线运营必须补

O. 可观测性和故障排查

P. 限流与容量

Q. 安全和合规

R. 未完成项清零表

当前至少要将以下 WIP 明确成“已修复版本 + 线上证据 + 回滚方案”：

在 WIP 未关闭前，不能宣称“全部业务能力就绪”。

最终评审结论