# 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

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

## Done Definition

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