Files
eip4-platform/docs/plans/2026-07-02-在线流程Modeler-实施计划.md
zhengwr 6f5b1f7117 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>
2026-07-02 09:13:02 +08:00

30 KiB
Raw Blame History

在线流程 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):

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 失败测试(核心断言:可逆):

@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:

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 失败测试(真实形态往返):

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。