# OA 看板钉钉待办接入方案

## 结论

正式系统**不能只靠新增环境变量**就直接发送钉钉待办。

原因：

1. 仓库当前只实现了钉钉登录与用户识别，没有“创建 / 更新 / 删除钉钉待办”的服务代码。
2. 当前没有“业务流程记录 <-> 钉钉待办 ID”的持久化表。
3. 当前没有发送幂等、失败重试、关闭待办、升级提醒等基础能力。

但从现有代码基础看，**补一层服务实现后，再由正式环境配置环境变量即可上线**。

## 现有基础

### 已具备

1. 钉钉 OAuth 登录能力
   - 文件：`src/server/services/dingtalk-auth.service.ts`
   - 已能完成：
     - 构建授权地址
     - 获取用户 access token
     - 获取 unionId
     - 获取 app access token
     - 用 unionId 换取 userId
     - 获取用户详情

2. 用户钉钉身份字段
   - 系统已保存并使用：
     - `dingtalkUserId`
     - `dingtalkUnionId`

3. OA 看板责任人映射
   - OA 看板已经能把不同阶段映射到默认责任角色 / 人员字段。
   - 例如首单下单待发起时可兜底为 `采购/跟单`。

4. 责任与跟进界面基础
   - 页面已有“责任与跟进”区域，适合作为钉钉待办的业务入口。

### 尚缺失

1. 钉钉待办发送 service
2. 待办投递日志表
3. 待办幂等规则
4. 待办关闭 / 更新规则
5. 定时升级提醒任务
6. 正式环境待办配置项

## 官方能力判断

根据钉钉开放平台官方文档，待办能力当前支持：

1. 创建工作待办
2. 更新待办
3. 删除待办
4. 查询用户待办

与本项目相关的关键点：

1. 创建待办时需要应用身份和用户身份，不能只知道姓名。
2. 待办通常需要可回跳的 `detailUrl`，跳回本系统详情页或看板页。
3. 如果要做闭环，流程状态变更后还要同步更新或关闭钉钉侧待办。

官方文档参考：

