# Forge-Admin 可行性分析（企微集成 / OA / 工作流集成）

> 分析对象：https://gitee.com/ForgeLab/forge-admin （产品文档 http://www.dlforgelab.com:8084/forge-docs/）
> 分析人：产品通　|　适用：母婴公司信息部选型评估　|　本文档用于与官方确认功能支持范围

## 0. 项目定位速览

- **是什么**：AI+企业级低代码中后台框架，Spring Boot 3.x + JDK 17 / Vue 3，微内核插件化架构。
- **核心内置能力**：系统管理（RBAC/部门/岗位/菜单/多租户）、Flowable 工作流、消息推送（站内信/短信）、社交登录（JustAuth 18+ 平台）、WebSocket 实时推送、AI 智能体/代码生成、大屏报表。
- **⚠️ 关键背景**：流程引擎目前仍在完善中。官方《流程管理模块自研设计方案》自述成熟度——动态表单设计 20%、流程条件设置 30%、审批节点配置 40%、组织架构集成 50%。即"基础审批可跑，高级流程能力在路线图"。

---

## 1. 企微集成（身份登录 / 通讯录同步 / 消息待办）

**结论：⚠️ 三个子项 —— 身份登录开箱可用，通讯录同步与消息/待办需官方支持实现（其中通讯录同步应最优先）**

| 子项 | 判定 | 说明 |
|------|------|------|
| 企微身份登录 | ✅ 开箱支持 | `forge-starter-social` 基于 JustAuth，原生支持 **企业微信 `WECHAT_ENTERPRISE`**、微信、钉钉、飞书等 18+ 平台；可扫码/授权登录，自动注册并绑定本地用户（`sys_user_social`）。 |
| 通讯录同步 | ⚠️ 需官方支持 | 当前无内置"从企微拉取通讯录"功能。社交登录的 `WECHAT_ENTERPRISE` 仅做"授权登录 → 自动建当前登录者账号"（`autoRegister`），拉取的是**单个登录用户**资料（uuid/昵称/头像/邮箱），**不全量拉取部门树 + 全员**（源码树无 `sync`/`contact`/企微部门同步模块）。需官方提供同步能力：调企微"通讯录管理"API（需单独 secret + 通讯录权限，异于登录用的 agentId）→ 写 forge 部门/用户表 → 建立 企微 userid ↔ forge userid 映射。**同步范围含标签**：标签走独立接口 `tag/list`（标签列表）+ `tag/get`（标签下成员/部门），**不是成员 `user/get` 的字段**；反向"某用户属于哪些标签"需遍历所有标签或自行维护 `userid → tags` 映射。系统自身的部门/用户/岗位（RBAC）可手工维护。 |
| 消息推送到企微 | ⚠️ 需官方支持 | 消息模块（`forge-starter-message`）默认仅 `web`(站内信) + `sms`(短信) 两个渠道，但 `MessageChannel` 接口可插拔。需官方提供 `WeComMessageChannel`，调用企微自建应用"发送应用消息"API（文本/卡片）。 |
| 待办进企微 | ⚠️ 需官方支持 | 当前无内置企微待办。需官方提供桥接能力：`forge 待办(sys_flow_task)` → 企微消息卡片 → 用户点击/回调 → forge 处理审批。依赖企微自建应用 + 公网可达回调 URL + access_token 管理。 |

**前置条件与风险**
- 需要企业微信管理员权限、自建应用、消息/通讯录 API 权限、可信 IP/域名（我方具备）。
- 企微回调需**公网可达**的 URL（内网系统要打通需做反向代理/中间件，我方具备）。
- 消息有频率限制；企微用户身份与 forge 本地用户需做 `userid` 映射（我方已有现成ERP用户与企微身份映射(不带部门信息)，是否可以导入或直接读取）。
- 项目当前未内置企微 JSSDK / 通讯录同步 / 待办 SDK，以上均需官方支持提供。
- **仅登录建号不带部门/岗位**：仅靠企微登录，只有"登录过的人"进系统且不含部门岗位，新员工不会自动建档，审批的"上级领导 / 部门负责人"无法自动解析（与 `getDeptManager`/`getUserDept` 需本地组织数据的前提冲突）。故需优先确认官方对**通讯录同步**的支持，作为 OA 审批的前置依赖。
- **通讯录同步范围确认（含标签）**：同步对象为 **部门 + 成员 + 标签**（标签指通讯录-标签管理里的成员标签）。标签走企微独立接口 `tag/list` + `tag/get`，**非成员 `user/get` 字段**；反向"用户 → 标签"需遍历标签或自建 `userid → tags` 映射。标签会增加同步任务的接口调用与映射复杂度，但企微已提供完整接口，技术上可行，已纳入需官方支持的范围。

