# n04-onboard 实施任务

## Delivery / Proof Map

| Requirement Area | Tasks | Evidence |
|---|---|---|
| 通用/企业清单数据模型与种子 | 1, 2 | 迁移测试、Repository 集成测试 |
| 学生有效清单与完成状态 | 2, 3, 6 | Service 单元测试、MockMvc、持久化测试 |
| 企业自定义项 CRUD、幂等、并发 | 2, 4, 6 | Service 单元测试、MockMvc、Repository 集成测试 |
| 公司知识配置与基础信息回退 | 1, 2, 5 | Service 单元测试、MockMvc、持久化测试 |
| 公开评价摘要与小样本保护 | 2, 5 | 聚合 Service 测试、评价边界测试 |
| 权限、白名单响应和错误码 | 6, 7 | 未登录、角色、跨企业、脱敏断言 |
| OpenAPI、前端联调和文档 | 8 | `python docs/verify_openapi.py`、文档检查 |
| 全量回归和可发布证明 | 8 | `mvn clean verify`、专项测试汇总 |

## Tasks

- [ ] 1. 新增 V38 建表迁移与 V39 通用清单种子，路径为 `mydreamjob-server/src/main/resources/db/migration/`。可观察结果：MySQL/H2 均可创建 `onboarding_checklist_items`、`student_onboarding_progress`、`company_knowledge`，主外键、唯一键和索引存在；通用清单按分类和稳定排序写入。证据：`mvn -Dtest=OnboardingMigrationTest,OnboardingSeedDataIntegrationTest test`。依赖：无。
- [ ] 2. 新增 `com.mydreamjob.onboarding` 领域实体与 Repository，路径为 `mydreamjob-server/src/main/java/com/mydreamjob/onboarding/`。可观察结果：可查询某企业的活动通用+自定义项、批量查询当前学生完成记录、按企业查询知识记录，并为评价聚合提供跨岗位只读查询。证据：`mvn -Dtest=OnboardingRepositoryIntegrationTest test`。依赖：1。
- [ ] 3. 实现学生有效清单查询与完成状态更新服务及接口，路径为 `OnboardingChecklistService.java`、`OnboardingChecklistController.java` 和对应 DTO。可观察结果：无企业自定义项时返回通用清单，有自定义项时合并排序；PUT 支持完成/取消完成、重复同状态幂等、完成率与完成时间正确。证据：`mvn -Dtest=OnboardingChecklistServiceTest,OnboardingChecklistControllerTest test`。依赖：2。
- [ ] 4. 实现企业自定义清单项查询、创建、更新和软删除，路径为 `OnboardingChecklistService.java`、`OnboardingChecklistController.java` 和对应 DTO。可观察结果：仅企业本人可操作；创建支持 `idempotencyKey` 重放与请求体哈希冲突；更新/删除使用版本号；软删除后条目从学生有效清单消失但历史完成记录保留。证据：`mvn -Dtest=OnboardingCompanyChecklistServiceTest,OnboardingCompanyChecklistControllerTest test`。依赖：1, 2。
- [ ] 5. 实现企业知识内容 Upsert 和学生公司知识聚合，路径为 `CompanyKnowledgeService.java`、`CompanyKnowledgeController.java` 和对应 DTO。可观察结果：企业读取无记录时返回 `configured=false`；学生读取无知识时返回 `BASIC_ONLY`；公开评价少于 3 条不返回均值；达到 3 条时返回平均分、分布、标签和八维摘要。证据：`mvn -Dtest=CompanyKnowledgeServiceTest,CompanyKnowledgeControllerTest test`。依赖：2。
- [ ] 6. 接入角色、所有权、错误码、幂等和乐观锁，路径为 `SecurityConfig.java`、`ErrorCode.java`、`OnboardingChecklistService.java`、`CompanyKnowledgeService.java`。可观察结果：`/onboarding/**` 仅认证访问；STUDENT/COMPANY 角色和公司所有权严格隔离；9701-9706 在目标冲突场景返回 409/404；响应 DTO 不包含内部身份或审核字段。证据：`mvn -Dtest=OnboardingAuthorizationIntegrationTest,OnboardingConcurrencyIntegrationTest,OnboardingPrivacyTest test`。依赖：3, 4, 5。
- [ ] 7. 补齐模块测试，路径为 `mydreamjob-server/src/test/java/com/mydreamjob/onboarding/`。可观察结果：Service、MockMvc、持久化、迁移、种子、权限、幂等、并发、回退、小样本和端到端场景全部覆盖；测试断言响应状态、错误码、数据库行数和排序。证据：`mvn -Dtest=Onboarding*Test test`。依赖：3, 4, 5, 6。
- [ ] 8. 更新 OpenAPI、接口文档、前端联调说明和路线图，路径为 `docs/openapi-rc.json`、`docs/onboarding-api.md`、`docs/frontend-integration.md`、`docs/backend-development-roadmap.md`、`README.md`。可观察结果：9 个路径及 DTO 与运行时一致；前端文档给出请求示例、错误码、版本和幂等说明；路线图将本模块标记为实现完成/待验收。证据：`python docs/verify_openapi.py`，随后执行 `mvn clean verify`。依赖：3, 4, 5, 6, 7。

## Requirement-to-Task Coverage

| Spec Requirement | Covered By |
|---|---|
| 学生读取有效入职清单 | 1, 2, 3 |
| 学生更新个人清单完成状态 | 2, 3, 6, 7 |
| 企业创建自定义清单项 | 1, 2, 4, 6, 7 |
| 企业查询和更新自定义清单项 | 2, 4, 6, 7 |
| 企业软删除自定义清单项 | 2, 4, 6, 7 |
| 清单权限和数据最小化 | 3, 4, 6, 7 |
| 学生读取公司知识介绍 | 1, 2, 5, 7 |
| 公司知识评价摘要与小样本保护 | 2, 5, 7 |
| 企业读取本企业知识配置 | 1, 2, 5, 7 |
| 企业 Upsert 公司知识内容 | 1, 2, 5, 6, 7 |
| 公司知识权限与所有权隔离 | 5, 6, 7 |
| 不改变既有评价与企业接口语义 | 7, 8 |

## Completion Gate

- 所有任务完成且专项测试、全量测试、OpenAPI 校验通过后才能进入 release-archivist。
- 不允许降低既有接口语义、删除业务数据或跳过迁移验证。