From 6e7d537f8aef97b659910425e642f297a774457d Mon Sep 17 00:00:00 2001 From: pwklppg <123456@.com> Date: Thu, 17 Sep 2026 09:50:43 +0800 Subject: [PATCH] docs: record W3 onboarding verification status --- changes/n04-onboard/.spec-superflow.yaml | 3 +- .../.superpowers/sdd/execution-plan.yaml | 8 +- .../n04-onboard/.superpowers/sdd/progress.md | 3 + .../sdd/reviews/W3-T8-rereview.md | 83 +++++++++++++ .../.superpowers/sdd/reviews/W3-T8.md | 78 ++++++++++++ .../.superpowers/sdd/reviews/W3-wave.md | 113 ++++++++++++++++++ .../sdd/task-briefs/T8-repair-1.md | 35 ++++++ 7 files changed, 319 insertions(+), 4 deletions(-) create mode 100644 changes/n04-onboard/.superpowers/sdd/reviews/W3-T8-rereview.md create mode 100644 changes/n04-onboard/.superpowers/sdd/reviews/W3-T8.md create mode 100644 changes/n04-onboard/.superpowers/sdd/reviews/W3-wave.md create mode 100644 changes/n04-onboard/.superpowers/sdd/task-briefs/T8-repair-1.md diff --git a/changes/n04-onboard/.spec-superflow.yaml b/changes/n04-onboard/.spec-superflow.yaml index 7c72627..68f7604 100644 --- a/changes/n04-onboard/.spec-superflow.yaml +++ b/changes/n04-onboard/.spec-superflow.yaml @@ -30,7 +30,7 @@ plan_revision: 1 dp_4_result: approved: SDD selected; W1 serial T1-T2, W2 serial T3-T5 depends W1, W3 serial T6-T8 depends W2 dp_4_confirmed: true dp_4_timestamp: 2026-09-16T07:58:31Z -batches_completed: 2 +batches_completed: 3 execution_paused: false paused_at: 2026-09-16T09:51:43Z paused_reason: user requested pause for the day; T7 tests are complete but independent T7 review and T8 remain pending @@ -38,3 +38,4 @@ resume_from: T7-review resume_mode: manual resumed_at: 2026-09-17T01:17:47Z resume_count: 1 +verification_blocked: true diff --git a/changes/n04-onboard/.superpowers/sdd/execution-plan.yaml b/changes/n04-onboard/.superpowers/sdd/execution-plan.yaml index 07fb15d..809634d 100644 --- a/changes/n04-onboard/.superpowers/sdd/execution-plan.yaml +++ b/changes/n04-onboard/.superpowers/sdd/execution-plan.yaml @@ -2,7 +2,7 @@ plan_revision: 1 selected_mode: sdd contract_hash: 79e718e36a2fd349a8c26dfd080e74a1844c01a6e52363613414694bc75a74d1 created_at: 2026-09-16T07:58:31Z -current: W3 +current: verification waves: - id: W1 strategy: serial @@ -20,5 +20,7 @@ waves: strategy: serial tasks: [T6, T7, T8] depends_on: [W2] - state: eligible - receipt: T6 pass; T7 pass; T8 pending \ No newline at end of file + state: passed_with_external_blocker + receipt: .superpowers/sdd/reviews/W3-wave.md +verification_blocked: true +closure_requires: external full-suite repair or waiver; real MySQL 8.4 / Docker acceptance diff --git a/changes/n04-onboard/.superpowers/sdd/progress.md b/changes/n04-onboard/.superpowers/sdd/progress.md index c9232d2..b2db2c6 100644 --- a/changes/n04-onboard/.superpowers/sdd/progress.md +++ b/changes/n04-onboard/.superpowers/sdd/progress.md @@ -18,3 +18,6 @@ - 2026-09-17T01:17:47Z Manual resume accepted. W3 resumes at T7 independent review; T6 remains passed and T8 remains pending. - 2026-09-17T01:21:54Z Task T7: review W3-T7 PASS; 30 focused tests, 96 onboarding regressions, randomized E2E pass. - 2026-09-17T09:33:54Z Task T8: documentation implementation complete; after adding missing onboarding assertions, verifier RED was `Missing onboarding path: /onboarding/companies/{companyId}/checklist`; static OpenAPI now 135 paths / 172 operations and contains 9 onboarding operations / 6 paths / 20 schemas; `python docs/verify_openapi.py` PASS; N04 focused regression PASS (96 tests); `mvn clean verify` FAIL (1492 tests, 2 failures, 9 errors) in existing CareerProgress/JobReviewDimension/LocalResumeStorage tests unrelated to T8; `mvn -DskipTests package` PASS; no commit; independent T8/W3 review pending. +- 2026-09-17T01:41:13Z Task T8: failed attempt 1/3 - review W3-T8 FAIL; OpenAPI knowledge example lacks version and create request schema omits runtime defaults. +- 2026-09-17T01:45:47Z Task T8: complete after focused repair (commit 310d931; W3-T8-rereview PASS; OpenAPI 135 paths / 172 operations, 9 onboarding operations / 6 paths; 96 tests pass). +- 2026-09-17T01:50:30Z W3 wave review PASS (conditional within N04): 96 tests, RR boundary 1, randomized E2E 7, OpenAPI 135 paths/9 operations; external blockers are existing full-suite failures and pending MySQL/Docker acceptance. diff --git a/changes/n04-onboard/.superpowers/sdd/reviews/W3-T8-rereview.md b/changes/n04-onboard/.superpowers/sdd/reviews/W3-T8-rereview.md new file mode 100644 index 0000000..0be808c --- /dev/null +++ b/changes/n04-onboard/.superpowers/sdd/reviews/W3-T8-rereview.md @@ -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 +``` diff --git a/changes/n04-onboard/.superpowers/sdd/reviews/W3-T8.md b/changes/n04-onboard/.superpowers/sdd/reviews/W3-T8.md new file mode 100644 index 0000000..28a03c0 --- /dev/null +++ b/changes/n04-onboard/.superpowers/sdd/reviews/W3-T8.md @@ -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 +``` \ No newline at end of file diff --git a/changes/n04-onboard/.superpowers/sdd/reviews/W3-wave.md b/changes/n04-onboard/.superpowers/sdd/reviews/W3-wave.md new file mode 100644 index 0000000..5dae57d --- /dev/null +++ b/changes/n04-onboard/.superpowers/sdd/reviews/W3-wave.md @@ -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` diff --git a/changes/n04-onboard/.superpowers/sdd/task-briefs/T8-repair-1.md b/changes/n04-onboard/.superpowers/sdd/task-briefs/T8-repair-1.md new file mode 100644 index 0000000..5dabfbb --- /dev/null +++ b/changes/n04-onboard/.superpowers/sdd/task-briefs/T8-repair-1.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 +``` \ No newline at end of file