Files
eip4-platform/docs/plans/2026-07-02-在线流程Modeler-实施计划.md
zhengwr 74b30adb6e docs(B3): 收尾——总览B3行🔴→🟢+一句话进度+README+计划完成横幅+双对抗评审处置
B3 在线流程Modeler v1 全17任务完成合main。评审处置:安全Critical#1(nginx)已修+A10加固backlog;
发布链I-1(formKey门误拒)语料dry-run证伪(803全命中miss=0)/I-2空content已知限制v2/M-1~3低优先。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-02 16:33:03 +08:00

42 KiB
Raw Blame History

在线流程 Modeler(B3)实施计划

✅ B3 全 17 任务完成并合 main(2026-07-02):platform origin/main 阶段1-4 全合、web origin/main 全合;每任务 TDD+对抗评审+修复轮,每阶段出口 live 验收(挡下 3 个单测/评审都没抓到的真 bug:options语义/面板ref/bpmn-js PascalCase断部署),末尾双对抗评审(安全+发布链)判定可宣告完成、唯一 Critical(nginx骨架洞)已修。Modeler 端到端可用:打开中文key存量流程→改办理人/会签保真读回→存草稿eip4IdMap保全→同人确认发布→部署新版本中文key保住+审计+起实例真userTask+旧实例不动+非admin403。

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 可逆净化是硬需求;且 moddle-xml 拒绝中文 id=进 moddle 前必须已净化,T1.1 实证)。activiti:formKey 值=裸 UUID(view_wftemplate_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 描述符 + 保真单测 ✅(8fdfe68,2026-07-02)

完成实证:panel 5.60.0/3.47.0;12/12+全量 101/101 绿;三发现已回写本计划(双包冲突→T1.5 只载 activiti / 嵌套全角【】→T2.3 / formKey=裸 UUID)。遗留:bpmn-moddle 无类型声明(TS7016 编辑器诊断,tsc -b 不受影响)→ T1.5 顺带补 .d.ts。

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

⚠️ T1.2 实证预警——hash 碰撞:现行 "n"+hex(hashCode&0x7fffffff) 有碰撞可能(1445/1512 文档 process id 为中文;同文档内两个原 id 撞哈希→引用错乱)。查看器容忍,但可逆 restore 要求双射:sanitize 必须检测碰撞并消解(碰撞时追加 -2/-3 序号),并补「同文档撞哈希仍双射可逆」单测(构造碰撞对或可注入 hash 的测试缝)。

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';
// (app 代码首次 import json:本 task 顺带在 tsconfig.app.json 开 "resolveJsonModule": true)

const modeler = new Modeler({
  container: canvasRef.current,
  propertiesPanel: { parent: panelRef.current },
  additionalModules: [BpmnPropertiesPanelModule, BpmnPropertiesProviderModule],
  // ⚠️ 只载 activiti!T1.1 实证:activiti+flowable 双包同载会因 bpmn:UserTask 同名 extends
  // 属性冲突(not allowed without redefines)静默丢弃 userTask。语料 1509/3 两命名空间不混用;
  // 单载 activiti 时 flowable 文档经 moddle lax $attrs 零丢失往返。flowable.json 只做隔离单测。
  // ⚠️ 同理:只 import 标准 BpmnPropertiesProviderModule,严禁引 Camunda provider——
  // 它会把 camunda 描述符注进 moddle,即双包冲突的变体(T1.1 评审 M-3)。
  moddleExtensions: { activiti: activitiModdle },
});

布局参照 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 验收

🔴 阶段1 live 验收实证(2026-07-02)——options 语义缺口已修:/api/process-select/options 在合并库返回的 143 选项全部 source='model',option.id=act_re_model 的 id 非 procDefId(计划原假设错),打开器按 procDefId 载入恒 found:false。修法=新增 by-key 取最新版端点(GET /api/flow/process-definitions/by-key/{key}/source + 网关同门转发),前端打开器按 option.source 双参分派(model→?procKey=key / processDefinition→?procDefId=id)。

⚠️ T1.4 评审 M-2——中文 procDefId 编码:真实 procDefId 形如 总包合同交底:3:<uuid>(中文+冒号进 path segment)。网关 FlowableClient 转发必须用 UriComponentsBuilder/uriVariables 正确编码(禁字符串拼 URL),且测试必须含一个中文 procDefId 用例(MockRestServiceServer 断言转发 URL 编码正确);live 验收也必须用中文 key 流程点穿 HTTP 全链。

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 数据源

📌 T1.6 评审 M-3:本 task 给 ProcessModelerController 加第二个及以后端点时,先抽 requireSuperAdmin() 私有方法(返回 403 ResponseEntity 或 null),所有端点统一过门防漏。

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

// T1.1 psql 实证真实形态:外层对象与 items 内每个对象的花括号**全部**是全角【】,
// 方括号[]半角,XML 属性内引号转义为 &quot;,content 可带 CHAR 尾部补白空格(不可 trim)。
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/扩展属性/监听器)

