lxq/changes/n04-onboard/proposal.md

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 个路径、请求体和响应模型，且与运行时文档一致。