Dev integration

联调与文档

开发闭环的最后一步：让前后端在真实运行状态下咬合，然后把项目文档补齐到"新人 30 分钟能跑起来"的程度。

开工前对齐（必须）

动手前先向用户给出联调计划：要核对的接口清单、要走查的 P0 场景、要产出的文档列表。用户明确同意后才开始；用户想优先联调某个模块，按用户的顺序来。

商量必须自带默认推荐：计划本身就是你的推荐方案，直接说"建议按此执行，确认即开始"；有取舍时标注「推荐」项+一句理由，不许只抛开放式问题。

第一部分：联调

1. 环境就位

• 前后端同时启动（数据库 + 后端 + 前端），确认端口、代理/CORS 配置正确。
• 用种子数据的测试账号登录成功，作为联调起点。

2. 逐接口核对

以 docs/dev/03-api-contract.md 的接口清单为 checklist，逐条走：

• 前端页面触发真实请求 → 抓包（浏览器 Network 面板）比对请求参数和响应结构是否与契约一致。
• 发现不一致时的裁决规则：契约为准。契约本身不合理的，三方（契约/后端/前端）一起改，并在契约文档记一条变更记录。
• 每核对完一个接口，把契约中该接口状态更新为 🔗 已联调。

3. 端到端场景走查

按 01-requirements.md 的 P0 用户故事，从登录开始完整走每条核心路径，重点打这些容易漏的点：

• 边界输入：空值、超长文本、特殊字符、0/负数
• 权限：用无权限账号访问受限功能，确认拦截且提示得体
• 并发/重复：连点提交按钮、重复操作幂等性
• 刷新与回退：页面刷新后状态是否正确恢复
• 数据一致性：前端操作后，数据库里的数据形状是否符合预期（直接查库确认）

4. 缺陷修复

• 发现的问题记入清单（现象/根因/修复/验证方式），逐个修复并复测。
• 修一个验一个，不要批量修完再统一测——回归成本更高。

第二部分：文档

5. 联调报告

写入 docs/dev/04-integration-report.md：验收结论（P0 逐条 ✅/❌）、接口核对结果、缺陷清单及修复状态、遗留问题与建议。

6. 项目文档

• README.md：项目一句话简介、技术栈、目录结构、本地启动（从 clone 到能访问的完整命令序列，逐条实际执行验证过）、测试账号、常见问题。
• 部署文档（docs/dev/05-deployment.md）：生产环境要求、构建命令、环境变量清单（每个变量的含义和示例值）、启动/停止/回滚步骤、日志位置。
• CHANGELOG.md：本次交付的功能清单（对应需求编号）。
• 检查 .env.example 与实际用到的环境变量是否同步。

7. 最终验收

• 按 README 的启动步骤在干净状态下重跑一遍（新终端、清缓存），文档里写的每条命令都必须真实可执行。
• 向用户交付总结：完成了什么（对照需求 P0 清单）、已知问题、建议的下一步（P1 排期 / 上线准备）。

原则

• 联调阶段发现的每个问题都要归因：是契约歧义、后端 bug 还是前端 bug——归因错误会在下个项目重犯。
• 文档写"验证过的事实"，不写"应该是这样"；没跑通的步骤不许写进 README。
• 交付报告如实呈现：测试失败就写失败，跳过的场景就写跳过，不粉饰。