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