5.1 KiB

Raw Blame History

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:

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

5.1 KiB Raw Blame History