---

## 2. 用本项目实现 OA

**结论：✅ 高度可行，是项目主打场景之一**

- **证据**：官方明确把"审批流业务系统（请假/采购/合同/报销/工单）"列为适合场景；内置 RBAC、部门/岗位、Flowable 审批（待办/已办/审批/驳回/转办/抄送）、消息通知、移动端 H5（工作台/消息中心/流程待办/审批）。
- **开箱即得的基础 OA**：用户/组织/权限、流程发起与审批、站内通知、移动端处理闭环。
- **需官方支持补强的部分**（按官方自评成熟度）：动态表单 20%、复杂条件分支 30%、层级/会签审批 40%、组织深度集成 50%；公文/印章/会议/资产等具体 OA 模块需官方支持搭建或确认路线图规划。
- **风险**：项目偏新，工作流高级能力在路线图；生产落地前需评估社区活跃度、开源 License、安全合规与官方运维/技术支持能力。

---

## 3. 工作流调用外部 API / 对外提供 API

**结论：✅ 可行，架构上对集成友好**

- **对外提供 API（被其他系统调用）✅**
  - `forge-flow` 是**独立流程服务**（`forge-flow/`），自带 REST 控制器（FlowModel / FlowTask / FlowInstance），任意系统可 HTTP 调用（启动流程 / 查询待办 / 审批）。
  - 更优：提供 **`forge-flow-client` Spring Boot Starter**，其他 Java 系统引入即用 `FlowClient`（`startProcess` / `approve` / `getTodoTasks`）与 `@FlowStart` / `@FlowCallback` 注解驱动；流程事件经 **Redis Pub/Sub** 回调。
- **调用外部系统 API ✅（需官方支持实现）**
  - Flowable 原生支持 **Service Task（Java Delegate）、HTTP Task、TaskListener**（官方示例 `TaskCreateListener`）。可在节点中调用外部 REST。
  - 但当前 BPMN 设计器仅 50%、"外部调用节点"的可视化配置尚不成熟，目前更依赖官方在 Java 层提供的 Service Task / Listener 能力，而非纯 UI 拖拽。
- **其他互通机制**：API 配置模块（自动注册 Controller 到 DB、两级缓存、实时刷新）、多数据源、AI 智能体 MCP 工具扩展，均可用于系统互通。

---

## 4. 综合建议与落地路径

**总体判断**：作为「OA 底座 + 多系统集成中枢」是合理选型——技术栈主流、能力覆盖到位、流程引擎对外暴露为独立服务，对集成很友好。

**建议路径（能力侧依赖官方提供的范围）**
1. **先确认企微侧**：我方是否已有企业微信、自建应用权限、能否开放 API 与公网回调（已确认具备）。
2. **MVP（基础审批 OA + 企微身份）**：用社交登录接企微身份（官方开箱能力）；Flowable 跑请假/报销；站内信 + 移动端 H5 做内部通知（官方开箱能力）。
3. **二期（企微消息/待办桥接）**：由官方提供 `MessageChannel`(企微) + 待办回调能力。
4. **多系统集成**：用 `forge-flow-client` 让其他系统发起/认领流程（官方能力）；用 Flowable Service Task / HTTP Task 在工作流中调外部 API（官方能力）；API 配置模块做接口治理（官方能力）。

