# 钉钉模块 - 用户场景

> **版本**: v1.0  
> **最后更新**: 2026-03-17  
> **维护者**: FFOA Team

---

## 场景摘要

| 角色 | 目标 | 入口 |
|------|------|------|
| 系统管理员 | 查看同步状态并手动触发任务 | `/organization/dingtalk` |
| 系统管理员 | 修复错误写入的考勤审批记录 | `/organization/dingtalk` |
| HR / 组织运营 | 查看假期余额与明细 | `/organization/dingtalk/annual-leave/quotas` |
| HR / 组织运营 | 查看、重算和导出年假释放计划 | `/organization/dingtalk/annual-leave/release-plan` |

---

## 用户旅程

### 旅程 1：系统管理员查看同步健康状态

1. 进入 `/organization/dingtalk`
2. 查看顶部概览卡片：
   - 任务总数
   - 已注册任务数
   - 今日成功数
   - 今日失败数
   - 当前启用状态
3. 查看任务卡片和最近执行记录
4. 若发现异常任务，展开任务参数区域继续手动触发

**成功标准**:

- 能快速判断当前钉钉同步是否可用
- 能定位到失败任务和最近日志

### 旅程 2：系统管理员手动触发某个同步任务

1. 在任务卡片中选择目标任务
2. 根据任务类型填写可选参数：
   - 支持时间范围的任务填写 `fromTime` / `toTime`
   - 支持员工过滤的任务填写 `userId`
3. 点击执行
4. 页面通过 SSE 实时展示流式日志
5. 任务结束后刷新概览和执行记录

**关键规则**:

- 出差、外勤、加班、假期延期等考勤类任务会被后端强制收敛到最近 60 天
- 员工信息和年假类任务不依赖时间范围

### 旅程 3：系统管理员进行审批撤销修复

1. 在 `/organization/dingtalk` 打开审批撤销修复面板
2. 选择同步类型
3. 指定员工
4. 输入审批号，可为精确值或 `undefined-*`
5. 先点击预览，确认命中记录
6. 再执行实际撤销
7. 查看处理结果、错误数量与日志

**成功标准**:

- 只命中当前同步类型和当前员工的真实审批
- 执行后得到可追踪的结果记录

### 旅程 4：HR 查看假期余额总览

1. 进入 `/organization/dingtalk/annual-leave/quotas`
2. 页面读取本地快照并渲染统计卡和余额矩阵
3. 可按员工关键字筛选
4. 可切换“隐藏 0 余额”
5. 如需要最新数据，点击“刷新快照”

**成功标准**:

- 页面无需直接请求实时钉钉余额接口即可展示数据
- 用户能快速定位某个员工某种假期的剩余额度

### 旅程 5：HR 查看余额详情并调整计划参数

1. 在余额总览页点击某个余额单元格，查看详情抽屉
2. 在余额页或释放计划页点击员工姓名
3. 打开年假计划参数弹窗
4. 查看只读信息：
   - 员工姓名
   - `userId`
   - 年度
   - 总计划天数
   - 最近重算时间
5. 编辑：
   - `adjustmentDays`
   - `notCountDays`
6. 点击保存，当前实现直接保存并重算

**成功标准**:

- 能区分“额度扣减”和“计划偏移”两个参数
- 保存后页面能反映新的计划结果

### 旅程 6：HR 查看与重算年假释放计划

1. 进入 `/organization/dingtalk/annual-leave/release-plan`
2. 按年度、关键字、是否仅看未来未释放筛选
3. 查看按员工展开的矩阵
4. 对无计划员工查看 `noPlanReason`
5. 点击“更新中间表”重算计划
6. 如需要执行真实发放，点击释放
7. 如需要线下核对，导出 CSV

**关键规则**:

- 页面默认只展示 `正常` 员工
- 无计划员工不会消失，而是保留在结果中并显示原因