furniture-3d-system-Wu/furniture-3d-system/docs/架构设计/OA看板-钉钉待办接入方案-20260729.md

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. 如果要做闭环，流程状态变更后还要同步更新或关闭钉钉侧待办。

官方文档参考：

• 待办概述
• 创建钉钉待办任务
• 更新钉钉待办任务
• 删除钉钉待办任务
• 更新钉钉待办执行者状态

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

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

# 是否启用 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

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

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

   • 查看待办发送日志

幂等与重试建议

待办系统必须做幂等。

建议唯一业务键：

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. 跳转链接

示例：

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