pwklppg
1 month ago
7 changed files with 319 additions and 4 deletions
@ -0,0 +1,83 @@ |
|||
# W3-T8 Re-review: OpenAPI 示例与默认值修复 |
|||
|
|||
- Wave: W3 |
|||
- Task: T8 |
|||
- Review round: repair round 1 |
|||
- Base SHA: `aad0ba6` |
|||
- Head SHA: `310d931` |
|||
- Prior failed report: `W3-T8.md` |
|||
- Repair brief: `T8-repair-1.md` |
|||
- Verdict: **PASS** |
|||
|
|||
## Original Findings |
|||
|
|||
### Resolved: knowledge Upsert response example omitted `version` |
|||
|
|||
`docs/openapi-rc.json:7439` now includes `data.version: 2` in the `PUT /onboarding/company/knowledge` 200 example. The request example uses `version: 1`, so the returned `version: 2` is consistent with update semantics. `CompanyKnowledgeView` still exposes `version`, and the schema remains unchanged. |
|||
|
|||
### Resolved: create-item schema omitted runtime defaults |
|||
|
|||
`docs/openapi-rc.json:11718` now declares `sortOrder.default = 1000`. |
|||
`docs/openapi-rc.json:11724` now declares `required.default = false`. |
|||
These match the initialized runtime fields in `CompanyChecklistItemCreateRequest`. |
|||
|
|||
### Resolved: verifier did not assert the repaired contract |
|||
|
|||
`docs/verify_openapi.py:300-309` now asserts: |
|||
|
|||
- `CompanyChecklistItemCreateRequest.sortOrder.default == 1000` |
|||
- `CompanyChecklistItemCreateRequest.required.default is False` |
|||
- knowledge Upsert 200 example `data.version == 2` |
|||
|
|||
The verifier diff adds 12 lines and removes none. Existing path, operation, schema, security, response-reference, field, and error-code checks remain intact, so the prior checks were not weakened. |
|||
|
|||
## Scope Verification |
|||
|
|||
The scoped semantic OpenAPI diff contains exactly the three intended changes: |
|||
|
|||
- `CompanyChecklistItemCreateRequest.required.default`: added `false` |
|||
- `CompanyChecklistItemCreateRequest.sortOrder.default`: added `1000` |
|||
- knowledge Upsert 200 example `data.version`: added `2` |
|||
|
|||
No runtime Java, test, migration, endpoint, schema, security, or unrelated documentation changes are present in `aad0ba6..310d931`. |
|||
|
|||
## Evidence |
|||
|
|||
```text |
|||
python .\docs\verify_openapi.py |
|||
paths: 135 |
|||
N04 onboarding endpoints and schemas present (9 operations / 6 paths) |
|||
No empty ref keys found |
|||
Valid JSON: True |
|||
All checks passed! |
|||
``` |
|||
|
|||
```text |
|||
mvn -Dtest=Onboarding*Test,CompanyKnowledge*Test test |
|||
Tests run: 96, Failures: 0, Errors: 0, Skipped: 0 |
|||
BUILD SUCCESS |
|||
``` |
|||
|
|||
`git diff --check aad0ba6..310d931` passed. |
|||
|
|||
## Remaining Findings |
|||
|
|||
No blocking findings. |
|||
|
|||
Non-blocking carried-forward findings from the prior review remain outside this focused repair: |
|||
|
|||
- Error-code verification remains partly text-based rather than asserting exact operation/status/example structure. |
|||
- Success responses continue to use the repository's existing `*/*` media type instead of explicit `application/json`. |
|||
- Full `mvn clean verify` and real MySQL 8.4 / Docker acceptance remain pending; the previously identified full-suite failures are unrelated to N04/T8. |
|||
|
|||
## Assessment |
|||
|
|||
**Ready for T8 receipt:** Yes |
|||
|
|||
The two original Important findings are resolved, and both are now protected by exact verifier assertions without weakening earlier checks. |
|||
|
|||
Receipt command: |
|||
|
|||
```bash |
|||
ssf execution review changes/n04-onboard --wave W3-T8 --base aad0ba6 --head 310d931 --report .superpowers/sdd/reviews/W3-T8-rereview.md --verdict pass |
|||
``` |
|||
@ -0,0 +1,78 @@ |
|||
# 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 |
|||
``` |
|||
@ -0,0 +1,113 @@ |
|||
# W3 Wave Review: n04-onboard |
|||
|
|||
- Wave: `W3` |
|||
- Base SHA: `a5730a7` |
|||
- Head SHA: `310d931` |
|||
- Verdict: **PASS (conditional)** |
|||
- Blocking findings inside W3: **None** |
|||
- Release status: **blocked by external verification gates** |
|||
|
|||
## Scope Reviewed |
|||
|
|||
Read the execution contract, onboarding-checklist and company-knowledge specs, design, W3 task reports (`W3-T6.md`, `W3-T6-rereview.md`, `W3-T7.md`, `W3-T8.md`, `W3-T8-rereview.md`), task briefs where needed, the combined diff `a5730a7..310d931`, and the relevant production, integration-test, OpenAPI, and documentation artifacts. |
|||
|
|||
The combined diff contains 31 files, `+7123/-1903`. W3 production changes are limited to: |
|||
|
|||
- `SecurityConfig.java` |
|||
- `OnboardingChecklistItemRepository.java` |
|||
- `OnboardingChecklistService.java` |
|||
- `CompanyKnowledgeService.java` |
|||
|
|||
The remainder is onboarding integration/privacy/end-to-end testing, OpenAPI/docs, and SDD workflow artifacts. No V1-V38 migration is modified in W3. No existing API path, request/response shape, or error semantics are intentionally changed. |
|||
|
|||
## Cross-Task Integration |
|||
|
|||
### Permissions and ownership |
|||
|
|||
- `/onboarding/**` is explicitly authenticated; anonymous requests return 401 through the existing security entry point. |
|||
- STUDENT and COMPANY role checks are enforced in service code, not merely by the HTTP matcher. |
|||
- Company operations resolve the company from `owner_user_id` and reject cross-company checklist mutation with `9701`/404 without modifying the target row. |
|||
- Privacy assertions cover success and error responses and verify absence of internal IDs, hashes, moderation fields, tokens, IP/User-Agent, phone, and email fields. |
|||
|
|||
### Concurrency and isolation |
|||
|
|||
- Company checklist creation runs at `READ_COMMITTED`, acquires a `PESSIMISTIC_WRITE` company-row lock, and uses a locking read for company item lookup before idempotency and active-count decisions. |
|||
- The 49-to-50 boundary is deterministic under H2 `MODE=MySQL` with the connection default forced to `REPEATABLE_READ`; the test observes exactly one success and one `9703`, with 50 active rows. |
|||
- Progress updates serialize per student user through a pessimistic user lock; concurrent first creation produces one progress row. |
|||
- Knowledge upserts serialize on the owning company row and map optimistic/duplicate-key conflicts to `9706`. |
|||
- The focused concurrency suite passes. Real MySQL 8.4 lock/deadlock behavior remains an external acceptance gate. |
|||
|
|||
### End-to-end contract |
|||
|
|||
- T7 exercises all 9 onboarding operations through the real Spring context, JWT/security chain, MockMvc, H2 persistence, and DTO serialization. |
|||
- Coverage includes standard/company checklist merge and fallback, completion and cancellation, stale versions, idempotent replay and hash conflict, 50-item limit, soft delete/repeat delete, cross-company isolation, `BASIC_ONLY`/`CONFIGURED`, `EMPTY`/`INSUFFICIENT`/`SUFFICIENT`, public-review filtering, tag limits, permission failures, and privacy assertions. |
|||
- T8 OpenAPI contains exactly 6 onboarding paths and 9 operations, all with bearer security and the expected response/error references. The repaired examples/defaults match runtime behavior. |
|||
|
|||
## Verification Evidence |
|||
|
|||
### Required focused regression |
|||
|
|||
```powershell |
|||
cd D:\1\zhi\zhilai\mydreamjob-server |
|||
$env:JAVA_HOME='D:\java'; $env:Path='D:\java\bin;'+$env:Path |
|||
& 'D:\maven\apache-maven-3.9.7\bin\mvn.cmd' '-Dtest=Onboarding*Test,CompanyKnowledge*Test' test |
|||
``` |
|||
|
|||
Result: `Tests run: 96, Failures: 0, Errors: 0, Skipped: 0`, `BUILD SUCCESS`. |
|||
|
|||
### Production-isolation concurrency check |
|||
|
|||
```powershell |
|||
& 'D:\maven\apache-maven-3.9.7\bin\mvn.cmd' '-Dtest=OnboardingConcurrencyIntegrationTest$RepeatableReadLimitBoundary' '-Dspring.datasource.hikari.transaction-isolation=TRANSACTION_REPEATABLE_READ' test |
|||
``` |
|||
|
|||
Result: `Tests run: 1, Failures: 0, Errors: 0, Skipped: 0`, `BUILD SUCCESS`. |
|||
|
|||
### Randomized end-to-end ordering |
|||
|
|||
```powershell |
|||
& 'D:\maven\apache-maven-3.9.7\bin\mvn.cmd' '-Dtest=OnboardingEndToEndIntegrationTest' '-Djunit.jupiter.testmethod.order.default=org.junit.jupiter.api.MethodOrderer$Random' test |
|||
``` |
|||
|
|||
Result: `Tests run: 7, Failures: 0, Errors: 0, Skipped: 0`, `BUILD SUCCESS`. |
|||
|
|||
### OpenAPI verification |
|||
|
|||
```powershell |
|||
python docs\verify_openapi.py |
|||
``` |
|||
|
|||
Result: `paths: 135`; `N04 onboarding endpoints and schemas present (9 operations / 6 paths)`; `No empty ref keys found`; `Valid JSON: True`; `All checks passed!`. |
|||
|
|||
Structured checks found 0 removed paths, 6 added paths, 0 removed schemas, and 20 added schemas. |
|||
|
|||
## External Blockers |
|||
|
|||
The reported full-suite failures were independently reproduced in isolation: |
|||
|
|||
```powershell |
|||
& 'D:\maven\apache-maven-3.9.7\bin\mvn.cmd' '-Dtest=CareerProgressServiceTest,JobReviewDimensionControllerTest,JobReviewDimensionServiceTest,LocalResumeStorageServiceTest' test |
|||
``` |
|||
|
|||
Result: `Tests run: 69, Failures: 2, Errors: 9, Skipped: 0`, `BUILD FAILURE`. |
|||
|
|||
- `CareerProgressServiceTest.fullAggregation_returnsCorrectSummaries` fails with expected `1` but got `0`. |
|||
- `JobReviewDimensionControllerTest.listReviews_shouldReturnDimensionScores` fails with 500 due a null `Page`. |
|||
- `JobReviewDimensionServiceTest.listReviews_shouldReturnDimensionScoresWithoutN1` fails with null `Page.getContent()`. |
|||
- `LocalResumeStorageServiceTest` reports 8 JUnit extension cleanup errors caused by sandbox `AccessDeniedException` on temporary directories. |
|||
|
|||
These failures are outside the W3 review range. `git diff --name-only a5730a7..310d931` contains no files in the failing controllers/services/storage paths. Across the full N04 branch from `a2c66b3`, the only review-package changes are additive query methods in `JobReviewRepository` and `JobReviewDimensionScoreRepository`; the failing CareerProgress and LocalResumeStorage code is unchanged. Therefore W3 itself can pass conditionally, but final release cannot be declared while `mvn clean verify` is red. |
|||
|
|||
Real MySQL 8.4/Docker execution also remains outstanding. The contract requires it for the final completion proof, and it was not performed without separate authorization. |
|||
|
|||
## Minor Findings |
|||
|
|||
- `git diff --check a5730a7..310d931` reports two workflow-report files with blank lines at EOF (`W2-T4.md`, `W2-T5.md`). This is documentation-only and non-blocking. |
|||
- Some OpenAPI error-code assertions remain partly textual rather than exact response-shape assertions. The repaired defaults/examples are covered. |
|||
- H2 `MODE=MySQL` is strong regression coverage but is not a substitute for the pending real-database acceptance gate. |
|||
|
|||
## Assessment |
|||
|
|||
**W3 passes conditionally.** T6 concurrency repair, T7 end-to-end coverage, and T8 contract/docs repair are integrated and verified; no blocking W3 finding remains. The final release/DP-7 gate remains blocked by the independently reproduced non-N04 full-suite failures and the pending real MySQL 8.4/Docker acceptance run. |
|||
|
|||
Report path: `D:\1\zhi\zhilai\changes\n04-onboard\.superpowers\sdd\reviews\W3-wave.md` |
|||
@ -0,0 +1,35 @@ |
|||
# T8 聚焦修复 1：OpenAPI 示例与默认值 |
|||
|
|||
## Prior Failure |
|||
|
|||
`W3-T8.md` 发现： |
|||
|
|||
- `PUT /onboarding/company/knowledge` 的 200 示例缺少运行时响应必备的 `version`。 |
|||
- `CompanyChecklistItemCreateRequest` 缺少运行时默认值 `sortOrder=1000`、`required=false`。 |
|||
- `docs/verify_openapi.py` 未断言示例字段和 schema 默认值，因此未捕获上述偏差。 |
|||
|
|||
## Objective |
|||
|
|||
修正 OpenAPI 契约，并增强验证脚本，使示例、默认值与运行时 DTO 一致。 |
|||
|
|||
## Required Changes |
|||
|
|||
- 在 `docs/openapi-rc.json` 中修正 `PUT /onboarding/company/knowledge` 的 200 示例，包含 `version`。 |
|||
- 为 `CompanyChecklistItemCreateRequest.sortOrder` 增加默认值 `1000`。 |
|||
- 为 `CompanyChecklistItemCreateRequest.required` 增加默认值 `false`。 |
|||
- 在 `docs/verify_openapi.py` 中增加精确断言： |
|||
- 知识 Upsert 200 示例的 `data.version` 存在。 |
|||
- 创建请求 schema 的两个默认值正确。 |
|||
- 不修改 runtime API 行为。 |
|||
|
|||
## Evidence |
|||
|
|||
```powershell |
|||
cd D:\1\zhi\zhilai |
|||
python .\docs\verify_openapi.py |
|||
``` |
|||
|
|||
```powershell |
|||
cd D:\1\zhi\zhilai\mydreamjob-server |
|||
mvn -Dtest=Onboarding*Test,CompanyKnowledge*Test test |
|||
``` |
|||
Loading…
Reference in new issue