审批接入（钉钉 / 企业微信）

系统支持三种审批方式：

| 方式 | 说明 | 适合 | |---|---|---| | 站内审批 | 后台直接点通过/驳回 | 不依赖第三方，最简单 | | 钉钉审批 | 推送到钉钉，领导手机审批 | 用钉钉的协会 | | 企业微信审批 | 推送到企微，领导手机审批 | 用企微的协会 |

没配置时自动降级为站内审批，不影响使用。

一、站内审批

不需要任何配置。用印、合同、公文发起后，审批人在后台 → 审批 → 待审批 点通过/驳回。

二、钉钉审批接入

1. 钉钉后台准备

1. 钉钉开放平台 → 创建应用 → 拿到 AppKey / AppSecret
2. 记下 CorpId、AgentId
3. 创建审批模板 → 拿到 processCode

2. 系统配置

后台 → 审批 → 审批设置 → 钉钉设置：

| 字段 | 填什么 | |---|---| | AppKey | 应用 Key | | AppSecret | 应用密钥 | | AgentId | 应用 AgentId | | CorpId | 企业 ID | | AES Key | 回调验签用 |

点「测试钉钉」验证。

3. 回调地址

把系统里的回调地址填到钉钉开放平台「事件订阅」：

https://你的域名/api/approval/dingtalk/callback

三、企业微信审批接入

1. 企微后台准备

1. 企业微信管理后台 → 应用管理 → 创建自建应用
2. 拿到 AgentId 和 Secret
3. 记下 CorpId（我的企业 → 企业信息）
4. 创建 3 个审批模板（用印/合同/通用文件）→ 拿到 template_id
5. 记录每个模板的控件 ID（在模板编辑页能看到 Text-1 这种）

2. 系统配置

后台 → 审批 → 审批设置 → 企业微信设置（右侧卡片）：

| 字段 | 填什么 | |---|---| | 企业 ID（corpid） | 企业微信 CorpId | | 应用 AgentId | 自建应用 AgentId | | 应用 Secret | 自建应用 Secret | | 用印/合同/通用模板 ID | 3 个模板 ID | | 默认审批人 userid | 审批人的企微账号（逗号分隔） | | 回调 Token / AESKey | 企微后台生成 |

点「测试企业微信」验证。

3. 配置接收消息

企业微信后台 → 你的应用 → 接收消息 → 设置 API 接收：

URL:    https://你的域名/api/approval/wecom/callback
Token:  （系统里生成的 Token）
AESKey: （系统里生成的 32 位 Key）

保存时企业微信会校验，系统自动回显。

4. 企业可信 IP

企微后台 → 你的应用 → 企业可信 IP → 填服务器 IP。

不填的话，所有审批 API 会报 60020 not allow to access from your ip。

5. 重要限制

⚠️ 企业微信不支持后台代审批：

后台点「通过」只更新本系统，企微里的审批卡片仍显示「审批中」。 所以后台处理完，要提醒审批人在企微里手动忽略那条审批。

四、审批模板映射

后台 → 审批 → 审批设置 → 审批模板：

每个模板要配：

• 通道（钉钉/企微）
• 钉钉 processCode
• 企微 template_id
• 企微控件映射（JSON）：

{
  "title": "Text-1",
  "content": "Text-2",
  "file": "File-3"
}

控件 ID 在企业微信模板编辑页能看到（每个控件右下角）。

五、回调兜底

回调可能丢失（网络/企微重试有限），系统有定时同步：

*/5 * * * * php artisan approval:sync-wecom

每 5 分钟拉一次审批状态，保证最终一致。

六、常见问题

| 问题 | 排查 | |---|---| | 60020 IP 不在白名单 | 配企业可信 IP | | 301025 发起人=审批人 | 换一个审批人，或换发起人 | | 301004 模板不存在 | template_id 填错 | | 回调不生效 | 检查接收消息 URL/Token/AESKey | | 审批状态不同步 | 手动跑 approval:sync-wecom |

下一篇：组织信息与年检