# Organization 2026-03-13 Backend Report

## 变更范围

- 模块：`organization / dingtalk annual leave`
- 类型：后端单元测试 + 前端定向 lint
- 目标：
  - 新增员工年假计划参数查询/更新接口
  - 支持按指定年份重算本地年假释放计划
  - 前端两处页面接入“点击姓名编辑年假计划参数”

## 测试范围与选择说明

- 单元测试：
  - 年假同步服务增加了按年份重算能力，属于业务规则变更，补单测验证。
  - 新增年假计划参数管理服务，补单测验证查询、更新、异常分支。
  - 控制器新增接口，补单测验证透传行为。
- E2E：
  - 本次未执行。当前变更以服务层和页面交互接线为主，先用后端单测和前端 lint 做闭环验证。

## 执行命令

```bash
cd /home/ffws01/Code/ffworkspace/backend && npx jest test/modules/organization/unit/annual-leave-sync.service.spec.ts test/modules/organization/unit/annual-leave-plan-admin.service.spec.ts test/modules/organization/unit/dingtalk-controller.spec.ts --runInBand --config '{"moduleFileExtensions":["js","json","ts"],"rootDir":".","testRegex":".*\\.spec\\.ts$","transform":{"^.+\\.(t|j)s$":"ts-jest"},"moduleNameMapper":{"^@/(.*)$":"<rootDir>/src/$1","^@core/(.*)$":"<rootDir>/src/core/$1"}}'
cd /home/ffws01/Code/ffworkspace/frontend && npx eslint src/app/'(modules)'/organization/dingtalk/annual-leave/quotas/page.tsx src/app/'(modules)'/organization/dingtalk/annual-leave/release-plan/page.tsx src/components/organization/dingtalk-annual-leave-plan-settings-dialog.tsx src/services/api/dingtalk.ts src/locales/organization/zh.ts src/locales/organization/en.ts
```

## 结果

- 后端单测：通过
  - `annual-leave-sync.service.spec.ts`
  - `annual-leave-plan-admin.service.spec.ts`
  - `annual-leave-insight.service.spec.ts`
  - `dingtalk-controller.spec.ts`
  - 汇总：`18/18`
- 前端定向 lint：通过

## 本次补充验证

- 缺少入职日期或首次参加工作日期时：
  - 同步任务会创建 `totalDays = 0`、`releaseSchedule = []` 的空计划记录
  - 点击编辑时如果本地尚无计划记录，会自动创建占位记录后再返回编辑数据
- `status = 顾问` 时：
  - 与 `停薪留职` 语义一致
  - 本年度不生成释放计划
  - 释放计划页会显示“员工状态为顾问，本年度不生成释放计划”
- 年假释放计划页状态筛选：
  - 默认隐藏 `顾问 / 停薪留职 / 已离职`
  - 开启对应开关后，后端会返回匹配状态员工，而不是只做前端本地隐藏

## 最小复现步骤

1. 打开“组织架构 > 钉钉同步 > 假期余额总览”或“年假释放计划”。
2. 点击员工姓名，打开“编辑年假计划参数”弹窗。
3. 调整 `状态 / 额度扣减天数 / 释放计划偏移天数` 并保存。
4. 重新打开同一员工，确认参数已更新。
5. 在“年假释放计划”中查看对应年度计划，确认修改后已按新参数重算。

## 结论

- 本次变更已完成基础验证，可进入联调或人工验收阶段。