lxq/changes/n04-onboard/.superpowers/sdd/task-briefs/T3.md

T3 任务简报：学生有效清单与完成状态

Where This Fits

• Wave: W1
• Depends on: T2
• Contract: changes/n04-onboard/execution-contract.md
• Specs: changes/n04-onboard/specs/onboarding-checklist/spec.md

Objective

实现 STUDENT 读取有效入职清单和更新本人完成状态的 Service、DTO 与 Controller，先用失败测试锁定回退、合并排序、完成率和幂等语义。

Files In Scope

• mydreamjob-server/src/main/java/com/mydreamjob/onboarding/OnboardingChecklistService.java
• mydreamjob-server/src/main/java/com/mydreamjob/onboarding/OnboardingChecklistController.java
• mydreamjob-server/src/main/java/com/mydreamjob/onboarding/dto/ChecklistItemView.java
• mydreamjob-server/src/main/java/com/mydreamjob/onboarding/dto/EffectiveChecklistResponse.java
• mydreamjob-server/src/main/java/com/mydreamjob/onboarding/dto/ProgressUpdateRequest.java
• mydreamjob-server/src/main/java/com/mydreamjob/onboarding/dto/ProgressUpdateResponse.java
• mydreamjob-server/src/test/java/com/mydreamjob/onboarding/OnboardingChecklistServiceTest.java
• mydreamjob-server/src/test/java/com/mydreamjob/onboarding/OnboardingChecklistControllerTest.java

Required Behavior

• GET /api/v1/onboarding/companies/{companyId}/checklist 仅服务 STUDENT。
• 企业没有活动自定义项时返回通用清单并设置 customized=false；有自定义项时返回通用项+企业项并按 sortOrder ASC, id ASC 排序。
• 响应包含 companyId、companyName、customized、totalItems、completedItems、completionRate 和 items。
• item 包含 itemId、source、itemKey、title、description、category、required、sortOrder、active、completed、completedAt、progressVersion。
• PUT /api/v1/onboarding/companies/{companyId}/checklist/items/{itemId}/completion 设置绝对完成状态。
• 首次完成写入 completedAt；取消完成清空 completedAt。
• 相同状态重复提交必须幂等成功，不增加数据库记录。
• 状态不同且提供过期 version 时返回 ONBOARDING_PROGRESS_CONCURRENT_UPDATE。
• item 必须属于该企业的活动项或活动通用项，否则返回 ONBOARDING_CHECKLIST_ITEM_NOT_FOUND。
• 企业不存在返回 COMPANY_NOT_FOUND；非 STUDENT 返回 FORBIDDEN。
• 完成率保留一位小数，空清单为 0.0，最大 100.0。

TDD Requirement

1. 先写 Service 和 Controller 失败测试，确认 RED。
2. 再实现最小 DTO、Service、Controller 使测试 GREEN。
3. 不实现企业自定义项 CRUD 或公司知识接口。

Evidence Commands

cd D:\1\zhi\zhilai\mydreamjob-server
mvn -Dtest=OnboardingChecklistServiceTest,OnboardingChecklistControllerTest test

Done Definition

• 测试覆盖通用回退、企业合并、稳定排序、首次完成、重复相同状态、取消完成、版本冲突、跨企业 itemId 和企业不存在。
• 响应不泄露内部用户字段。
• 不修改既有已验收接口。