Appearance
用户指南 13 · jeeflow-ui 流程中心（前端接入）
面向要把流程中心嵌进自己系统的集成方。后端只要实现了 规范 06 · 统一门面 的
/wf/**（40+ 个 action）， 前端不关心后端是 Java / Go / Python / Node / PHP。和 vben5-wf 的分工：付费版完整后台（Ant Design、低代码档案、设计器属性二开）走 mldong-vben5；本文是开源 通用流程中心， 无 Ant Design、无
/sys/*、选人/字典/上传由宿主注入。
npm 尚未发布
@mldong/jeeflow-ui 还没上 npm（包内版本仍为 0.1.0）。当前请：
- 体验：开源演示站
- 源码：github.com/mldong/jeeflow-ui（demo / embed 即下文两种接入的样板）
下文安装命令按发布后写法预留，发布前不要 npm add。
1. 当前能做到什么
| 能力 | 程度 | 说明 |
|---|---|---|
| 工作台 | ✅ | 待办/已办/我发起/抄送统计 + 最近待办 |
| 发起 / 待办 / 已办 / 我发起 / 抄送 / 委托 | ✅ | 对齐 vben5-wf 流程中心 8 菜单（不含档案） |
| 发起抽屉 | ✅ | Tab：表单 / 流程图；选人、抄送、理由、附件（流程 JSON 开关） |
| 办理抽屉 | ✅ | Tab：详情 / 流程图 / 审批记录；actionBtns 分流；字段权限编辑；转办/加签 |
| 实例详情 | ✅ | 同上三 Tab；撤回 / 抄送 / 重新提交 |
| Schema 表单 | ✅ | __schema__.columns：Input/Textarea/Select/数字/日期；ApiDict/Upload 走 adapters |
| 字段权限 | ✅ | PERMISSION_f_* 优先，1 只读 / 2 可编 / 3 隐藏 |
| 自定义业务表单 | ✅ | registerForm(formKey, 组件)，未注册则走内置 SchemaForm |
| 流程图高亮 + 处理人回显 | ✅ | highLight / getAssigneeTextData |
| 流程定义列表 | ✅ | 详情抽屉看图；启停 / 删除 |
| 流程设计 | ⚠️ 画布级 | 钉钉设计器画图、保存草稿、发布、导入 JSON；没有 vben5 那套字段权限/按钮/schema 属性面板 |
| 选人 | ✅ | 办理候选走引擎 candidatePage；抄送/转办/委托走 adapters.listUsers |
| 权限码显隐 | ✅ | hasPermission(['wf:processTask:todoList'])，不传则全放行 |
| 流程档案 / 低代码表 | ❌ | 业务能力，不进 jeeflow-ui |
| 设计器 TaskDrawer 二开 | ❌ | 留给 vben5-wf；复杂配置用导入 JSON |
运行时已经能执行字段权限、操作按钮、__schema__（从已发布 JSON 读出）； 只是不能在画布里点出来——用设计页「导入 JSON」或在 vben5-wf 里设计后导出。
2. 三种接入方式（由轻到重）
① 直接用演示站 无需集成，给客户看引擎
② iframe 壳 异栈（若依等）：嵌一页流程中心
③ Vue 组件包 同栈 Vue3：整页嵌入或拆抽屉/页面2.1 演示站
jeeflow-demo.mldong.com —— 六语言后端切换，源码 jeeflow-ui/apps/demo。
2.2 iframe（异栈）
源码样板：apps/embed（壳）+ apps/embed/public/host.html（宿主）。
宿主 → 壳（URL 或 postMessage，后者可热更新）：
| 通道 | 字段 |
|---|---|
| URL | ?token=&backend=&operator=&theme=&site=&logo= |
jeeflow:init | token / backend / operator / theme: { primary, siteName, logo } |
jeeflow:setOperator | operator |
壳 → 宿主：
| type | 时机 |
|---|---|
jeeflow:ready | 壳挂载完成 |
jeeflow:event | 发起 / 办理 / 撤回（event + action + operator） |
jeeflow:todo-count | 待办数（首取 + 轮询） |
选人等 adapters 在 embed 壳进程里注入（壳自己 createJeeflowUi），不要让 ui-kit 去打宿主 /sys/user/select。需要搜人时，壳把 listUsers 做成对父页的 postMessage RPC 即可。
2.3 Vue 组件包（同栈，发布后）
bash
pnpm add @mldong/jeeflow-ui vue mldong-flow-designer-dingtalkvue 与 mldong-flow-designer-dingtalk 是 peer（设计器/预览画布用钉钉包）。
ts
import { createApp } from 'vue'
import { createJeeflowUi, JeeflowUiKey, JfLayout } from '@mldong/jeeflow-ui'
import '@mldong/jeeflow-ui/dist/jeeflow-ui.css' // 若构建拆出独立 css，按实际文件名
const jeeflowUi = createJeeflowUi({
baseUrl: () => '/api', // 门面根，请求打到 {baseUrl}/wf/{action}
getOperator: () => store.userId, // 当前用户 → 门面 operator
getToken: () => store.token, // 可选，Authorization: Bearer
hasPermission: (codes) => hasAny(codes),
adapters: {
listUsers: (kw, ctx) => sysUserSelect(kw),
getUsersByIds: (ids) => sysUserByIds(ids),
getDict: (code) => dictApi(code),
upload: (file) => oss.put(file),
},
})
jeeflowUi.registerForm('leave-form', LeaveForm)
createApp(App).provide(JeeflowUiKey, jeeflowUi).mount('#app')也可包一层 <JeeflowUiProvider :config="...">，效果相同。
3. 整页流程中心（推荐默认）
对齐 vben5-wf 的 8 个流程菜单 + 工作台，宿主只提供壳（登录 / 顶栏）：
vue
<script setup>
import {
JfLayout,
JfWorkbenchPage, JfApplyListPage, JfTodoPage, JfDonePage,
JfMyInstancePage, JfCcListPage, JfProcessDefinePage,
JfProcessDesignPage, JfSurrogatePage,
} from '@mldong/jeeflow-ui'
const menus = [
{ key: 'workbench', title: '工作台', icon: 'home', component: JfWorkbenchPage },
{ key: 'apply', title: '发起申请', icon: 'apply', component: JfApplyListPage },
{ key: 'todo', title: '我的待办', icon: 'todo', component: JfTodoPage },
{ key: 'done', title: '我的已办', icon: 'done', component: JfDonePage },
{ key: 'mine', title: '我发起的', icon: 'mine', component: JfMyInstancePage },
{ key: 'cc', title: '我的抄送', icon: 'cc', component: JfCcListPage },
{ key: 'define', title: '流程定义', icon: 'define', component: JfProcessDefinePage },
{ key: 'design', title: '流程设计', icon: 'design', component: JfProcessDesignPage },
{ key: 'surrogate', title: '我的委托', icon: 'surrogate', component: JfSurrogatePage },
]
</script>完整拼菜单见演示站 apps/demo/src/App.vue。按钮显隐跟 hasPermission 的 wf:{action} 权限码。
白标：覆盖 CSS 变量即可（--jf-primary、--jf-header-bg 等），不必改组件。
4. 拆着用（只要办理抽屉 / 只要 API）
ts
import { useJeeflowUi, JfApproveDrawer, JfStartDrawer, SubmitType } from '@mldong/jeeflow-ui'
const { api, can } = useJeeflowUi()
const todos = await api.processTask.todoList({ pageNum: 1, pageSize: 10 })
await api.processTask.execute(taskId, SubmitType.AGREE, { tf_approvalComment: '同意' })页面、抽屉、JfUserPicker / JfFlowViewer / JfApprovalRecord 均可单独挂到宿主路由。 必须包在 createJeeflowUi / JeeflowUiProvider 里。
5. 宿主 adapters（不要写死 /sys）
ui-kit 不调用宿主 REST。缺哪个 adapter，对应控件降级。
| adapter | 用途 | 不传时 |
|---|---|---|
listUsers(keyword, ctx) | 抄送 / 转办 / 委托 / 指定下一处理人 | 提示注入 |
getUsersByIds(ids) | 已选 chips 回显姓名 | 显示 userId |
listRoles(keyword) | 预留给设计器按角色指派 | 目前设计器薄面板未做，注入了也暂不消费 |
getDict(code) | SchemaForm ApiDict | 空下拉 |
upload(file) | 发起附件 / SchemaForm Upload | 只存文件名 |
选人优先级：scene=candidate 且有 taskId → 门面 processTask/candidatePage； 否则 adapters.listUsers。流程 JSON 里的 selectUserApi 只作为 ctx.apiHint，ui-kit 不直接 fetch。
ts
adapters: {
listUsers: async (keyword, ctx) => {
// ctx.scene: candidate | nextOperator | cc | surrogate | assignee
const rows = await myUserApi.search(keyword)
return rows.map((u) => ({
userId: String(u.id),
realName: u.name,
deptName: u.deptName,
}))
},
}6. 业务表单
ts
jeeflowUi.registerForm('leave-form', LeaveForm)组件约定：modelValue（f_ 字段）+ defineId / instanceId；办理页另有 task。 节点 properties.form 对上 formKey 即用该组件；对不上（或 SchemaWfForm）走内置 SchemaForm。
7. 设计器：够演示，不替代 vben5
JfProcessDesignPage 能：钉钉风画布、保存/发布、导入 LogicFlow JSON。
不能：在属性面板里配字段权限、操作按钮、可视化 schema——这些运行时认 JSON， 作者侧用「导入 JSON」或到 vben5-wf 设计。设计器扩展见 指南 12（那是 mldong-flow-designer-plus 的二开，不是本包）。
8. 后端前提
| 项 | 要求 |
|---|---|
| 门面 | POST {baseUrl}/wf/{action}，{code,msg,data}，code=0 成功 |
| operator | 前端 getOperator() 自动写入；后端也可覆盖 |
| 扩展仓储 | 流程设计 / 委托需要 IProcessExtRepository；纯内存 demo 已带 |
| CORS | 前后端不同源时放行 |
非 mldong 框架（若依等）先按 指南 10 §6 做转发 controller，再选 iframe 或 Vue 包。
9. 相关
- 源码：jeeflow-ui
- 门面契约：规范 06
- 流程 JSON 配置项：规范 02
- 后端接入：指南 10
- 设计器生命周期：指南 11