# 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

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

## Done Definition

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