lxq/changes/n04-onboard/.superpowers/sdd/task-briefs/T8.md

T8 任务简报：OpenAPI、接口文档与前端联调

Where This Fits

• Wave: W3
• Depends on: T7
• Contract: changes/n04-onboard/execution-contract.md

Objective

发布 onboarding 的静态 OpenAPI、接口说明、前端联调说明和路线图状态，先用契约校验暴露文档缺口，再补齐文档。

Files In Scope

• docs/openapi-rc.json
• docs/onboarding-api.md
• docs/frontend-integration.md
• docs/backend-development-roadmap.md
• README.md

Required Behavior

• OpenAPI 包含 9 个 /onboarding 路径和全部请求/响应 schema，operationId 全局唯一。
• 文档说明角色、企业所有权、通用/企业项合并、完成状态版本、幂等键、软删除、知识回退、评价小样本阈值和 9701-9706。
• 前端联调文档给出 Base URL、鉴权头、请求示例、响应示例、409/404/401/403 处理。
• README 和 roadmap 将入职清单与公司知识介绍状态从“未开始”更新为“实现完成/待验收”。
• 文档字段名、默认值、错误码与运行时 DTO 完全一致。

TDD Requirement

1. 先运行 python docs\verify_openapi.py，记录缺失路径或 schema 的失败证据。
2. 再更新 OpenAPI 和文档，直到校验通过。
3. 文档校验失败不得通过删除既有路径或放宽校验绕过。

Evidence Commands

cd D:\1\zhi\zhilai
python .\docs\verify_openapi.py
cd .\mydreamjob-server
mvn clean verify

Done Definition

• OpenAPI 校验通过，9 个新路径可被 Apifox/前端消费。
• 文档与 runtime 注解一致，无未说明错误。
• 全量测试和打包通过。