# n04-onboard 入职清单与公司知识介绍

## Why

产品功能表将 M1.1「入职清单」和 M1.2「公司了解」列为一期 P2 功能，但当前后端没有对应表、服务、API、权限或测试。学生缺少可执行的标准入职准备事项，也无法在一个接口中集中查看企业基础资料、企业文化与制度、员工评价摘要；企业也没有维护自定义清单和公司知识内容的入口。

本变更以最小可用闭环补齐后端能力：通用清单提供稳定基线，企业自定义项补足差异，学生的个人完成状态可持续计算完成率；公司知识优先展示企业已维护内容与公开评价摘要，信息不足时合法回退到企业基础信息。

## What Changes

- 新增 `onboarding` 后端模块，提供 9 个接口：
  - `GET /onboarding/companies/{companyId}/checklist`
  - `PUT /onboarding/companies/{companyId}/checklist/items/{itemId}/completion`
  - `GET /onboarding/companies/{companyId}/knowledge`
  - `GET /onboarding/company/checklist-items`
  - `POST /onboarding/company/checklist-items`
  - `PUT /onboarding/company/checklist-items/{itemId}`
  - `DELETE /onboarding/company/checklist-items/{itemId}`
  - `GET /onboarding/company/knowledge`
  - `PUT /onboarding/company/knowledge`
- 新增三类持久化数据：通用/企业自定义清单项、学生对清单项的完成状态、企业知识内容。
- 通过 Flyway 写入通用入职清单种子数据；企业未配置自定义项时，学生仍获得通用清单。
- 公司知识聚合企业基础资料、企业维护的文化/制度/入职指南，以及该公司所有公开岗位评价的汇总；有效公开评价少于 3 条时不展示平均分，避免小样本暴露。
- 企业配置接口仅允许企业维护本公司数据；学生接口仅允许学生读取公司资料并更新本人清单状态。
- 补齐错误码、幂等键、乐观锁、MockMvc、Service、持久化、迁移、端到端测试、OpenAPI 与前端联调文档。

## Scope

### In Scope

- 通用清单的数据库种子数据、排序、分类和必填标记。
- 企业自定义清单项的创建、查询、更新和软删除。
- 学生按企业读取有效清单、查看个人完成状态、设置完成或未完成。
- 企业知识内容的读取与 Upsert。
- 公司知识介绍聚合公司基础资料与公开评价摘要，并支持 `BASIC_ONLY` 回退。
- COMPANY 所有权校验、STUDENT 角色校验、敏感字段白名单响应。
- 创建幂等、更新/删除乐观锁、并发冲突错误码和重复请求重放。
- 模块自动化测试、OpenAPI 静态契约校验和前端联调文档。

### Out of Scope

- ADMIN 管理通用模板、发布审核、版本回滚和内容治理后台。
- 通知提醒、职场内容推荐、试用期提醒、入职回访和在职反馈。
- 按岗位、投递或 Offer 生成个性化清单。
- 第三方 CMS、富文本 HTML、AI 生成公司介绍或 AI 内容审核。
- 学生端页面、企业端页面和前端状态管理。
- 修改已有企业、岗位、Offer 或评价接口的响应语义。

## Impact

- `mydreamjob-server/src/main/resources/db/migration/`：新增 V38、V39 迁移，不修改 V1-V37。
- `mydreamjob-server/src/main/java/com/mydreamjob/onboarding/`：新增领域实体、Repository、Service、Controller 和 DTO。
- `mydreamjob-server/src/main/java/com/mydreamjob/common/exception/ErrorCode.java`：新增 97xx 错误码。
- `docs/openapi-rc.json`、`docs/onboarding-api.md`、`docs/frontend-integration.md`、路线图和 README 状态说明。
- 现有 `Company`、`Job`、`JobReview`、`JobReviewDimensionScore` 只读复用，不改变其表结构和接口。
- 新增表使用 Flyway，支持 MySQL 8.4 与 H2 `MODE=MySQL` 集成测试。

## Proof of Completion

- 学生可在企业无自定义项时取得通用清单；有自定义项时取得合并后的有效清单。
- 学生重复设置同一完成状态不产生重复行，完成率和完成时间正确；并发冲突返回明确 409 错误码。
- 企业只能操作本企业数据；跨企业 itemId、非 COMPANY 或非 STUDENT 请求返回 403/404，不泄露其他企业数据。
- 公司知识响应只包含白名单字段；无企业知识内容时返回 `BASIC_ONLY` 和企业基础资料；评价少于 3 条时不返回平均分。
- `mvn -Dtest=Onboarding*Test test`、`mvn clean verify`、`python docs/verify_openapi.py` 全部通过。
- OpenAPI 契约包含全部 9 个路径、请求体和响应模型，且与运行时文档一致。