**已澄清信息（用户确认，2026-07-26）**
- 企微：已有企业号，可开自建应用 + 公网回调。
- 其他系统：非 Java / Spring Boot；对外提供 API，或允许 forge 直连其数据库。
- 统一身份 / SSO：当前没有。
- OA 复杂度：需要**复杂表单 + 层级会签**。
- 开源协议 / 官方支持模式：待确认（建议立项前核实 License 与官方技术支持方式）。

---

## 5. 页面自适应专项（PC 表单在移动端能否自适应）

**结论：❌ 开箱不能自适应；PC 表单在手机上需官方支持实现**

- **技术事实**：前端管理端基于 **Vue 3 + Naive UI（桌面组件库）**。`AiForm` 组件虽有 `gridCols`（栅格列数，默认 1）与字段 `span` 占位，但文档未提供响应式断点——它是**固定列数栅格**，不会随屏幕宽度自动重排。`FormDesigner` / `FormPreview` 同样基于 naive-ui。
- **架构是双端分离**：移动端是**另一套独立的 uni-app 3 + Vue 3 H5**（提供工作台 / 消息中心 / 流程待办 / 审批页），并不是把 PC 管理页面做响应式自适应。手机上打开 PC 表单会出现字段挤压、下拉/日期选择器触摸体验差、布局横向溢出等问题。
- **对"复杂表单"的影响**：你明确要复杂表单，而动态表单引擎官方自评仅 20% 成熟度，且文档未体现移动端 H5 复用同一份表单 Schema 做移动渲染。因此——**复杂 PC 表单在手机上基本需要由官方支持实现移动端表单**。

**落地建议（依赖官方支持的范围）**
- **MVP**：移动端只做"审批动作"（通过 / 驳回 + 简单意见，官方 H5 已具备），复杂表单填写留在 PC 端完成。
- **二期（推荐，需官方支持）**：采用 **Schema 驱动 + 双渲染器**——PC 用 Naive UI 渲染，移动端用 uni-app / Vant 按同一份 JSON Schema 渲染；或在 `AiForm` 层接入 Naive UI 响应式栅格（`NGrid` 的 `cols="1 s:2 m:3"`）+ viewport 适配，实现一套 Schema 跨端。
- 若要求"PC 一套表单、移动端自动好看"，需官方支持实现，非框架当前自带能力。

---

## 6. 按澄清修正的关键结论

**6.1 多系统集成方式（其他系统非 Java）**
- **其他系统调用 forge**：`forge-flow` 暴露的是标准 **REST API**，非 Java 系统直接 HTTP 调用即可（启动流程 / 查询待办 / 审批），**无需依赖仅限 Java 的 `forge-flow-client` Starter**。
- **其他系统读取 forge 数据**：可直连 forge 的 MySQL（如 `sys_flow_task` 待办表），但属库级耦合，建议优先走 REST / Redis 事件订阅。
- **forge 调用其他系统**：Flowable `Service Task` / `HTTP Task` / `TaskListener` 调用对方 REST API（对方既已提供 API，这条最顺）。

**6.2 无 SSO → 企微身份成为统一身份抓手**
- 既然没有统一身份，正好用社交登录的 `WECHAT_ENTERPRISE` 作为统一入口，把 **企微 userid ↔ forge 账号 ↔ 其他系统账号** 做映射；forge 可作为身份中枢向其他系统透传身份，避免各系统各自登录。

**6.3 复杂表单 + 层级会签是主要依赖官方支持的部分（P0 优先级）**
- 这恰是官方自评成熟度最低的区域：**动态表单 20% / 流程条件 30% / 审批节点 40%**。可行，但需重点依赖官方支持，建议列为 P0 优先级，并同步评估"等待官方补强"还是"由官方提供定制开发"，这直接关系到项目周期与风险。

---

## 7. 与企微审批的能力缺口对比（需厂家支持项）

> 以下为我方当前企微审批系统的 11 项能力缺口。逐条对照 forge-admin 文档能力判定支持情况；**不支持、或仅底层引擎可行但缺配置层的，统一纳入"需厂家支持"清单。**