🔴 T2.3 实证——meta 透传是正确性硬要求:真实表达式外层对象除 items 外还有 5 个业务 meta 字段(messageTemplate/taskSuccessService/isSkipInitiator/isNoUserSkip/isSkipBeforeTask;taskSuccessService 是真实任务后置服务钩子如 PM_CONTRACTUALREGISTER_UPDATEPROJECTSTATUS)。codec 的 parse 已返 {items,variant,meta}、build 收 meta 可选参——侧板写回办理人/会签时必须把 parse 出的 meta 原样传回 build,否则发布会打掉已部署流程的业务字段。测试必须含「改 items 后 meta 逐字保留」用例。

📌 随本 task 顺带收 T1.5 评审遗留:红线回归测试——ProcessModelerPage 测试断言 ModelerCtor.mock.calls[0][0].moddleExtensions 键恰为 ['activiti'] 且 additionalModules 长度为 2(防「顺手」加 provider 静默回归)。(canvas ref null 分支已随 dffd1f3 修复,勿重复。)

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 前端:存草稿 + 草稿列表打开

📌 T2.2 评审遗留——草稿删除端点:五端点无 DELETE,POST 重试窗口产生的重复草稿无 API 可清、草稿列表 UX 也需要删除。本 task 或 T4.1 补:flowable-service DELETE /api/flow/models/{id}(deleteModel)+ 网关同门转发 + 前端草稿列表删除按钮(confirm)。

📌 T2.2 实证——wftemplates 名称现实:view_wftemplate 无名称列(计划原假设错),网关已按 entityid→sys_entity.name 解析——1016 活动模板仅 339 有中文名,其余下拉显 uuid。formKey 下拉须加过滤输入框(1016 项不可裸滚动),无名项显示「<uuid 前 8 位>…(未命名)」。此项归本 task 或 T2.4 收口轮顺带。

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 还原 + 引擎校验门)

🔴 阶段2 live 实证——bpmn-js 输出被严格 XSD 校验拒(已修,且警示 T3.1):flowable convertToBpmnModel(src, validateSchema=true, ...) 的严格 Xerces XSD 校验拒绝 bpmn-js saveXML 的默认命名空间输出(cvc-complex-type.2.4.a: Invalid content ... {MODEL}Process),原始带前缀 source 能过。草稿保存已改 validateSchema=false(草稿是半成品,XSD 不适用)+ 字节级 DOCTYPE 守卫保 XXE。本 task deploy 必须验证同问题:createDeployment().addString().deploy() 也解析 bpmn-js 输出,若 Flowable 部署校验拒默认命名空间/activiti 扩展,需在部署前把 bpmn-js XML 规范化(或确认 deploy 路径不走严格 XSD)——阶段 3 live 必须用「编辑器改过并 saveXML 的真实流程」部署,不能只用原始 source。

⚠️ T1.3 评审 I-2 预警——文本引用:bpmn-js saveXML 会给流节点补 <bpmn:incoming>/<bpmn:outgoing> 元素文本引用(存量 1512 文档 0 命中,但编辑器导出会有),BpmnIdSanitizer.restore 只还原属性位 → 直接部署会落库「属性=中文原 id、文本引用=净化 id」的脏 XML(Flowable 不解析 incoming/outgoing 故功能无害,但再次 from-procdef 重编辑时碰撞序号换位可能指错节点)。本 task 必须:restore 前剥除 incoming/outgoing 元素(Flowable 自行从 sequenceFlow 推导)或把文本引用位纳入 restore,二选一并加测试(含「编辑器导出态 XML → 部署 XML 无净化 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)

📌 T2.4 评审补充:语义校验白名单须加两条——①办理人/会签表达式的 items 非空(items:[] 的 MI collection 运行期会炸,仅 JSON 可解析+type 白名单不够);②completionCondition 允许「三预设 或 保留的自定义 body」(T2.4 已实现自定义保留态,校验别把存量自定义条件拒了,白名单改为预设正则 ∪ 非空任意表达式加告警)。

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)

🔴🔴 阶段3 live 揪出 CRITICAL——activiti.json 描述符致 bpmn-js Modeler 输出 PascalCase 元素名(部署链断):bpmn-js Modeler.saveXML 对 activiti.json extends 的 bpmn 类型(Process/UserTask/StartEvent)序列化成大写 <Process>/<UserTask>/<StartEvent>(未扩展的 sequenceFlow/endEvent 仍小写)。Flowable 大小写敏感→<Process> 不识别→ProcessValidator 报 flowable-process-definition-not-executable,部署完全断。「isExecutable 丢失」是此 bug 症状非独立问题。T1.1/T1.2 moddle round-trip 测试抓不到(直接 fromXML→toXML 读写同形),只有真 Modeler saveXML+真部署暴露(live 铁证)。修=重构 activiti.json 扩展类型定义让 Modeler 序列化保持小写 BPMN 元素名(moddle extends 惯用法),验收硬门=saveXML 输出小写 userTask/process + 真部署 200 + 起实例生成 userTask。已挂 T3.3 修复轮 + 需前端保真测试升级到「过 bpmn-js Modeler.saveXML 非仅 bpmn-moddle」。

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 最终发布链对抗评审处置(2026-07-02)

