企业协同
企业协同是 Forge Admin 对接企业 IM / OA 平台的统一入口，支持企业微信、钉钉、飞书等多平台，在一处完成「连接配置、通讯录同步、身份匹配、待办推送、消息投递」的闭环管理。
后端能力由 forge-plugin-collaboration（业务插件）与 forge-starter-collaboration（技术 Starter）提供。当前深度适配企业微信：接入 Access Token 管理、回调加解密、通讯录连接器，并支持工作台免登与待办卡片推送。
功能入口
登录管理后台后，点击左侧菜单 企业协同，进入连接管理页面。
页面结构
企业协同页面顶部由以下页签组成：
| 页签 | 作用 |
|---|---|
| 配置指南 | 各平台的接入前置说明与配置步骤引导 |
| 连接管理 | 新建、查看、编辑各平台的协同连接 |
| 同步批次 | 通讯录 / 标签同步任务的批次与结果记录 |
| 问题单 | 同步失败、映射异常等问题的汇总与处理 |
| 映射查询 | 企业侧部门 / 成员与系统组织 / 用户的映射关系查询 |
| 投递记录 | 消息 / 待办卡片投递的发送记录与状态 |
| 回调事件 | 平台回调事件的接收与处理记录 |
连接管理列表
连接列表展示当前已配置的协同连接，字段如下：
| 列 | 说明 |
|---|---|
| 平台 | 企业微信 / 钉钉 / 飞书等 |
| 连接名称 | 连接的显示名称，如「企业微信」 |
| 企业 ID | 平台侧的企业标识（CorpID） |
| 身份策略 | 平台成员与系统账号的匹配方式（如「自动创建用户」「仅绑定已有用户」） |
| 目录来源 | 通讯录目录的权威来源（如「外部权威」「不同步」） |
| 状态 | 正常 / 停用 |
| 创建时间 | 连接创建时间 |
支持按 平台 / 连接名称 / 状态 筛选，行内提供「详情 / 编辑 / 更多」操作。
新建连接
点击 新建连接，按分组填写配置：
1. 基础信息
| 字段 | 必填 | 说明 |
|---|---|---|
| 平台 | 是 | 选择企业微信 / 钉钉 / 飞书等 |
| 平台显示名称 | 是 | 页面展示名称，如「企业微信」 |
| 平台 Logo | 否 | 上传图片（≤2MB，png/jpg/jpeg/webp/gif） |
| 连接编码 | 否 | 留空自动生成，如 wecom-a1b2 |
| 连接名称 | 是 | 如「XX 科技企业微信」 |
| 外部企业 ID | 条件 | 企业型平台必填，纯登录平台可留空 |
| 连接类型 | 是 | 企业自建 |
2. 目录与身份
| 字段 | 必填 | 说明 |
|---|---|---|
| 身份匹配策略 | 是 | 平台成员与系统账号的匹配方式（自动创建用户 / 仅绑定已有用户等） |
| 默认角色 | 否 | 自动建号时分配的默认角色（可多选），为空走全局配置 |
| 目录权威来源 | 是 | 通讯录目录的权威来源（不同步 / 外部权威等） |
| 默认挂载组织 ID | 否 | 目录同步的根组织 ID |
| API 基础地址 | 否 | 留空使用平台官方地址，私有化部署可自定义 |
3. 客户端免登
| 字段 | 说明 |
|---|---|
| 工作台免登 | 开启后，用户在平台工作台内免密跳转进入系统（由后端连接配置 sso_workbench_enabled 驱动） |
4. 待办推送
| 字段 | 说明 |
|---|---|
| 待办卡片推送 | 开启后，流程待办以卡片形式推送到平台工作台 |
| 待办 H5 访问地址 | 开启推送时必填，如 https://h5.example.com/forge-h5（无需带 #/） |
5. 定时同步
| 字段 | 说明 |
|---|---|
| 定时目录同步 | 开启后按 Cron 周期自动同步通讯录 |
| 同步周期 (Cron) | 如 0 0 2 * * ?（每天凌晨 2 点） |
填写完成后点击 确定 保存。
通讯录同步
连接保存后，可在 连接管理 行内操作或 同步批次 页签触发通讯录同步：
- 系统拉取平台侧的部门结构与成员信息。
- 按「身份匹配策略」与「目录权威来源」完成组织 / 用户映射。
- 同步结果写入 同步批次：可查看新增、更新、失败数量与状态。
- 支持手动触发与定时自动同步（见上节 Cron）。
待办推送与消息投递
- 流程产生待办后，系统可按连接配置将待办卡片推送到平台工作台。
- 用户点击卡片后，通过「待办 H5 访问地址」进入移动端审批页面处理。
- 投递结果可在 投递记录 页签查看；平台侧回调可在 回调事件 页签查看。
注意事项
- 企业微信自建应用需先在企业微信管理后台获取 企业 ID（CorpID） 与 应用 Secret，并配置可信 IP 与回调 URL。
- 回调 URL 必须是公网可访问地址，平台才能推送回调事件。
- 应用 Secret 等敏感凭据保存后脱敏显示，禁止明文落库或打印到日志。
- 通讯录同步建议在业务低峰期执行，首次同步前确认平台侧组织架构已完善。
- 身份匹配策略选择「自动创建用户」时，请先确认默认角色配置，避免新账号权限异常。