docs(plan): 在线流程Modeler(B3)实施计划——4阶段TDD任务
基于 06-26 design(D1-D9)+三路事实勘探(语料/后端/前端)合成: - §0 事实基线:1512真实BPMN扩展面实测(11属性/5元素/中文key会签流)+后端(deploy无审计/sanitize单向/Model API零使用/网关超管判定现成)+前端(bpmn-js17已装/属性面板缺/admin门与测试范本) - §0.5 计划级决策P1-P6:moddle自建vendored+语料双门/影响摘要节点级diff/3模板/草稿admin共见/EIP4控件走React侧板非preact/全量保真扫描做工具不进CI - 阶段1 moddle保真+只读载入/阶段2 三控件+草稿/阶段3 发布门(校验+超管+同人确认+审计V4+id还原)/阶段4 新建+live e2e - 验收清单8项+红线提醒(databaseSchemaUpdate=false/保真层不改/JDK解析器/部署门只落网关) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
@@ -78,7 +78,8 @@
|
||||
| `plans/2026-06-25-A10-生产上线工程化-design.md` | A10 生产化 design(D1-D6 待拍板;W1-W4 骨架已合 main) |
|
||||
| `plans/2026-06-25-报表迁移-JOR引擎重宿主-design.md` | 报表 A3 设计(Phase1-3 已完成 + 安全收口,总览 §11) |
|
||||
| `plans/2026-06-25-审批闭环-实施计划.md` | 审批闭环 P0-P3(已实施合 main `c95eaee`,剩外部前置) |
|
||||
| `plans/2026-06-26-在线流程Modeler-design.md` | B3 流程 Modeler 设计(D1-D9 拍定,下一步 plan→实现) |
|
||||
| `plans/2026-06-26-在线流程Modeler-design.md` | B3 流程 Modeler 设计(D1-D9 拍定) |
|
||||
| `plans/2026-07-02-在线流程Modeler-实施计划.md` | B3 实施计划(4 阶段 TDD 任务,含语料/代码勘探基线 + P1-P6 计划级决策,**执行中**) |
|
||||
| `AI_AGENT_AUTO_DEVELOPMENT.md` + `AI_AGENT_PAGE_BLUEPRINT_CONTRACT.md` / `AI_AGENT_REPAIR_CONTRACT.md` / `AI_AGENT_Nocobase_ADOPTION_PLAN.md` + `skills/` | AI Agent 对外口径红线 + 编译/修复/采纳契约 + Skills 目录 |
|
||||
| `framework定制视图-TODO-2026-06-17.md` | A 兼容线**活清单**(Done/In-Progress/待验三态),每次修完回写 |
|
||||
| `framework定制视图-engineclass移植backlog-2026-06-17.md` | 46 framework 视图迁移**主 backlog**(verdict/移植项/优先级) |
|
||||
|
||||
340
docs/plans/2026-07-02-在线流程Modeler-实施计划.md
Normal file
340
docs/plans/2026-07-02-在线流程Modeler-实施计划.md
Normal file
@@ -0,0 +1,340 @@
|
||||
# 在线流程 Modeler(B3)实施计划
|
||||
|
||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||||
>
|
||||
> 设计权威:`2026-06-26-在线流程Modeler-design.md`(D1-D9 已拍定)。本计划把 design 落成 TDD 任务,
|
||||
> 每阶段独立可验、可 `--no-ff` 合 main。执行分支:platform `feat/process-modeler` / web `feat/process-modeler`。
|
||||
|
||||
**Goal:** 在既有 bpmn-js 流程图查看器之上交付可编辑 BPMN 流程设计器——1512 个存量真实流程可在线改(key 不变),新流程可从空白/模板建并部署,activiti 扩展零丢失。
|
||||
|
||||
**Architecture:** 前端 eip4-web 新 `/process-modeler` 页(bpmn-js `lib/Modeler` + 标准属性面板 + EIP4 React 侧栏控件);后端 flowable-service 新 `ProcessModelController`(flowable 原生 Model API 存草稿 act_re_model,id 净化映射存 metaInfo,发布时逆向还原);platform-flow-gateway 转发 `/api/workflow/models/**` 并承担超管门/EIP4 语义校验/部署审计。
|
||||
|
||||
**Tech Stack:** bpmn-js 17.11(已装)+ `bpmn-js-properties-panel`/`@bpmn-io/properties-panel`(新增)+ 自建 vendored activiti moddle 描述符;Flowable 6.8.1 RepositoryService Model API;React 18 + 自研 ui/Dialog;vitest + Mockito/MockMvc + Playwright。
|
||||
|
||||
---
|
||||
|
||||
## §0 事实基线(2026-07-02 勘探,全部核实过)
|
||||
|
||||
**语料(本地 eip4 库,5433,search_path=eip3)**:1512 真实 BPMN(act_ge_bytearray)/1503 部署/143 act_re_model。
|
||||
扩展面实测:**11 个扩展属性**(activiti:formKey 1476docs / candidateUsers 1465 / exclusive 1311 / assignee 27 / collection 28 / elementVariable 24 / candidateGroups 3 / autoStoreVariables 4 / initiator 3 / dueDate 1 + flowable:assignee 3docs)、**5 个扩展元素**(taskListener 159docs / formProperty 6 / value / field / string);命名空间 activiti=1509docs、flowable=3docs。BPMN 特性:userTask 1505 / conditionExpression 297 / exclusiveGateway 276 / parallelGateway 52 / **multiInstance 28(8 个 distinct key,如「总包合同交底」——key 就是中文,D7 id 可逆净化是硬需求)** / boundary·timer·subProcess·error 个位数 / signal·callActivity·serviceTask 零。
|
||||
|
||||
**后端**(file:line 均已核实):
|
||||
- 部署端点已有:`FlowController.deploy` @ flowable-service `api/FlowController.java:81-105`,body=`{name?,bpmnXml}`,`createDeployment().name().addString().deploy()`,**无鉴权无审计**;网关 FlowableClient **未封装 deploy**。
|
||||
- `ProcessDiagramController.java`:`sanitizeBpmnIds` @ :120 **单向丢映射**(:125 建 map :130 `"n"+hex(hash)`,方法返回即弃);`readProcessModel(procDefId)` @ :172 是 private(`repositoryService.getProcessModel`);**无 public 按 procDefId 取 XML 端点**。ID 重写正则 `ID_ATTR` @ :113-114 覆盖 `id|bpmnElement|sourceRef|targetRef|attachedToRef|processRef|default`。
|
||||
- Flowable 6.8.1 裸引擎(flowable-service/pom.xml:26,非 starter;flowable5-compatibility 已引)。`RepositoryService` bean @ `config/FlowableEngineConfig.java:73-76`;`databaseSchemaUpdate=false`(:55,红线)。**Model API(newModel/saveModel/addModelEditorSource/getModelEditorSource/createModelQuery)全仓零使用**——本计划首次启用,act_re_model 表已存在(143 行),无需 DDL。
|
||||
- 网关模式:`FlowableClient`(client/FlowableClient.java,RestClient,baseUrl 默认 :8089,`execute()` @ :299 连接类失败重试→503、4xx/5xx 透传不重试);控制器方法参数注入 `AuthPrincipal`;**超管判定现成**:`EngineContextBinder.isSystemAdmin(AuthPrincipal)` @ platform-auth `security/EngineContextBinder.java:68-76`(userId trim equalsIgnoreCase "ADMIN" 或 account=="admin")。
|
||||
- flowable-service **无 Spring Security 无 @Profile**,裸 8089 靠网关保护 → 超管门必须落在网关层。
|
||||
- 审计现状:部署/审批动作无审计表(只有 taskService.addComment + logger);唯一显式审计模型先例=platform-ai `AiAuditEntry`。Flyway 机制已有(platform-app `db/migration/V1-V3`),本计划加 V4。
|
||||
- 办理人 JSON(`BasePropertiesConverter.java`):`{"items":[{type,content,isCandidate,isSendMail,isSendPhone(,isSendMessage)}]}`;**BPMN 里花括号写全角 `【】`**,handler 运行时 replace 回 `{}`;前缀常量 `CANDIDATESERVICE="${candidateUsersHandler.getCandidateUsers(execution,'"` @ :34、`MULTIINSTANCESERVICE="${multiInstanceUsersHandler.getUsers(execution,'"` @ :35。type 取值:user/depart/position/formSpecifiedDimension/initiator/sameToTask/beforeTaskLeader/beforeTaskDepartManager/scriptUser/projectRoleType。引擎注册 bean 名(FlowableEngineConfig:62-68):`candidateUsersHandler`(TrimmingCandidateUsersHandler)/`multiInstanceUsersHandler`。
|
||||
- 起实例(e2e 用):`POST /api/flow/process/start` @ FlowController:246(processDefinitionKey→startProcessInstanceByKey)。
|
||||
- WfTemplate 全量列表端点**不存在**(WfTemplateService 只按单 id 查)→ 需新建 picker 数据源。
|
||||
- 测试范本:`ProcessDiagramControllerTest`(@Mock RepositoryService + MockMvc standalone + getProcessModel stub 返 ByteArrayInputStream)、`FlowableClientTest`(MockRestServiceServer)、`CandidateUsersHandlerTest`。
|
||||
|
||||
**前端**:
|
||||
- bpmn-js 17.11.1 已装、`lib/Modeler` 可直接 import、CSS 裸路径可行(ProcessDiagram.tsx:4-6 已验证);**需新增 `bpmn-js-properties-panel` + `@bpmn-io/properties-panel`**;Modeler 需补 `bpmn-js/dist/assets/bpmn-font/css/bpmn.css`(palette 图标)。
|
||||
- 现有 `/modeler` = 实体建模器(占用)→ 新页用 **`/process-modeler`**。
|
||||
- admin 门=页面组件内 `isAdminProfile(getProfile())` 自查降级(ModelerPage.tsx:21-22 范式);路由注册 App.tsx:41-52;入口挂 DesignCenterPage.tsx:76-91 按钮区 + Topbar.tsx:71-80 admin 图标。
|
||||
- 弹窗/确认:自研 `ui/Dialog`(Dialog/Drawer)+ `toast()`;选人表单范本 ApprovalDrawer.tsx `MultiUserForm`(:199-261)。
|
||||
- api 惯例:`src/api/http.ts` axios 单例;流程域走裸 JSON 派(diagram.ts 防御性默认);网关前缀 `/api/workflow/`。
|
||||
- 测试:vitest(token 用 importOriginal 只 mock getProfile);Playwright 新配一个 config(照 `playwright.fivering.config.ts`:后端 8094、vite 5174、`apiJson`/`adminToken` 辅助复用 five-ring.spec.ts 写法)。
|
||||
- 生命周期范本 ProcessDiagram.tsx:29-67(alive flag + destroy try/catch);编辑器页布局范本 editor/DesignerPage.tsx。
|
||||
|
||||
## §0.5 计划级决策(design「待 plan 细化」四项 + 实现取舍,执行前已定)
|
||||
|
||||
| # | 决策 | 取定与理由 |
|
||||
|---|------|-----------|
|
||||
| P1 | moddle 描述符来源 | **自建 vendored** `eip4-web/src/modeler/moddle/activiti.json`(完整 activiti 命名空间描述符,以社区 activiti-bpmn-moddle 内容为种子手工审校收录,不引 npm 依赖——供应链可控 + 可扩展 flowable 别名)。**验收=双门**:①语料覆盖测试(§0 的 11 属性+5 元素全部声明)②moddle 层 round-trip 零丢失测试 |
|
||||
| P2 | 影响摘要 diff | 前端 DOMParser 节点级 diff:按 userTask id 对齐,比较 candidateUsers/assignee/formKey/multiInstance 四类属性变化,列「节点名:改了什么」。不做通用图 diff(YAGNI) |
|
||||
| P3 | 新建模板库 | 3 个:单人审批/两级审批/会签,静态 BPMN 字符串放 `src/modeler/templates/`。**以真实流程为骨架改造**(从「总包合同交底」等抽形),保证与引擎兼容 |
|
||||
| P4 | 草稿权限 | v1 整页 admin 门(页面+网关双层),草稿全体 admin 共见,无 per-user 属主(YAGNI,v2 再说) |
|
||||
| P5 | EIP4 定制控件宿主 | **不写 preact 属性面板分组**,改为**同右栏叠放的 React 侧板**(selection.changed 驱动),放标准面板上方。理由:preact entries 与 React+RTL 测试栈割裂、集成风险高;React 侧板同样满足 D4「标准全套+定制叠加」,且原生字段照旧显示+灰字提示。含通用「activiti 扩展属性」键值编辑器兜底长尾属性(D5 全属性可编辑)+ taskListener 简单编辑(event+class/delegateExpression) |
|
||||
| P6 | 语料保真扫描 | 全量 1512 流 round-trip 扫描做成**工具脚本**(连库跑,如 parity 模式),不进 CI 硬门;单测用**合成 fixture**(复刻 §0 全扩展面+中文 id+全角【】),不把客户 BPMN 提交进仓 |
|
||||
|
||||
---
|
||||
|
||||
## 阶段 1:moddle 保真 + 只读载入存量(可独立合 main)
|
||||
|
||||
### Task 1.1 前端依赖 + moddle 描述符 + 保真单测
|
||||
|
||||
**Files:**
|
||||
- Modify: `eip4-web/package.json`(+`bpmn-js-properties-panel@^5.23.0` +`@bpmn-io/properties-panel@^3.23.0`;装完看 npm 实际解析版本,只需兼容 bpmn-js 17)
|
||||
- Create: `eip4-web/src/modeler/moddle/activiti.json`(完整 activiti 描述符:name=Activiti, uri=`http://activiti.org/bpmn`, prefix=activiti;types 覆盖 §0 全部 11 属性(挂 bpmn:UserTask/Process/SequenceFlow 等宿主的 extension attributes)+ taskListener/formProperty/field/string/value 元素;另加 flowable 别名描述符 `flowable.json`(uri=`http://flowable.org/bpmn`,覆盖 flowable:assignee 等 3docs 用到的属性))
|
||||
- Create: `eip4-web/src/modeler/moddle/fidelity.test.ts`
|
||||
- Create: `eip4-web/src/modeler/moddle/fixtures/synthetic-full-surface.bpmn.ts`(合成 fixture:中文 process id/name + userTask 带 candidateUsers 全角【】JSON + formKey + exclusive + 多实例(collection/elementVariable/completionCondition) + taskListener(class+field/string/value) + formProperty + boundaryEvent/timer + conditionExpression + BPMNDiagram DI)
|
||||
|
||||
**Step 1** 写失败测试(fidelity.test.ts,moddle 层 round-trip):
|
||||
|
||||
```ts
|
||||
import BpmnModdle from 'bpmn-moddle';
|
||||
import activiti from './activiti.json';
|
||||
import flowable from './flowable.json';
|
||||
import { SYNTHETIC_BPMN } from './fixtures/synthetic-full-surface.bpmn';
|
||||
|
||||
const CORPUS_ATTRS = ['formKey','candidateUsers','exclusive','assignee','collection',
|
||||
'elementVariable','candidateGroups','autoStoreVariables','initiator','dueDate'];
|
||||
const CORPUS_ELEMENTS = ['taskListener','formProperty','value','field','string'];
|
||||
|
||||
it('语料覆盖:全部实测 activiti 属性/元素在描述符中有声明', () => {
|
||||
const declared = JSON.stringify(activiti);
|
||||
[...CORPUS_ATTRS, ...CORPUS_ELEMENTS].forEach(n =>
|
||||
expect(declared, `activiti:${n} 未声明`).toContain(`"${n}"`));
|
||||
});
|
||||
|
||||
it('round-trip 零丢失:import→export 后全部 activiti 扩展原样保留', async () => {
|
||||
const moddle = new BpmnModdle({ activiti, flowable });
|
||||
const { rootElement } = await moddle.fromXML(SYNTHETIC_BPMN);
|
||||
const { xml } = await moddle.toXML(rootElement, { format: false });
|
||||
// 关键断言:每个扩展属性值逐字保留(含全角【】JSON、中文 id)
|
||||
for (const frag of ['activiti:formKey="view_wftemplate_'
|
||||
, "candidateUsersHandler.getCandidateUsers(execution,'【"
|
||||
, 'activiti:taskListener', 'activiti:elementVariable="assignee"'
|
||||
, 'multiInstanceUsersHandler.getUsers']) {
|
||||
expect(xml).toContain(frag);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
**Step 2** `cd eip4-web && npm install bpmn-js-properties-panel@^5.23.0 @bpmn-io/properties-panel@^3.23.0 && npx vitest run src/modeler` → 期望 FAIL(描述符/fixture 不存在)。
|
||||
**Step 3** 写 activiti.json/flowable.json 描述符 + 合成 fixture(fixture 的多实例/办理人形态先 `psql` 抽「总包合同交底」BPMN 对照,形态照抄)。
|
||||
**Step 4** `npx vitest run src/modeler` → PASS;`npx tsc -b` 干净。
|
||||
**Step 5** commit:`feat(modeler): activiti/flowable moddle 描述符 + 语料覆盖/round-trip 保真测试`
|
||||
|
||||
### Task 1.2 全量语料保真扫描脚本(工具,不进 CI)
|
||||
|
||||
**Files:** Create: `eip4-web/tools/modeler-fidelity-sweep.mjs`
|
||||
|
||||
node 脚本:`pg` 不引依赖——用 `psql` 子进程拉 `translate(encode(bytes_,'base64'),E'\n','')`(同勘探法),逐条 bpmn-moddle round-trip,对比「activiti:*/flowable:* 属性与元素多重集」前后一致(归一化后 diff),输出 `匹配 N/1512 + 差异清单`。跑:`node tools/modeler-fidelity-sweep.mjs`(连 5433/eip4)。
|
||||
**验收:1512/1512 零丢失**(有差异=描述符缺口,回补 Task 1.1 描述符后重跑)。结果记进 commit message。
|
||||
commit:`feat(modeler): 全量 1512 真实流程 moddle round-trip 保真扫描工具(实测零丢失)`
|
||||
|
||||
### Task 1.3 后端:id 净化抽成可逆 `BpmnIdSanitizer`
|
||||
|
||||
**Files:**
|
||||
- Create: `flowable-service/src/main/java/com/eip4/flowservice/api/BpmnIdSanitizer.java`
|
||||
- Modify: `flowable-service/src/main/java/com/eip4/flowservice/api/ProcessDiagramController.java`(sanitizeBpmnIds 委托新类,行为不变)
|
||||
- Create: `flowable-service/src/test/java/com/eip4/flowservice/api/BpmnIdSanitizerTest.java`
|
||||
|
||||
**Step 1** 失败测试(核心断言:可逆):
|
||||
|
||||
```java
|
||||
@Test void 净化后还原_逐字节等于原文() {
|
||||
String xml = 读fixture(中文id流程含processRef/sourceRef引用);
|
||||
BpmnIdSanitizer.Result r = BpmnIdSanitizer.sanitize(xml);
|
||||
assertThat(r.xml()).doesNotContain("总包合同交底");
|
||||
assertThat(BpmnIdSanitizer.restore(r.xml(), r.idMap())).isEqualTo(xml);
|
||||
}
|
||||
@Test void 还原只回写映射内id_新增ASCII节点id保留() { ... }
|
||||
@Test void 合法NCName_id不改写_映射为空() { ... }
|
||||
```
|
||||
|
||||
**Step 2** `mvn -pl flowable-service -am test -Dtest=BpmnIdSanitizerTest` → FAIL。
|
||||
**Step 3** 实现:搬 ProcessDiagramController :113-150 的 `ID_ATTR` 正则与净化逻辑进 `sanitize`(返回 `record Result(String xml, Map<String,String> idMap)`,idMap=原→净化);`restore(xml, idMap)` 用同一 `ID_ATTR` 正则反向替换(净化→原,仅命中 map 值者)。ProcessDiagramController 原 static 方法改为委托(保持包级可见签名,原单测不动)。
|
||||
**Step 4** `mvn -pl flowable-service -am test`(含既有 ProcessDiagramControllerTest 回归)→ 全绿。
|
||||
**Step 5** commit:`refactor(flow): id 净化抽 BpmnIdSanitizer,补可逆 restore(D7 地基)`
|
||||
|
||||
### Task 1.4 后端:按 procDefId 取源 XML 端点
|
||||
|
||||
**Files:**
|
||||
- Modify: `flowable-service/.../api/ProcessDiagramController.java`(新增端点,readProcessModel 已在此类)
|
||||
- Modify: `flowable-service/src/test/java/com/eip4/flowservice/api/ProcessDiagramControllerTest.java`
|
||||
|
||||
**Step 1** 失败测试:`GET /api/flow/process-definitions/{procDefId}/source` → `{found:true, bpmnXml:<净化后>, idMap:{原:净}, procDefKey, version}`;procDefId 不存在 → `{found:false}`(200,防御性——网关照 diagram 惯例)。
|
||||
**Step 3** 实现:`repositoryService.getProcessModel` + `createProcessDefinitionQuery().processDefinitionId(id).singleResult()`(取 key/version)+ `BpmnIdSanitizer.sanitize`,返回 xml 与 idMap。
|
||||
**Step 4** `mvn -pl flowable-service -am test` 绿。**Step 5** commit:`feat(flow): 按 procDefId 取净化源 XML 端点(含 idMap)`
|
||||
|
||||
### Task 1.5 前端:ProcessModelerPage 骨架 + 只读载入存量
|
||||
|
||||
**Files:**
|
||||
- Create: `eip4-web/src/pages/ProcessModelerPage.tsx`、`src/api/processModeler.ts`、`src/pages/ProcessModelerPage.test.tsx`
|
||||
- Modify: `src/App.tsx`(+route `/process-modeler`)、`src/pages/DesignCenterPage.tsx`(+入口按钮 `dc-process-modeler`「流程设计」)、`src/shell/Topbar.tsx`(admin 图标可选,跟设计中心并排)
|
||||
|
||||
**Step 1** 失败测试(照 ModelerPage.test.tsx 范式:importOriginal 保留 isAdminProfile、mock getProfile + api):admin 可见容器 `data-testid="process-modeler-canvas"` 与属性面板容器;非 admin 显示「仅管理员可用」;`?procDefId=` 时调 `fetchProcDefSource` 并 importXML(mock api 返合成 fixture)。
|
||||
**Step 3** 实现:照 ProcessDiagram.tsx 生命周期(alive flag/destroy)挂 `bpmn-js/lib/Modeler`:
|
||||
|
||||
```ts
|
||||
import Modeler from 'bpmn-js/lib/Modeler';
|
||||
import { BpmnPropertiesPanelModule, BpmnPropertiesProviderModule } from 'bpmn-js-properties-panel';
|
||||
import 'bpmn-js/dist/assets/diagram-js.css';
|
||||
import 'bpmn-js/dist/assets/bpmn-js.css';
|
||||
import 'bpmn-js/dist/assets/bpmn-font/css/bpmn.css';
|
||||
import '@bpmn-io/properties-panel/dist/assets/properties-panel.css';
|
||||
import activitiModdle from '../modeler/moddle/activiti.json';
|
||||
import flowableModdle from '../modeler/moddle/flowable.json';
|
||||
|
||||
const modeler = new Modeler({
|
||||
container: canvasRef.current,
|
||||
propertiesPanel: { parent: panelRef.current },
|
||||
additionalModules: [BpmnPropertiesPanelModule, BpmnPropertiesProviderModule],
|
||||
moddleExtensions: { activiti: activitiModdle, flowable: flowableModdle },
|
||||
});
|
||||
```
|
||||
布局参照 DesignerPage:顶栏(名称/保存草稿·发布·返回,本阶段按钮 disabled 占位)+ 左画布 + 右栏(上=EIP4 侧板占位,下=标准面板)。存量入口:设计中心按钮 → 新页内「打开存量流程」下拉(数据源复用 `GET /api/process-select/options`)。
|
||||
**Step 4** `npx vitest run` + `npx tsc -b` + `npm run build` 全绿。
|
||||
**Step 5** commit:`feat(modeler): /process-modeler 页骨架(Modeler+标准属性面板+存量只读载入)`
|
||||
|
||||
### Task 1.6 网关:source 转发 + 阶段 1 live 验收
|
||||
|
||||
**Files:**
|
||||
- Modify: `platform-flow-gateway/.../client/FlowableClient.java`(+`procDefSource(procDefId)`)
|
||||
- Create: `platform-flow-gateway/.../web/ProcessModelerController.java`(`GET /api/workflow/process-definitions/{id}/source`,**超管门**:`AuthPrincipal` 校验 `EngineContextBinder.isSystemAdmin`,非超管 403——若该方法非 public static,本 task 顺带提升可见性并补一个判定单测)
|
||||
- Create: `platform-flow-gateway/src/test/.../ProcessModelerControllerTest.java`(admin 200 转发 / 非 admin 403 / flowable 不可达 503——照 FlowableClientTest 的 MockRestServiceServer 模式)
|
||||
|
||||
**live 验收(阶段 1 出口)**:`mvn -pl platform-app,flowable-service -am package -DskipTests` → `run-dev.sh both` → 浏览器 admin 登录 → 设计中心「流程设计」→ 打开「总包合同交底」→ palette/标准属性面板可见、中文节点名正常渲染、点 userTask 属性面板出 BPMN 标准属性。截图留档。
|
||||
commit + `--no-ff` 合 main:`feat(modeler): 阶段1 存量流程只读载入(moddle保真+可逆净化+页面骨架)`
|
||||
|
||||
---
|
||||
|
||||
## 阶段 2:EIP4 三控件 + 草稿(act_re_model)
|
||||
|
||||
### Task 2.1 后端:ProcessModelController(草稿 CRUD + from-procdef)
|
||||
|
||||
**Files:**
|
||||
- Create: `flowable-service/.../api/ProcessModelController.java`(`@RequestMapping("/api/flow")`)
|
||||
- Create: `flowable-service/src/test/.../ProcessModelControllerTest.java`(@Mock RepositoryService + Model + ModelQuery,MockMvc standalone,照 ProcessDiagramControllerTest)
|
||||
|
||||
端点(全裸 JSON,防御性风格同 diagram):
|
||||
- `GET /models` → `createModelQuery().orderByLastUpdateTime().desc().list()` → `[{id,name,key,lastUpdateTime}]`
|
||||
- `GET /models/{id}` → model + `new String(getModelEditorSource(id), UTF_8)` → `{found,id,name,key,bpmnXml,metaInfo}`
|
||||
- `POST /models` body `{name,key,bpmnXml,metaInfo?}` → `newModel()`+`saveModel`+`addModelEditorSource`(XML 先过 BpmnXMLConverter 解析守卫,坏 XML→422)
|
||||
- `PUT /models/{id}` → 更新 name/editorSource/metaInfo(不存在→404)
|
||||
- `POST /models/from-procdef` body `{procDefId}` → 读源 XML → `BpmnIdSanitizer.sanitize` → 建 model,**metaInfo=`{"eip4IdMap":{...},"sourceProcDefId":"...","originalKey":"总包合同交底"}`**(jackson 序列化)→ `{modelId}`
|
||||
|
||||
TDD 循环同前;测试含:from-procdef 的 metaInfo 落 idMap、坏 XML 422、404。
|
||||
commit:`feat(flow): 流程草稿 ProcessModelController(act_re_model,Model API 首次启用)`
|
||||
|
||||
### Task 2.2 网关:models 全套转发 + wftemplate picker 数据源
|
||||
|
||||
**Files:**
|
||||
- Modify: `FlowableClient.java`(+models list/get/create/update/fromProcDef 五方法)
|
||||
- Modify: `ProcessModelerController.java`(+`/api/workflow/models/**` 五端点,全部过超管门)
|
||||
- Modify: `platform-flow-gateway/.../web/`(新 `GET /api/workflow/wftemplates`:JdbcTemplate `SELECT view_wftemplate_id, ... FROM view_wftemplate`——**实现前先 psql `\d view_wftemplate` 核实名称列**(name 或 xml 内 title,照 WfTemplateService.parse 的取名逻辑),返 `[{id,name}]`)
|
||||
- Tests:转发/403/wftemplates 列表(mock JdbcTemplate)
|
||||
|
||||
commit:`feat(gateway): 流程草稿转发(超管门)+wftemplate picker 数据源`
|
||||
|
||||
### Task 2.3 前端:办理人表达式编解码器(纯函数,TDD 核心件)
|
||||
|
||||
**Files:** Create: `eip4-web/src/modeler/candidateExpression.ts` + `candidateExpression.test.ts`
|
||||
|
||||
**Step 1** 失败测试(真实形态往返):
|
||||
|
||||
```ts
|
||||
const REAL = `\${candidateUsersHandler.getCandidateUsers(execution,'【"items":[{"type":"user","content":"u1,u2","isCandidate":true,"isSendMail":false,"isSendPhone":false}]】')}`;
|
||||
it('解析真实表达式(全角【】)', () => {
|
||||
const r = parseCandidateExpression(REAL);
|
||||
expect(r!.items[0]).toMatchObject({ type: 'user', content: 'u1,u2', isCandidate: true });
|
||||
});
|
||||
it('构建=引擎口径(全角【】+前缀后缀逐字)', () => {
|
||||
expect(buildCandidateExpression(r.items)).toBe(REAL);
|
||||
});
|
||||
it('scriptUser/depart/beforeTaskLeader 各 type 往返不丢字段', ...);
|
||||
it('multiInstance 前缀变体 multiInstanceUsersHandler.getUsers 同套解析', ...);
|
||||
it('非法/空表达式返回 null 不抛', ...);
|
||||
```
|
||||
> ⚠️ 全角【】的准确包裹形态(`【"items":...】` 还是 `{"items":...}` 外层才转)**以「总包合同交底」真实 BPMN 逐字为准**——写实现前先 psql 抽原文对照,测试 fixture 逐字复制真实片段。
|
||||
|
||||
**Step 3** 实现 `parse/build`(前后缀常量逐字对齐 BasePropertiesConverter :34-35;build 输出全角,parse 兼容全角/半角)。
|
||||
commit:`feat(modeler): 办理人/会签表达式编解码器(与 BasePropertiesConverter 逐字对齐)`
|
||||
|
||||
### Task 2.4 前端:EIP4 侧板(办理人/会签/formKey/扩展属性/监听器)
|
||||
|
||||
**Files:**
|
||||
- Create: `src/modeler/Eip4Panel.tsx`(+`Eip4Panel.test.tsx`)、`src/modeler/useSelectedElement.ts`(订阅 `selection.changed`)
|
||||
- Modify: `ProcessModelerPage.tsx`(右栏上方挂 Eip4Panel)
|
||||
|
||||
控件(全部经 bpmn-js `modeling.updateProperties(element, {...})` 写回,undo/redo 天然生效):
|
||||
1. **办理人**(userTask 选中时):解析 `activiti:candidateUsers` → items 表格编辑(type 下拉=§0 的 10 种 + content 文本 + isCandidate/三个通知开关)→ build 回写。原生字段照旧显示于标准面板,控件顶部灰字:「EIP4 引擎以本控件为准,下方原生字段仅供高级调试」。
|
||||
2. **会签**:开关=读写 `loopCharacteristics`(`moddle.create('bpmn:MultiInstanceLoopCharacteristics', {isSequential, collection: MI表达式, elementVariable:'assignee'})` + completionCondition 三预设:全票 `${nrOfCompletedInstances/nrOfInstances==1}`/过半 `>0.5`/指定数 `>=N`;**结构逐字对照真实会签流**);人员来源复用办理人 items 编辑器。
|
||||
3. **formKey**:下拉(数据源 `GET /api/workflow/wftemplates`)写 `activiti:formKey`。
|
||||
4. **扩展属性**(兜底 D5):列出 `element.businessObject.$attrs` 里 activiti:/flowable: 长尾键值可增删改。
|
||||
5. **任务监听器**:读写 `extensionElements` 里 `activiti:taskListener`(event 下拉 create/assignment/complete/all + class/delegateExpression 文本;v1 不做 fields 编辑,原样保留)。
|
||||
|
||||
测试:RTL 渲染 + 假 element/modeling(vi.fn 断言 updateProperties 载荷);办理人/会签/formKey 三控件各 set/clear 用例。
|
||||
commit:`feat(modeler): EIP4 侧板三控件+扩展属性/监听器编辑`
|
||||
|
||||
### Task 2.5 前端:存草稿 + 草稿列表打开
|
||||
|
||||
**Files:** Modify `processModeler.ts`(saveDraft/createDraft/listModels/getModel/fromProcDef)、`ProcessModelerPage.tsx`(顶栏「保存草稿」`saveXML({format:true})`→PUT;打开器加「草稿」tab);tests。
|
||||
|
||||
**阶段 2 live 验收**:打开「总包合同交底」→ from-procdef 建草稿 → 改办理人(加一个 user)→ 保存 → psql 查 `act_re_model` 新行 + `act_ge_bytearray` 编辑源含改动 + metaInfo 含 eip4IdMap → 重开草稿回显正确。
|
||||
commit + 合 main:`feat(modeler): 阶段2 EIP4 控件+草稿闭环`
|
||||
|
||||
---
|
||||
|
||||
## 阶段 3:发布门(校验 + 超管 + 同人确认 + 审计 + id 还原)
|
||||
|
||||
### Task 3.1 后端:deploy-from-model(id 还原 + 引擎校验门)
|
||||
|
||||
**Files:** Modify `ProcessModelController.java` + test。
|
||||
|
||||
`POST /models/{id}/deploy`:
|
||||
1. 读 editorSource + metaInfo.eip4IdMap → `BpmnIdSanitizer.restore`(**存量 key 还原为中文原 key**;无 idMap=新建流程,跳过)。
|
||||
2. **引擎校验门**:`BpmnXMLConverter.convertToBpmnModel` + `new ProcessValidatorFactory().createDefaultProcessValidator().validate(model)` → 有 error 返回 422 `{errors:[{activityId,problem}]}` 不部署。
|
||||
3. `createDeployment().name(model.getName()).addString(key+".bpmn20.xml", restoredXml).deploy()` → 查新 procdef → `{deploymentId, processKey, newVersion}`。
|
||||
4. `GET /models/{id}/impact`:还原后解析 key → `{processKey, currentVersion(latest procdef), runningInstances(runtimeService.createProcessInstanceQuery().processDefinitionKey(key).count())}`。
|
||||
|
||||
测试:还原后部署 XML 含原中文 key(捕获 addString 参数断言)、校验失败 422 不调 deploy、impact 计数。
|
||||
commit:`feat(flow): 草稿发布(id还原+ProcessValidator校验门)+影响摘要端点`
|
||||
|
||||
### Task 3.2 网关:EIP4 语义校验 + 部署审计(Flyway V4)
|
||||
|
||||
**Files:**
|
||||
- Create: `platform-flow-gateway/.../aggregate/ModelSemanticValidator.java` + test:解析 XML(**照 WfTemplateService.newJdkDbf :116-135 钉 JDK 解析器**,防 xerces 击穿)→ ①每个 `activiti:candidateUsers`/multiInstance collection 的内嵌 JSON 可解析且 items[].type ∈ 白名单 ②`activiti:formKey` 存在于 view_wftemplate(JdbcTemplate exists)③completionCondition 匹配预设白名单正则。返回 `List<String> errors`。
|
||||
- Create: `platform-app/src/main/resources/db/migration/V4__flow_deploy_audit.sql`(照 V3 风格):`sys_flow_deploy_audit(id bigserial pk, model_id, deployment_id, process_key, new_version int, operator varchar(64), deployed_at timestamp default now())`
|
||||
- Modify: `ProcessModelerController.java`:deploy 端点=超管门 → ModelSemanticValidator(fail→422 带明细)→ FlowableClient.deployModel → 成功后 JdbcTemplate INSERT 审计行(operator=principal.userId())。
|
||||
- Tests:语义校验三类各 fail 用例 / 非 admin 403 / 审计行落库断言(mock JdbcTemplate 捕获参数)。
|
||||
|
||||
commit:`feat(gateway): 发布语义校验门+sys_flow_deploy_audit 审计(V4)`
|
||||
|
||||
### Task 3.3 前端:同人确认弹窗(影响摘要)+ 发布流
|
||||
|
||||
**Files:** Create `src/modeler/PublishConfirm.tsx`(+test)、`src/modeler/diffSummary.ts`(+test,P2 节点级 diff);Modify `ProcessModelerPage.tsx`。
|
||||
|
||||
发布点击 → 并发取 impact + 本地 diffSummary(打开时的源 XML vs 当前 saveXML)→ `ui/Dialog`:流程 key/当前版本→新版本/运行中实例数(灰字:留在旧版本不受影响)/「办理人或会签变更节点」清单 → 确认 → deploy → `toast('已发布 vN','ok')`;422 校验失败按节点渲染错误清单。
|
||||
commit:`feat(modeler): 同人确认发布(影响摘要+节点级diff+校验错误展示)`
|
||||
|
||||
**阶段 3 live 验收**:改「总包合同交底」办理人 → 发布 → psql 验 act_re_procdef 新版本 **key_ 仍=总包合同交底**、sys_flow_deploy_audit 有行、旧版本运行实例不受影响;非 admin 用户 curl deploy=403。合 main。
|
||||
|
||||
---
|
||||
|
||||
## 阶段 4:新建流程 + live e2e + 收尾
|
||||
|
||||
### Task 4.1 模板库 + 新建流
|
||||
|
||||
**Files:** Create `src/modeler/templates/{blank,single-approval,two-level,cosign}.bpmn.ts` + `NewProcessDialog.tsx`(名称/key/模板选择;key 允许中文——引擎既有事实)+ tests。模板以真实流程结构为骨架(psql 抽形改造),三模板全部先过 Task 1.1 round-trip 测试 + 后端 ProcessValidator 校验。
|
||||
commit:`feat(modeler): 空白/单人/两级/会签模板新建流程`
|
||||
|
||||
### Task 4.2 Playwright live e2e(8094 惯例)
|
||||
|
||||
**Files:** Create `eip4-web/playwright.process-modeler.config.ts`(照 fivering:VITE_BACKEND_TARGET=8094、vite 5174、testMatch process-modeler)+ `e2e/process-modeler.spec.ts`。
|
||||
|
||||
场景(复用 five-ring 的 apiJson/adminToken/登录块):
|
||||
1. **改存量全链**:登录 admin → 流程设计 → 打开「总包合同交底」→ 改办理人 content 加用户 → 保存草稿 → 发布(确认弹窗断言含 key/版本/实例数)→ `apiJson POST /api/flow/process/start {processDefinitionKey:'总包合同交底'}` → 取新实例任务 approval-context 断言新办理人生效。
|
||||
2. **新建全链**:会签模板新建 → formKey 选一个 → 发布 → start → 任务出现。
|
||||
3. **走查**:中文节点名渲染 / palette 元素齐 / 标准面板 + EIP4 侧板同屏 / 非 admin 页面降级。
|
||||
|
||||
跑法(spec 头注释):`java -jar platform-app/target/*.jar --server.port=8094` + flowable 8089 → `npx playwright test -c playwright.process-modeler.config.ts`。
|
||||
commit:`test(modeler): 流程Modeler live e2e(改存量/新建/走查 3 场景)`
|
||||
|
||||
### Task 4.3 收尾:文档回写 + 对抗评审
|
||||
|
||||
- 总览 B3 行 🔴→🟢(证据哈希)、A2 行「仅剩」措辞更新、README/设计中心导航登记;本计划顶部加完成横幅。
|
||||
- **对抗评审**(house 惯例,不可跳):code-reviewer + security-reviewer 双 agent 过 diff(重点:网关超管门绕过面 / restore 正则替换的边界(id 是另一 id 前缀)/ deploy XML 注入面 / 审计字段),揪修后全量 `mvn clean install` + `npm test` + e2e 重跑。
|
||||
- 合 main + push。
|
||||
|
||||
---
|
||||
|
||||
## 验收清单(全项打勾才算 B3 完成)
|
||||
|
||||
- [ ] 1512 流 moddle round-trip 扫描零丢失(Task 1.2 工具实测)
|
||||
- [ ] 打开存量中文 key 流程→编辑→发布,act_re_procdef 新版本 key 不变(D7)
|
||||
- [ ] 办理人/会签/formKey 三控件双向往返与 BasePropertiesConverter 逐字兼容(D4)
|
||||
- [ ] 发布门:非超管 403 / ProcessValidator+语义校验 422 / 审计行落库(D2)
|
||||
- [ ] 运行中实例留旧版本(D8,e2e 断言)
|
||||
- [ ] 新建(空白+3 模板)可部署可起实例(D1)
|
||||
- [ ] Playwright 3 场景 + 全量单测 + `mvn clean install` + `tsc -b`/`npm run build` 全绿
|
||||
- [ ] 对抗评审收口,文档回写
|
||||
|
||||
## 红线提醒(执行中不可越)
|
||||
|
||||
flowable `databaseSchemaUpdate=false` 不动(act_re_model 已存在无需 DDL;审计表走 Flyway V4 是平台表非引擎表);保真层 `com.dsasp.*` 不改(BasePropertiesConverter 只读对齐,不重构);XML 解析一律钉 JDK 解析器(xerces 击穿前科);JDK 21;部署门只落网关(flowable-service 裸 8089 无安全栈);每 task TDD、每阶段对抗自查后才合 main。
|
||||
Reference in New Issue
Block a user