判定「可宣告完成,无 Critical 无阻断」。id 保真闭环三来源自洽+发布错误契约双形状透传扎实。跟进项处置:

  • I-1 formKey 门误拒改存量——语料 dry-run 证伪(无需修):全库 803 个 distinct activiti:formKey 全部命中 view_wftemplate(miss=0),formKey 门不会误拒任何存量流程。评审担心的静默回归在真实库不成立。
  • I-2 空 content 语义缺口:已作已知限制记录(见下),v2 精化(content 可能是变量表达式,硬要求非空会误拒,需按 type 分白名单)。
  • M-1(下游 422 顶层文案 handler 用 message、前端读 msg,per-node 错误仍渲染)/ M-2(by-id 写删侧无 category 守卫,超管门+UI 已兜)/ M-3(writeCosign 重建只保 4 属性,真实会签仅用 handler-collection 模式暴露低)= 低优先清理 backlog。

B3 最终安全对抗评审(2026-07-02 阶段4)——1 Critical 已修 + A10 生产加固 backlog

  • ✅ Critical#1 已修:deploy/nginx.conf 的 /flowable/ 裸 proxy 到无鉴权 8089 对公网暴露→绕过网关超管门匿名部署/覆盖生产 BPMN。改 return 404(前端只走 /api/workflow/ 网关,不需要直达)。注:此洞在 A10 部署骨架里、生产未切流,非 B3 运行时可达;网关侧超管门本身实现严密无绕过面(评审确认)。
  • A10 生产加固 backlog(非 B3 dev 阻塞,超管信任模型内可接受,随 A10 生产化做):High#2 部署 BPMN 可含 serviceTask/JUEL 表达式/监听器=引擎内表达式求值面(超管信任内可接受;修 #1 后降为加固项,v2 可加可执行元素白名单);Medium#3 网关→flowable-service 无凭据纯靠网络隔离(加 X-Internal-Auth 共享密钥纵深);Medium#4 审计只覆盖网关 deploy 路径+写失败静默(下沉审计到 flowable-service 实际部署点或加失败告警)。Low#5(无细粒度流程授权=v1有意)/#6(伪造metaInfo不提权=超管本可写任意key)/#7(impact 缺 DOCTYPE 兜底=enableSafeBpmnXml 已挡)/#8(disableSchemaValidation 只跳 XSD 不开 DTD) 均已缓解/可接受。

已知限制 / v2 精化点(2026-07-02 阶段4 e2e 发现)

  • 会签办理人 content 为空的语义缺口:ModelSemanticValidator 校验 items 非空(数组长度)但不校验 candidate item 的 content 非空。会签模板出厂 items=[{type:user,content:""}] 过语义门,但运行期 multiInstanceUsersHandler 解析空 content → MI 跳过 → 流程无任务直接结束。不硬修(content 常是 ${APPLYUSERS} 变量表达式,硬要求非空会误拒合法流程);v2 可考虑「content 空且非变量表达式 → WARNING」。用户新建会签流程须填办理人,否则部署出空转流程。
  • live e2e 非幂等:发布无运行时下架端点,每跑场景A「总包合同交底」版本 +1(live 验收固有,非 CI 硬门)。
  • 非超管 403 e2e 降级:dev 库无非超管账号,场景C④用无 token(principal==null 走同一 requireSuperAdmin 分支)+admin 对照证门有效;真非超管 token 断言待 dev 库补账号。

验收清单(全项打勾才算 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 全绿
  • 对抗评审收口,文档回写

红线提醒(执行中不可越)

每阶段合 main 前必须全 reactor mvn clean install 真绿(模块级 mvn -pl 跑不到 platform-app 的 ArchitectureRulesTest,阶段2 wftemplates 给 @RestController 注 JdbcTemplate 触棘轮就是模块级漏过、全 reactor 才 catch;且判绿看 BUILD SUCCESS 字样,勿信 | tail 后的 $?=tail 退出码);控制器新增 SQL 一律收口 Service(ArchUnit 棘轮禁 @RestController 直用 JdbcTemplate);生产 8089 不对外(T1.6 评审:门在网关的前提=flowable-service 网络隔离,阶段 3 部署门验收清单显式检查,deploy/nginx/compose 不得暴露 8089);flowable databaseSchemaUpdate=false 不动(act_re_model 已存在无需 DDL;审计表走 Flyway V4 是平台表非引擎表);保真层 com.dsasp.* 不改(BasePropertiesConverter 只读对齐,不重构);XML 解析一律钉 JDK 解析器(xerces 击穿前科);JDK 21;部署门只落网关(flowable-service 裸 8089 无安全栈);每 task TDD、每阶段对抗自查后才合 main。