# W3-T8 Review: OpenAPI、接口文档与前端联调

- Wave: W3
- Task: T8
- Base SHA: `73afd87`
- Head SHA: `aad0ba6`
- Review report: `.superpowers/sdd/reviews/W3-T8.md`
- Verdict: **FAIL**

## Strengths

- T8 的交付范围正确：diff 仅涉及 OpenAPI、文档、验证脚本和 SDD 状态文件，没有修改 Java 生产代码或测试代码。
- 与 `73afd87` 相比，OpenAPI 精确新增 6 个 `/onboarding` 路径、9 个 operation、20 个 schema；原有 129 个路径和 139 个 schema 的结构化内容均未变化。
- 9 个 operation 的 `operationId` 唯一，全部声明 `bearerAuth`；成功响应引用正确；9701-9706 均出现在对应错误响应中。
- `docs/onboarding-api.md` 覆盖角色、企业所有权、通用/企业清单合并、完成状态与版本、幂等创建、软删除、知识回退、3 条评价阈值、错误码和请求/响应示例。
- `docs/frontend-integration.md` 第 22 节覆盖 Base URL、鉴权、9 个接口、请求示例、状态回退及 400/401/403/404/409 处理。
- README 和 roadmap 已更新为 N04“实现完成，待真实 MySQL/Docker 验收”，并准确记录当前全量测试失败情况。
- `docs/verify_openapi.py` 是增强而非削弱：删除了旧的固定路径总数断言，改为更强的 135 paths / 172 operations 断言，并新增 N04 路径、operation、security、schema 和错误码检查。
- N04 专项回归通过：`Tests run: 96, Failures: 0, Errors: 0, Skipped: 0`，`BUILD SUCCESS`。

## Blocking Findings

### Important: OpenAPI 示例与运行时响应不一致

- File: `docs/openapi-rc.json:7430-7439`
- `PUT /onboarding/company/knowledge` 的 200 示例 `data` 缺少 `version`。
- Runtime `CompanyKnowledgeView`、OpenAPI schema 以及 `docs/onboarding-api.md` 都明确包含 `version`；企业客户端必须使用该字段进行下一次乐观锁更新。
- 因此该示例会误导前端在对更新响应建模或联调时遗漏版本，直接违反 T8“字段、默认值与运行时 DTO 完全一致”的要求。
- Fix: 在 200 示例中补充一个与更新语义一致的 `version`，并在 `docs/verify_openapi.py` 中增加示例字段断言。

### Important: 创建请求的 OpenAPI schema 未表达运行时默认值

- File: `docs/openapi-rc.json:11714-11722`
- `CompanyChecklistItemCreateRequest.sortOrder` 缺少 `default: 1000`。
- `CompanyChecklistItemCreateRequest.required` 缺少 `default: false`。
- Runtime DTO 明确初始化了这两个默认值，文档正文也说明默认值，但静态 OpenAPI schema 没有表达，违反 T8 对默认值一致性的要求。
- Fix: 在对应 schema 属性中加入 `default`，并在 `docs/verify_openapi.py` 中断言这些默认值。

## Minor Findings

- `docs/verify_openapi.py` 对 9704 的检查只验证响应描述或示例的序列化文本中存在该错误码；当前 9704 只出现在描述中。建议按 operation/status 精确断言错误码和示例结构，同时覆盖 `version` 默认值和响应示例，避免回归。
- OpenAPI 200 响应当前沿用仓库既有的 `*/*` content type，而不是更明确的 `application/json`。这不影响本次 T8 通过判定，但会给前端代码生成带来额外歧义。
- `changes/n04-onboard/.superpowers/sdd/progress.md` 尚未记录 T8 独立 review 结果，符合当前“review pending”状态，等待 receipt 后再更新。

## Non-Blocking Verification

- `python .\docs\verify_openapi.py`：
  - `paths: 135`
  - `N04 onboarding endpoints and schemas present (9 operations / 6 paths)`
  - `All checks passed!`
- 结构化对比 `73afd87..aad0ba6`：
  - added paths: 6
  - added operations: 9
  - added schemas: 20
  - existing paths changed: 0
  - existing schemas changed: 0
- N04 regression:
  - `mvn -Dtest=Onboarding*Test,CompanyKnowledge*Test test`
  - `Tests run: 96, Failures: 0, Errors: 0, Skipped: 0`
  - `BUILD SUCCESS`
- Reported full-suite failure set reproduced independently:
  - `mvn -Dtest=CareerProgressServiceTest,JobReviewDimensionControllerTest,JobReviewDimensionServiceTest,LocalResumeStorageServiceTest test`
  - `Tests run: 69, Failures: 2, Errors: 9`
  - failures are the reported CareerProgress/JobReviewDimension assertions and LocalResumeStorage temp-directory cleanup errors.
- `git diff --check 73afd87..aad0ba6` passed.
- `git diff --name-status 73afd87..aad0ba6` contains no Java production or test changes, so the reported failures are unrelated to the T8 commit. The N04 branch's only changes touching those packages are additive `JobReview` repository query methods that are not used by the failing paths; CareerProgress and LocalResumeStorage code is unchanged.

## Assessment

**Ready to merge?** No

**Reasoning:** The OpenAPI structure, documentation coverage, security declarations, error-code coverage, and N04 regression are strong, but the static contract is not yet fully runtime-consistent. The missing knowledge-response `version` example and missing create-request defaults are actionable contract defects that must be fixed and re-reviewed before T8 can pass.

Receipt command:

```bash
ssf execution review changes/n04-onboard --wave W3-T8 --base 73afd87 --head aad0ba6 --report .superpowers/sdd/reviews/W3-T8.md --verdict fail
```