前端接口对接规范

把接口对接视为逐级开启的契约门禁（contract gate）：只实现已有证据支持的部分，让未知项保持可见、可替换且不会混入生产行为。请求契约永远不得推测；响应未知时先建立安全的可观察性，再等待真实结构。

1. 收集契约证据

先读取仓库指令、目标页面、相邻实现、请求客户端、环境配置、现有 Mock，以及项目中的 OpenAPI/Swagger、生成客户端、共享类型、后端实现和明确文档。识别项目指定的单一事实来源；未指定时，记录每项结论所依据的最近、最权威证据。

证据能够回答的事实自行查明。证据缺失或互相冲突时暂停对应部分，向用户列出冲突来源和需要确认的具体问题，不自行选择看似合理的版本。

真实请求的契约门禁要求逐项确认：

• endpoint 路径和 HTTP method；
• path、query、body 参数的位置、名称、类型、必填性和序列化方式；
• 鉴权方式、必要 headers、Content-Type 和项目使用的 API client；
• 是否上传文件。

文件上传还要确认文件字段名、单文件或多文件、其他表单字段，以及已声明的类型、大小等限制。让请求库管理 multipart boundary，除非项目契约明确要求其他行为。

另行记录响应证据：成功响应的外层结构和业务数据位置，以及已明确的错误结构、分页字段、空值语义和状态码行为。响应证据的完整度决定后续能推进到哪一条分支，但不改变请求契约门禁。

完成标准：每个已确认请求项都能指向具体证据；请求缺口、响应缺口和证据冲突分别列明。

2. 按门禁状态推进

严格根据当前证据选择允许的动作：

• 没有 endpoint 路径：不创建真实请求函数，不推测路径；需要演示页面时，只建立隔离的 Mock。
• 路径或请求结构不完整：不发起真实请求；保留已确认信息并报告缺口。
• 请求契约完整、整个响应未知：可以完成请求调用、加载态和项目既有通用错误处理；只记录安全的开发环境日志，不读取任何业务字段。
• 成功响应已知、附属契约未知：只映射已确认的成功字段；错误、分页或空值语义沿用项目既有通用处理，并明确报告未知部分。
• 响应仅有个别页面字段无法映射：映射已确认字段，对缺失字段使用显式 UI 占位和 TODO。

不要用常见的 code/message/data、page/total 等结构填补未知契约，也不要自行增加重试、轮询、缓存失效、权限或状态流转规则。

完成标准：实现内容没有越过当前门禁；每个未实现部分都有明确阻塞原因，而不是隐藏的猜测。

3. 隔离 Mock

没有接口路径或需要独立演示时，优先复用项目已有的 fixture、Mock server、MSW 或测试替身。让 Mock 描述页面所需场景，但明确标注“非真实接口契约”，不要把页面形状伪装成后端响应结构。

通过项目已有的开发或测试开关启用 Mock，并验证生产构建无法启用或引用它。不要把临时数据直接埋入页面组件；如果项目没有 Mock 设施，提供最小、可替换且与生产入口分离的实现。

完成标准：Mock 可被真实实现整体替换，不包含推测 endpoint，并且没有进入生产请求路径。

4. 映射响应数据

复用项目已有的 API、model、hook、composable 或 adapter 边界；没有既有抽象时保持最薄映射，不为本规范强制引入新架构层。

对已确认响应执行尽量直接的 1:1 映射，保留字段类型、空值、枚举、时间和单位语义。只有现有页面模型或命名约定要求时才重命名，并让来源字段与目标字段的关系可追踪。不得猜测语义相近的响应字段，也不得伪造响应对象中的字段。

页面字段找不到已确认映射时：

1. 使用明显的展示占位或页面已有静态默认值；
2. 在代码中添加 TODO(api-integration): <页面字段> 缺少已确认响应映射；需要 <待确认信息>，确认后删除此占位。；
3. 在聊天交付中逐项列出页面字段、占位值、所需契约和 TODO 位置。

占位值不得进入提交载荷或回写后台。根据已确认字段，只允许增加可逆、可解释的安全展示派生，例如格式化、显隐和禁用态；权限、金额、状态迁移、提交行为、持久化以及其他业务决策必须有明确契约。每项安全派生都要在交付中说明其输入与页面影响。

完成标准：每个展示字段都能追溯到已确认响应、明确的安全派生或显式占位；请求载荷不含占位值或展示派生值。

5. 安全观察未知响应

响应结构未知时，只在开发环境使用项目日志设施记录；没有统一设施时使用受开发环境保护的控制台日志。优先遮蔽 Authorization、token、Cookie、密码、证件信息和常见个人信息。无法可靠识别敏感值时，只输出状态码、顶层键名和数据类型，不输出字段值。

临时日志必须带有用途说明，并在响应结构确认、映射完成后删除。生产构建中不得保留未知响应的原始输出。

完成标准：未知响应可被安全观察，生产环境不会输出原始数据，并且临时日志有明确删除条件。

6. 验证并汇报

运行目标项目已有的格式化、静态检查、测试和构建检查。按已确认契约验证请求 method、URL、参数位置、上传字段和序列化；验证响应映射、占位值隔离、Mock 生产隔离，以及临时日志的环境保护。只断言已有证据支持的行为。

交付时明确汇报：

• 契约证据及已确认的请求项；
• 未确认或冲突的契约；
• Mock 的启用范围和生产隔离状态；
• 临时响应日志及其删除条件；
• 所有占位字段、占位值和 TODO(api-integration)；
• 新增安全派生逻辑的输入与页面影响；
• 已运行的检查、结果，以及未运行检查的原因。

以上各项全部可追踪，且没有未披露的请求或响应推测时，对接工作才算完成。