15 KiB

Raw Blame History

N04 入职清单与公司知识介绍执行契约

Intent Lock

问题：产品一期要求提供入职清单和公司知识介绍，但当前后端没有对应表、接口、权限或测试。学生无法获得“通用准备项 + 企业自定义项”的有效清单，无法保存个人完成状态，也无法集中查看企业基础资料、文化制度、入职指南和公开评价摘要；企业无法维护本公司差异内容。

意图：新增最小可用的 onboarding 后端模块。通过 V38/V39 建立三张业务表和通用清单种子；提供 9 个确定性接口；STUDENT 读取有效清单、更新本人完成状态、读取公司知识，COMPANY 仅维护本企业自定义清单与知识内容；公司知识使用企业基础资料、企业维护内容及公开评价摘要，其中公开评价少于 3 条时不返回均值。不调用 AI，不引入 ADMIN 内容治理。

完成证明：V38/V39 在 H2 与真实 MySQL 成功执行；9 个接口的权限、所有权、幂等、并发、回退、排序、完成率、评价摘要和小样本保护均通过自动化测试；OpenAPI、接口文档和前端联调文档与运行时一致；mvn clean verify 与 python docs/verify_openapi.py 通过。

Scope Fence

允许范围

新增 mydreamjob-server/src/main/resources/db/migration/V38__onboarding_checklist_and_company_knowledge.sql 和 V39__onboarding_standard_checklist_seed.sql。
新增 com.mydreamjob.onboarding 领域包，包括实体、Repository、Service、Controller、DTO 和测试。
修改 SecurityConfig.java，使 /onboarding/** 仅允许认证访问，并在服务层执行 STUDENT/COMPANY 角色与公司所有权校验。
修改 ErrorCode.java，新增 9701-9706。
更新 docs/openapi-rc.json、docs/onboarding-api.md、docs/frontend-integration.md、docs/backend-development-roadmap.md 和 README.md。
只读复用 Company、CompanyRepository、Job、JobReview、JobReviewDimensionScore 及其 Repository。
采用 9 个固定接口：
- GET /api/v1/onboarding/companies/{companyId}/checklist
- PUT /api/v1/onboarding/companies/{companyId}/checklist/items/{itemId}/completion
- GET /api/v1/onboarding/companies/{companyId}/knowledge
- GET /api/v1/onboarding/company/checklist-items
- POST /api/v1/onboarding/company/checklist-items
- PUT /api/v1/onboarding/company/checklist-items/{itemId}
- DELETE /api/v1/onboarding/company/checklist-items/{itemId}?version={version}
- GET /api/v1/onboarding/company/knowledge
- PUT /api/v1/onboarding/company/knowledge

禁止范围

不修改 V1-V37 历史迁移或既有表结构。
不修改既有企业、岗位、Offer、评价和维度评分接口的路径、请求、响应或权限语义。
不实现 ADMIN 模板管理、审核发布、版本回滚、CMS 或内容治理后台。
不实现通知、内容推荐、试用期提醒、入职回访、在职反馈或前端页面。
不按岗位、投递或 Offer 生成个性化清单，不引入入职资格门槛。
不接 AI、第三方内容平台、外部搜索或实时同步。
不存储或渲染 HTML/富文本；知识字段按纯文本处理并限制长度。
不在响应或日志中输出 ownerUserId、员工用户 ID、手机号、邮箱、Token、IP、User-Agent、评价哈希或审核原因。
不启动或停止 Docker；真实 MySQL/Docker 黑盒验收需要用户单独授权。

Approved Behavior

ID	已批准行为	批次
REQ-OC-1	STUDENT 按存在的 `companyId` 获取有效清单；响应包含通用项与企业活动自定义项、排序、分类、必填标记、个人完成状态、完成数、总数、完成率和 `customized`；企业不存在返回 404。	B1、B2
REQ-OC-2	STUDENT 通过 PUT 将本人对有效条目的状态设置为完成或未完成；相同状态重复提交幂等；取消完成清除 `completedAt`；跨企业或非活动 itemId 返回 404；响应返回版本和最新完成率。	B1、B2、B3
REQ-OC-3	COMPANY 创建本企业自定义项；请求校验标题、说明、分类、排序和必填标记；相同 `idempotencyKey` 与相同请求体返回原条目，不同请求体返回 409 `ONBOARDING_IDEMPOTENCY_CONFLICT`；活动自定义项达到 50 条后返回 409 `ONBOARDING_ITEM_LIMIT_EXCEEDED`。	B1、B2、B3
REQ-OC-4	COMPANY 查询本企业全部自定义项；使用当前 `version` 更新标题、说明、分类、排序、必填和活动状态；过期版本返回 409 `ONBOARDING_CHECKLIST_ITEM_CONCURRENT_UPDATE`；不得读取或修改其他企业条目。	B1、B2、B3
REQ-OC-5	COMPANY 使用当前 `version` 软删除本企业条目；条目从学生有效清单消失，历史和完成记录保留；重复删除幂等成功；跨企业删除返回 404 且状态不变。	B1、B2、B3
REQ-OC-6	学生接口仅允许 STUDENT；企业配置接口仅允许 COMPANY 且只能操作当前用户拥有的企业；未登录返回 401，角色不符返回 403，无企业资料返回 404；所有响应使用白名单 DTO。	B2、B3
REQ-CK-1	STUDENT 按存在的 `companyId` 读取公司知识；企业有知识记录返回 `CONFIGURED`，无记录返回 `BASIC_ONLY` 和企业基础资料；不得返回 `ownerUserId` 等内部字段；企业不存在返回 404。	B1、B2
REQ-CK-2	公司评价摘要只使用该公司岗位下 `PUBLISHED` 且审核为 `AUTO_APPROVED/APPROVED` 的评价；无评价返回 `EMPTY`；少于 3 条返回 `INSUFFICIENT` 和不含均值的真实数量；至少 3 条返回平均分、评分分布、热门标签和八维摘要，维度返回样本数和 `SUFFICIENT/INSUFFICIENT`。	B1、B2、B3
REQ-CK-3	COMPANY 读取本企业知识配置；无记录返回 `configured=false`、空内容和版本 0；有记录返回内容、更新时间和当前版本。	B1、B2
REQ-CK-4	COMPANY Upsert 本企业知识内容；文化最多 2000 字符，工作制度和入职指南最多 4000 字符，至少一个字段非空，按纯文本处理；已有记录使用当前版本，冲突返回 409 `ONBOARDING_KNOWLEDGE_CONCURRENT_UPDATE`。	B1、B2、B3
REQ-CK-5	公司知识学生读取仅允许 STUDENT；企业配置仅允许 COMPANY 且只操作本企业；非角色访问返回 401/403；不存在的公司返回 404。	B2、B3
REQ-CK-6	本变更只读复用既有企业、岗位、评价和维度数据，不修改历史表结构和既有接口语义；既有测试与 OpenAPI 路径必须回归通过。	B3

需求覆盖结果：两份 spec 中全部 12 条 Requirement 的 MUST/SHALL 行为均已映射到 Approved Behavior、至少一个测试义务和至少一个执行批次，无未映射需求。

Architecture and Interface Constraints

数据模型固定为 onboarding_checklist_items、student_onboarding_progress、company_knowledge 三张表。
onboarding_checklist_items 使用 scope_type/scope_id/item_key 区分并唯一化 STANDARD 与 COMPANY 条目；company_id 仅对企业项建立外键。
student_onboarding_progress(student_user_id, item_id) 唯一；完成状态采用绝对值 Upsert，completedAt 仅在完成时存在。
company_knowledge.company_id 唯一；知识内容按纯文本存储并使用 @Version。
通用清单由 V39 固定种子提供，企业自定义项只增量追加，不允许覆盖或裁剪通用项。
学生有效清单必须在一次查询中合并活动通用项和企业项，并使用 sortOrder ASC, id ASC 稳定排序。
完成率计算为 completedItems * 100.0 / totalItems，保留一位小数并最大为 100.0；空清单为 0.0。
创建清单项使用 idempotencyKey 和规范化请求体 SHA-256；更新、删除、完成状态和知识内容使用乐观锁语义。
公司评价摘要必须通过公司下所有岗位聚合，不得只使用单个岗位汇总；热门标签从公开评价 tags 中计数，按次数降序、字典序升序，最多 10 个。
八维摘要复用 ReviewDimension，八个维度均返回，缺失维度样本数为 0、dataState=INSUFFICIENT。
所有响应使用 ApiResponse<T>；请求 ID 从 X-Request-Id 读取。
新增错误码固定为：
- 9701 ONBOARDING_CHECKLIST_ITEM_NOT_FOUND
- 9702 ONBOARDING_CHECKLIST_ITEM_CONCURRENT_UPDATE
- 9703 ONBOARDING_ITEM_LIMIT_EXCEEDED
- 9704 ONBOARDING_IDEMPOTENCY_CONFLICT
- 9705 ONBOARDING_PROGRESS_CONCURRENT_UPDATE
- 9706 ONBOARDING_KNOWLEDGE_CONCURRENT_UPDATE
复用 FORBIDDEN、UNAUTHORIZED、BAD_REQUEST 和 COMPANY_NOT_FOUND。
迁移编号以当前仓库下一个可用版本为准；若 V38/V39 被其他变更占用，必须回退规划阶段刷新编号和契约。

Execution Batches

Batch B1: 数据模型、迁移与只读聚合基础

覆盖任务：T1、T2。
交付物：V38/V39 迁移、三个实体、三个模块 Repository、现有评价跨岗位聚合查询、迁移和 Repository 集成测试。
完成定义：H2/MySQL 可创建三张表、约束和索引；通用种子数量和排序稳定；活动通用项与企业项可合并查询；学生完成记录可批量读取；公司公开评价可按评分、维度和 tags 聚合。
依赖：无。
评审门：B1 完成并由 code-reviewer 记录 pass 后才能开始 B2。

Batch B2: 学生清单、企业配置与公司知识接口

覆盖任务：T3、T4、T5。
交付物：两个 Controller、两个 Service、全部 DTO、清单合并与完成状态、自定义项 CRUD、知识 Upsert、基础信息和评价摘要组装、Service 与 MockMvc 专项测试。
完成定义：REQ-OC-1 至 REQ-OC-6、REQ-CK-1 至 REQ-CK-5 的接口和服务行为实现；企业无自定义项时回退通用清单；无知识时返回基础信息；公开评价少于 3 条不返回均值。
依赖：B1 通过评审。
评审门：B2 完成并由 code-reviewer 记录 pass 后才能开始 B3。

Batch B3: 权限、并发、契约、全量测试与文档

覆盖任务：T6、T7、T8。
交付物：SecurityConfig 与 ErrorCode 更新、角色和所有权集成测试、幂等与乐观锁冲突测试、隐私断言、端到端测试、OpenAPI、接口文档和前端联调文档。
完成定义：匿名 401、非角色 403、企业不存在 404、跨企业 404、版本冲突 409、幂等冲突 409、活动项上限 409 均符合契约；OpenAPI 包含 9 个路径并运行时一致；mvn clean verify 与 python docs/verify_openapi.py 通过。
依赖：B2 通过评审。
评审门：B3 完成并由 code-reviewer 记录 pass 后才能进入验证和收尾。

Test Obligations

ID	测试义务	批次	证据
TO-1	V38/V39 创建三张表、主外键、唯一键和索引；通用种子内容、分类和排序稳定。	B1	`mvn -Dtest=OnboardingMigrationTest,OnboardingSeedDataIntegrationTest test`
TO-2	企业无自定义项回退通用清单；有项时合并排序、来源和 category 正确。	B1、B2	Repository 集成测试、`OnboardingChecklistServiceTest`
TO-3	完成状态首次设置、重复相同状态、取消完成、跨企业 itemId 和完成率。	B2	`mvn -Dtest=OnboardingChecklistServiceTest,OnboardingChecklistControllerTest test`
TO-4	创建校验、幂等重放、请求体哈希冲突和 50 条活动项上限。	B2、B3	`OnboardingCompanyChecklistServiceTest`、持久化测试
TO-5	企业列表、更新、软删除、版本冲突、重复删除和跨企业隔离。	B2、B3	`OnboardingCompanyChecklistServiceTest`、`OnboardingConcurrencyIntegrationTest`
TO-6	STUDENT/COMPANY/ADMIN/匿名权限矩阵和白名单响应。	B2、B3	`OnboardingAuthorizationIntegrationTest`、`OnboardingPrivacyTest`
TO-7	公司知识无记录回退、企业读取、首次创建、更新和长度校验。	B2	`mvn -Dtest=CompanyKnowledgeServiceTest,CompanyKnowledgeControllerTest test`
TO-8	评价只取公开记录；0、1、2、3 条边界；评分分布、标签和八维摘要。	B1、B2	聚合 Repository 测试、`CompanyKnowledgeServiceTest`
TO-9	知识版本冲突返回 9706，不覆盖新内容。	B2、B3	`OnboardingConcurrencyIntegrationTest`
TO-10	9 个接口的状态码、请求/响应 DTO、错误码和 OpenAPI 一致性。	B3	`OnboardingEndToEndIntegrationTest`、`python docs/verify_openapi.py`
TO-11	迁移、种子、实体、Repository、Service、Controller 和权限集成场景全部可重复。	B1、B2、B3	`mvn -Dtest=Onboarding*Test test`
TO-12	既有模块回归、完整打包、静态契约和无敏感字段泄露。	B3	`mvn clean verify`、`python docs/verify_openapi.py`

Build Rules

每个批次按 TDD 先写失败测试，再实现最小行为，不得跳过测试。
只修改允许范围内文件；发现需要修改已验收接口、历史迁移或既有响应语义时立即停止并触发 Rewind。
迁移和种子数据必须可在 H2（MODE=MySQL）与真实 MySQL 执行，不依赖外部文件路径。
所有清单排序、完成率、评价汇总和标签排序必须确定性；禁止随机数、当前时间或请求顺序影响结果。
新增日志不得包含个人完成明细、Token、手机号、邮箱、IP、User-Agent、评价哈希或审核原因。
OpenAPI 注解、示例和实际响应必须一致，不能只改文档或只改运行时。
企业内容按纯文本处理，不拼接 HTML；前端展示安全由 JSON 字符串和前端转义共同保证。
不启动或停止 Docker；若需要真实 MySQL/Docker 黑盒验证，必须先取得用户单独授权。

Review Gates

DP-3：本执行契约必须由用户明确批准并记录 dp_3_result、dp_3_timestamp 后，才能开始任何实现。
Batch Review：B1、B2、B3 每批完成后由 code-reviewer 按规范符合性和代码质量评审，记录 pass 或 fail。
DP-4：批准契约后由 build-executor 给出执行模式和 wave 计划，用户确认后开始执行。
Verification Gate：实现完成后执行专项测试、全量测试、OpenAPI 校验和必要的 MySQL/Docker 黑盒验证。
DP-7：由 release-archivist 完成最终验证与关闭，不在本契约内自动完成。

Rewind Conditions

出现以下任一情况必须停止执行并回到规划阶段刷新工件和本契约：

需要新增、删除或改变用户可见接口、请求字段、响应字段、权限或错误语义。
需要改变数据表结构、唯一键、外键、通用/企业项来源模型或迁移编号。
需要改变完成状态幂等、乐观锁、完成率公式或软删除语义。
需要改变公开评价审核状态、3 条小样本阈值、八维维度或热门标签排序。
需要引入 ADMIN 模板治理、内容审核、版本回滚、通知、推荐、Offer 资格门槛或 AI。
需要修改 V1-V37、既有企业/岗位/评价接口或既有表结构。
V38/V39 被其他变更占用。
发现任一已批准 MUST/SHALL 无法映射到测试义务或执行批次。

DP-3 Approval Gate

执行者确认：本契约完整覆盖已批准的 12 条 Requirement，无未映射需求；B1→B2→B3 依赖清晰；不同批次之间的实体、Repository、DTO 和错误码接口已在 Architecture and Interface Constraints 中固定；所有测试义务均有证据命令。

批准方式：用户明确回复批准本执行契约后，记录 dp_3_result、dp_3_timestamp，再执行 specifying → bridging → approved-for-build 状态转换。DP-3 记录前禁止进入 build-executor。

15 KiB Raw Blame History