- [待办概述](https://open.dingtalk.com/document/development/dingtalk-todo-task-overview)
- [创建钉钉待办任务](https://open.dingtalk.com/document/development/add-dingtalk-to-do-task)
- [更新钉钉待办任务](https://open.dingtalk.com/document/development/updates-dingtalk-to-do-tasks)
- [删除钉钉待办任务](https://open.dingtalk.com/document/development/delete-dingtalk-to-do-tasks)
- [更新钉钉待办执行者状态](https://open.dingtalk.com/document/development/update-dingtalk-to-do-status)

## 正式环境建议新增的环境变量

下面这些变量建议作为**待办功能正式接入专用配置**。当前代码尚未消费它们。

```env
# 是否启用 OA 看板钉钉待办
DINGTALK_TODO_ENABLED=false

# 钉钉开放平台 API 应用配置（待办、审批等服务端调用）
DINGTALK_API_CLIENT_ID=
DINGTALK_API_CLIENT_SECRET=

# 钉钉网页登录使用独立 OAuth 应用配置，不与 API 应用混用
DINGTALK_LOGIN_CLIENT_ID=
DINGTALK_LOGIN_CLIENT_SECRET=
DINGTALK_CALLBACK_ORIGIN=

# 待办跳转回系统的基础地址
DINGTALK_TODO_DETAIL_BASE_URL=

# 用于构造钉钉待办来源标识 / 业务空间
DINGTALK_TODO_SOURCE_APP=oa-board

# 是否开启超时升级提醒
DINGTALK_TODO_ESCALATION_ENABLED=false

# 超时升级阈值（天）
DINGTALK_TODO_ESCALATION_DAYS=3
```

如果最终接入方案要求额外的应用标识，还可能需要：

```env
DINGTALK_AGENT_ID=
```

是否必须取决于最终选用的钉钉待办接口版本与应用类型。

## 建议新增的数据表

建议新增一张专门的待办投递表，避免把钉钉待办状态散落在 JSON 里。

建议表名：

- `oa_board_dingtalk_todo_dispatch`

用途：

1. 记录某个业务流程 / 阶段是否已创建钉钉待办
2. 保存钉钉待办 ID / 执行人 / 状态
3. 支持去重、重试、关闭、审计

SQL 草案见：

- `scripts/sql/create-oa-board-dingtalk-todo-dispatch-table.sql`

## 建议的发送时机

### 第一阶段：最小闭环

先只做一类待办：

1. 当流程进入新的“当前审批阶段”
2. 且解析出了唯一责任人
3. 且该阶段还没有有效待办
4. 则创建一条钉钉待办

建议首批接入阶段：

1. `产品设计-外观`
2. `产品设计-结构`
3. `产品生产-首单下单`
4. `限价-发起`

原因：

1. 这些阶段责任人相对清晰
2. 都已经有字段或规则可映射负责人
3. 业务价值高，适合先验证

### 第二阶段：关闭与更新

当以下任一情况发生时，同步钉钉待办：

1. 当前阶段变化
   - 关闭旧待办
   - 为新阶段责任人创建新待办

2. 流程完成 / 驳回 / 终止
   - 关闭对应待办

3. 负责人变更
   - 更新执行人，或关闭旧待办后重建

### 第三阶段：升级提醒

当流程满足以下条件时再发升级提醒：

1. 阶段超时
2. 原待办已创建
3. 距离上次提醒超过冷却时间
4. 升级接收人可解析

升级对象建议：

1. 当前负责人
2. 当前负责人上级
3. 商品企划 / 荆川 / 管理员可选兜底

## 负责人解析策略

待办发送目标不能只靠中文名，必须最终落到钉钉身份。

建议解析顺序：

1. 当前运行任务的 `userId`
   - 直接映射 `dingtalkUserId`

2. 表单中责任人字段
   - 如 `appearanceDesigner`、`structureDesigner`、`merchandiserOwner`、`pricingOwner`
   - 用姓名匹配本地用户 / 员工目录，取 `dingtalkUserId`

3. 阶段默认角色兜底
   - 例如 `采购/跟单`
   - 通过角色到成员名单的映射表进一步解析

如果一个阶段只能解析到“角色名”而不能解析到唯一员工，建议：

1. 不直接发待办
2. 记录 `NEEDS_OWNER_MAPPING`
3. 在看板中提示“负责人映射未完成”

## 需要新增的服务模块

建议至少拆成这几个文件：

1. `src/server/services/dingtalk-todo.service.ts`
   - 创建 / 更新 / 删除待办
   - 管理 app token

2. `src/server/services/oa-board-dingtalk-todo-dispatch.service.ts`
   - 负责业务规则
   - 判断是否该发待办
   - 生成 payload
   - 落库记录

3. `src/server/services/oa-board-owner-resolution.service.ts`
   - 负责将阶段负责人解析成钉钉用户

4. `scripts/sync-oa-board-todos.ts`
   - 用于定时补发、关闭、升级

## 需要新增的 API / 任务

### 后台任务

建议新增定时任务：

1. `sync:oa-board:todos`
   - 扫描当前有效流程
   - 创建缺失待办
   - 关闭失效待办
   - 触发升级提醒

### 管理接口

如有需要，可新增：

1. `POST /api/intake/oa-board/todo-dispatch/retry`
   - 手工重试失败待办

2. `GET /api/intake/oa-board/todo-dispatch`
   - 查看待办发送日志

## 幂等与重试建议

待办系统必须做幂等。

建议唯一业务键：

```text
board_key + stage_key + receiver_dingtalk_user_id
```

规则：

1. 同一个业务键，只允许存在 1 条 `OPEN / PENDING / RETRYING` 记录
2. 接口超时后不立即重发，先查日志状态
3. 网络失败按指数退避重试

## 正式环境能否“只配置就开”

最终判断：

1. **现在不能**
   - 因为缺少待办发送代码和日志表

2. **补完代码后可以**
   - 正式系统只需配置环境变量
   - 再开启定时任务即可

## 推荐落地顺序

### P1

1. 新增待办投递表
2. 新增 `dingtalk-todo.service.ts`
3. 先打通“创建待办”
4. 先只接 `产品生产-首单下单`

### P2

1. 接入更多阶段
2. 做关闭 / 更新逻辑
3. 做负责人映射异常日志

### P3

1. 做超时升级提醒
2. 做看板内待办发送状态可视化
3. 做手工重试与运维面板

## 建议的产品口径

为了降低误发风险，建议待办文案统一包含：

1. 开款编号
2. 当前阶段
3. 目标动作
4. 超时状态
5. 跳转链接

示例：

```text
【OA 新品流程看板】XP2026070900000291 已进入“产品生产-首单下单”，请尽快处理。
```