# 钉钉模块 - 错误码

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

---

## 错误码摘要

当前模块尚未抽出独立的枚举式业务错误码，主要依赖：

1. 通用 HTTP 状态码
2. NestJS 异常消息
3. 钉钉开放平台返回的 `errcode` / `errmsg`

---

## 常见错误类型

| 场景 | HTTP / 返回 | 说明 | 处理建议 |
|------|-------------|------|----------|
| 员工不存在 | `404` | 查询年假计划参数时找不到员工 | 提示用户先同步员工 |
| 未知任务代码 | `200` + `success: false` | 手动触发不存在的任务 | 检查任务代码 |
| 缺少必填参数 | `200` 或 `400` | 如缺少 `userId` / `leaveCode` | 前端先做必填校验 |
| 钉钉接口失败 | 第三方 `errcode != 0` | 考勤、假期、审批等接口调用失败 | 记录日志并按接口返回排查 |
| 审批未命中 | `200` + `processedCount = 0` | 预览或撤销未扫描到真实审批 | 检查员工、时间范围、审批号模式 |
| 年假计划无法生成 | `200` + `hasPlan = false` | 员工缺少入职日期或首次参加工作日期 | 查看 `noPlanReason` |

---

## 典型错误消息

| 来源 | 示例 |
|------|------|
| `AnnualLeavePlanAdminService` | `未找到员工 {userId} 在 {year} 年的年假释放计划` |
| `DingtalkController` | `未知任务代码: {code}` |
| `getLeaveRecords` | `缺少 userId 或 leaveCode 参数` |
| 钉钉接口 | `errcode={n}, errmsg={message}` |

---

## 文档约束

后续若模块内新增稳定的业务错误码枚举，应补充：

1. 错误码标识
2. 触发条件
3. 前端展示文案
4. 对应恢复动作