| # | 我方缺口（企微审批不支持） | forge-admin 支持情况 | 判定 |
|---|--------------------------|---------------------|------|
| 1 | 基础控件，无布局控件 | `AiForm` 支持栅格（`gridCols`/`span`），Naive UI 含布局组件 | 部分支持；复杂布局控件需与厂家确认 |
| 2 | 明细控件，不支持行内关联 | 动态表单引擎官方自评仅 20%，明细/子表控件尚不成熟 | **需厂家支持/确认** |
| 3 | 不支持跨表数据关联；明细内不支持关联控件 | 当前未见跨表/关联型表单控件（非原生关系型表单能力） | **需厂家支持** |
| 4 | 不支持字段级权限；节点填写值无法作流转条件 | ① 仅有 `datascope` 数据范围（行级/部门级），字段级权限未见；② 流转条件：Flowable 支持"流程变量 + 网关条件"（技术上可行），但条件可视化配置成熟度仅 30% | ① **需厂家支持**；② 底层支持，可视化配置**需厂家支持** |
| 5 | 不支持自定义页面 | 支持通过代码新增页面（菜单/路由），但可视化"页面搭建器"未见 | **需厂家支持/确认** |
| 6 | 仅必填校验，不支持自定义校验 | 动态表单成熟度 20%，自定义校验规则能力待确认 | **需厂家支持** |
| 7 | 数据仅审批留存，无业务台账/报表 | 内置"大屏报表"+多数据源，但表单数据→业务台账/报表的自动贯通待确认 | 部分支持；数据贯通**需厂家支持** |
| 8 | 不支持自由流程；不支持子流程 | ① 自由流程（任意跳转）非 Flowable BPMN 原生；② 子流程为 Flowable 原生能力 | ① **需厂家支持**；② 支持（Flowable 原生） |
| 9 | 不支持退回到指定节点 | Flowable 技术上可行（任意节点跳转），但界面暴露程度取决于审批节点配置（成熟度 40%） | 底层支持；界面完整实现**需厂家支持** |
| 10 | 不支持节点触发数据操作（如自动更新关联表） | Flowable `Service Task`/`HTTP Task`/`TaskListener` 可触发外部 API 或数据操作 | 支持（Flowable）；可视化配置**需厂家支持** |
| 11 | 无流程测试/模拟（需模拟标签/人员测各节点） | 文档未见流程模拟/测试功能 | **需厂家支持** |

### 需厂家支持 consolidated 清单（forge 当前不支持 / 仅引擎层可行缺配置）
- 明细控件的行内关联能力
- 跨表数据关联、明细内关联控件
- 字段级权限
- 节点填写值作为流转条件的**可视化配置**
- 可视化自定义校验规则
- 可视化自定义页面（页面搭建器）
- 自由流程（任意跳转 / 指定审批人）
- 表单数据 → 业务台账 / 报表的自动贯通
- 退回到指定节点的**界面完整实现**
- 节点触发数据操作的**可视化配置**
- 流程测试 / 模拟（按标签、人员模拟各节点）

> 说明：表中"支持（Flowable 原生）"的项（子流程、节点触发数据操作、退回到指定节点、节点值作流转条件）底层引擎能力具备，但当前 BPMN 设计器成熟度 30%~50%，**易用化/可视化配置仍需厂家支持**，对业务人员自主配置不友好。

---

### 证据来源（已读取）
- Gitee 项目 README（定位、技术栈、功能模块、适合场景）
- 产品文档 `backend/modules/social.md`（社交登录含 WECHAT_ENTERPRISE）
- 产品文档 `backend/modules/message.md`（MessageChannel 可插拔、web/sms 渠道）
- 产品文档 `backend/modules/api-config.md`（API 自动注册/缓存/刷新）
- 产品文档 `backend/modules/flow-client.md`（FlowClient / @FlowStart / @FlowCallback / Redis Pub-Sub）
- 产品文档 `backend/modules/flow-design.md`（Flowable 架构与功能成熟度自评）
- 产品文档 `backend/modules/websocket.md`（实时推送）
- 前端文档 `frontend/components/overview.md`、`form-designer.md`、`ai-form.md`（Vue3 + Naive UI、AiForm 固定栅格、FormDesigner 基于 naive-ui、移动端为独立 uni-app H5）