Files
eip4-platform/docs/研究/按钮与保存-服务流分派机制.md
zhengwr 1b69f8b481
Some checks failed
ci / build-test-parity (push) Has been cancelled
docs: 统一项目文档进 eip4-platform/docs + 新增进度路线总览
- 从工作区根 docs/(非 git,未版本化)合并全部文档进版本控制,消除文档两头分裂
- 新增 README(状态总览+模块完成度+全文档索引)、项目进度与路线-总览-2026-06-17(A兼容/B新功能+关键路径+待拍板决策)
- 被取代的冲突状态/审计快照归入 归档/;对最易误导的两份("16视图已交付"实现交付报告、06-13架构快照)加"已归档"横幅
- 现行权威:engineclass移植backlog(46视图) + 用户管理Delta移植(方法论/交接) + 组件设计体系 + 通用模板收口 + 客户沟通
- 诚实口径:纵向模块仅用户管理 parity,横向引擎地基较全,余 153 定制视图(47 framework+106 业务)多为通用页已产·delta 未移植

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-17 14:53:29 +08:00

20 KiB
Raw Blame History

EIP3 按钮 / 保存 → 服务流派发机制(只读研究)

目的:搞清老通用低代码引擎如何把【按钮点击】和【保存】派发到具体【服务流】,作为 EIP4「写/动作路径走服务流」转换设计的依据。 纪律:每条论断给 file:line 或 DB 证据;推断明确标注「推断」。


0. 一句话结论(最重要)

派发不是命名约定,而是显式绑定。 每个 CRUD 按钮在 view_template.xml 里都带一个或多个 <method servicename="…"/> 子元素,servicename 的值(如 OA_NOTICEMANAGE_ADD)就是 sys_serviceflow 表的主键 sys_serviceflow_id。运行时引擎用这个名字按主键直接 loadPOJO 出服务流定义并执行。{TABLE}_{ADD/UPDATE/DELETE/SEARCH} 只是人起的命名习惯,引擎不靠它推断——靠的是 XML 里写死的 servicename。

起点事实里「按钮无 servicename/serviceid 属性」是对的,但只对按钮元素的属性成立;servicename 藏在按钮的子元素 <method> 上。这是之前误判的根因。


1. 按钮 → 服务流的确切派发约定

1.1 数据形态(DB 实测)

通知管理 crud e732c4b0-2402-4e73-8cc4-786c8a8c52af 的 XML 存在 eip3.view_template.xml 列(view_template 表结构:view_template_id, name, type, xml, engineclass…,DB \d view_template)。该行 name=通知管理, type=1, engineclass=空。

实测 XML 的按钮节点(psql … SELECT xml FROM view_template WHERE view_template_id='e732c4b0…'):

按钮 name button @type button @id(节选) <method> 子元素 servicename
添加 insert 478f950e… 保存→OA_NOTICEMANAGE_ADD;保存并提交审批→OA_NOTICEMANAGE_ADD_AND_SUBMIT
修改 update 6e5b803c… load→OA_NOTICEMANAGE_LOAD;保存→OA_NOTICEMANAGE_UPDATE;保存并提交审批→OA_NOTICEMANAGE_ADD_AND_SUBMIT
删除 delete 61c64168… OA_NOTICEMANAGE_DELETE
查看 read b229add5…(onloadscript=d7a82532) OA_NOTICEMANAGE_LOAD
实际接收对象 read 6ec34d40… OA_NOTICEMANAGE_LOAD
发送通知 update e62f1594…(onloadscript=2a753a3d) load→OA_NOTICEMANAGE_LOAD_SENDNOTICE;发送→OA_NOTICEMANAGE_PUBLISH
文件归档 delete 5f15dbfe… OA_NOTICEMANAGE_UPDATE_AC
提交审批 delete b3c01de2… OA_NOTICEMANAGE_SUBMIT

关键 XML 形态(实测):

<button id="478f950e-…" type="insert" name="添加" pageid="7a1bbdaf-…" …>
  <method name="保存" servicename="OA_NOTICEMANAGE_ADD" successmsg="保存成功!"/>
  <method name="保存并提交审批" servicename="OA_NOTICEMANAGE_ADD_AND_SUBMIT" successmsg="保存成功!"/>
</button>
<button id="6e5b803c-…" type="update" name="修改" pageid="7a1bbdaf-…" …>
  <method servicename="OA_NOTICEMANAGE_LOAD"/>            <!-- 加载(前置 load) -->
  <method name="保存" servicename="OA_NOTICEMANAGE_UPDATE" successmsg="保存成功!"/>
  <method name="保存并提交审批" servicename="OA_NOTICEMANAGE_ADD_AND_SUBMIT" successmsg="保存成功!"/>
</button>

(注:修改/发送通知 等 update/read 按钮的第一个 <method> 无 name,是前置加载流;带 name 的是表单页底部的保存/动作按钮。删除/文件归档/提交审批 仅一个 <method>,列表页点击即执行,无表单页。)

1.2 解析路径(源码逐跳)

  1. XML→对象:GridTemplateConverter.convertXmlToGridTemplate 逐个 <button> 调 ToolButtonUtil.createToolButtonByElement
    • framework/com.dsasp.client.viewFramework/.../grid/GridTemplateConverter.java:139-144
  2. <method>→服务名:ToolButtonUtil 把每个 <method> 转成一个 EditFormButton,servicename → EditFormButton.excuteservice,name/successmsg/icon 一并带上;首个 load/method 的 servicename 作为前置 beforeService
    • framework/com.dsasp.client.viewFramework/.../util/ToolButtonUtil.java:25-55(saveService = method.attributeValue("servicename");new EditFormButton(name, icon, excuteservice))
  3. 按钮 id→服务名(运行时分派表):CRUDUtil(grid 包)从 XML 用 XPath 按 @type + @id 取 <method>/@servicename:
    • getInsertMethod(id) → //crud/button[@type='insert'][@id='…']/method/@servicename —— grid/CRUDUtil.java:738-745
    • getUpdateMethod(id) → …[@type='update']… —— :756-763
    • getDeleteMethod(id) → …[@type='delete']… —— :774-781
    • getSelectMethod(id) / getSelectLoadMethod / getInsertLoadMethod / getUpdateLoadMethod 同理 —— :783-800, 747-754, 765-772
    • getSearchMethod() 特殊:取 //crud/display/@selectservice(列表查询服务挂在 display 根属性上,不是按钮)—— grid/CRUDUtil.java:725-728
    • getMethodsByButtonId(id):返回该按钮全部 <method> 的 servicename 列表(多保存按钮场景)—— grid/CRUDUtil.java:859-869
  4. 按钮渲染 + onClick:GridTemplateComponent 为每个 insert/update/delete 按钮建 Vaadin Button,button.setId(buttonId),onClick 里:
    • insert:createButtonUseMoreServ(label, icon, crudUtil.getMethodsByButtonId(insertid), listener),点击打开表单页 GridTemplateInsertWindow —— grid/GridTemplateComponent.java:679-739
    • update:同上,先校验「选中一条」,再打开表单页 —— :745-826
    • delete:createButton(label, icon, crudUtil.getDeleteMethod(deleteid), listener),点击(可选确认框)后直接 deleteExcute(deleteid) —— :831-922
  5. 真正执行:ViewEngineActionUtil.excuteService(param, serviceName) → flowExcuteService.excute(param, UserSession.get(), serviceName)
    • framework/com.dsasp.client.viewFramework/.../component/ViewEngineActionUtil.java:165-181
    • delete 直接执行点:GridTemplateComponent.java:927, 950(ViewEngineActionUtil.excuteService(param, crudUtil.getDeleteMethod(deleteid)))

1.3 「提交审批」vs「文件归档」如何区分(关键难点)

两者 @type 都是 delete,但 @id 不同,各自挂不同的 <method servicename>:

  • 文件归档 id=5f15dbfe… → OA_NOTICEMANAGE_UPDATE_AC(XML 实测)
  • 提交审批 id=b3c01de2… → OA_NOTICEMANAGE_SUBMIT(XML 实测)

GridTemplateComponent.bindingDataDelete() 对每个 delete 按钮按其 deleteid 调 crudUtil.getDeleteMethod(deleteid)(grid/CRUDUtil.java:774 的 XPath 带 [@id='…']),所以两个同 type 的按钮各自解析到自己的服务流。区分键是 button @id,不是 name、不是 view_template_service、不是 onloadscript。 (name 仅用于显示和「服务控制」匹配,见 §1.4。)

注意一个反直觉点:两个 delete 按钮实际都不是删数据——文件归档走 _UPDATE_AC(发送归档=改状态)、提交审批走 _SUBMIT(改流程状态)。type=delete 在这里只决定渲染成列表页工具按钮 + 可选确认框 + 点击即执行这套交互形态,与服务流真实语义无关。推断:老系统设计者把「列表行上点一下就触发、不开表单页」的动作一律塞进 delete 类型复用其交互骨架。

1.4 旁路:服务控制(自动前置流,非主线)

GridTemplateComponent 各按钮 onClick 里有 controlMap 分支:若按 buttonName 命中 SYS_TEMPLATECONTROL_BUTTON,会先 GetServicesFunction.excuteFlow(map, flowId) 跑控制流(GridTemplateComponent.java:653-665, 700, 776, 864)。引擎侧 FlowExcuteServiceImpl.checkControl 也会按 SYS_TEMPLATECONTROL 自动链式执行 iscontrol 控制流(FlowExcuteServiceImpl.java:104-135)。通知模块未实测到 button 控制配置,EIP4 转换初期可忽略,但需登记为未知项(见 §5)。


2. 服务流 servicename 的存储与解析

2.1 存储:servicename = sys_serviceflow 主键

sys_serviceflow 表结构(DB \d sys_serviceflow): sys_serviceflow_id(PK, varchar200), displayname, contentxml(xml), entityid, iscontrol, isactive, isupdateable …

sys_serviceflow_id 存的就是 OA_NOTICEMANAGE_ADD 这种可读名字(不是 UUID)。 DB 实测(SELECT sys_serviceflow_id, displayname, iscontrol FROM sys_serviceflow WHERE sys_serviceflow_id ILIKE 'OA_NOTICEMANAGE%')15 行全部命中,节选:

sys_serviceflow_id displayname iscontrol
OA_NOTICEMANAGE_ADD 通知管理新增 1
OA_NOTICEMANAGE_ADD_AND_SUBMIT 通知管理保存并提交审批 1
OA_NOTICEMANAGE_UPDATE 通知管理更新 1
OA_NOTICEMANAGE_DELETE 通知管理删除 1
OA_NOTICEMANAGE_LOAD 通知管理加载 0
OA_NOTICEMANAGE_SEARCH 通知管理查询 0
OA_NOTICEMANAGE_PUBLISH 发送通知 1
OA_NOTICEMANAGE_UPDATE_AC 通知管理-发送归档 1
OA_NOTICEMANAGE_SUBMIT 通知管理-提交审批 1
OA_NOTICEMANAGE_LOAD_SENDNOTICE 通知管理-发送通知加载 0

§1.1 表里 8 个按钮引用的 9 个 servicename 逐一对得上 sys_serviceflow 的 PK(DB 实测 IN 查询 9 行全中)。所以「key 存在哪」的答案是:就是 sys_serviceflow_id 列本身——不在 contentxml 属性里,也不靠 view_template_service,也不靠约定生成。起点笔记「sys_serviceflow 只有 displayname+id+contentxml+entityid」漏看了 id 列本身就是可读 servicename。

view_template_service(列 view_templateid, servicename)对通知模板只关联 OA_NOTICEMANAGE_SEARCH(DB 实测)。推断:该表只登记「列表初始查询服务」用于鉴权/索引,不是按钮派发的依据;按钮派发完全走 XML 内联 <method>。

2.2 运行时解析:按主键 loadPOJO

FlowExcuteServiceImpl.excute(map, ctx, flowId)(FlowExcuteServiceImpl.java:78-102) → flowService.getFlowDefinition(flowId)(:80) → FlowServiceImpl.getFlowDefinition:pojoService.loadPOJO(flowKey, "SYS_SERVICEFLOW", null, true)(FlowServiceImpl.java:70-88)——按主键 = 服务名直接 load 出行,再 BaseFlowConvert 用 CONTENTXML 建 Flow(BaseFlowConvert.java:199)。无 XML 全表扫描,O(1) 主键查。

2.3 EIP4 FlowNameResolver 解析(已移植)

eip4-platform/platform-metadata/.../flow/FlowNameResolver.java(resolve(flowId) :99-133)三级解析:

  1. UUID 格式 → UUID_PASSTHROUGH,原样交引擎按 PK 查(:104-107)
  2. _SAVE/_UPDATE/_DELETE 后缀 → WRITE_REDIRECT,引导走 /api/entity/{table}/save(:109-112, 57-59)
  3. <TABLE>_SEARCH 且 TABLE 在 SYS_ENTITY → SYNTHESIZED,运行时合成默认搜索流并缓存(:114-123, 141-166)
  4. 其余命名服务:SELECT COUNT(*) FROM sys_serviceflow WHERE sys_serviceflow_id = ?(:171-176),命中 → NAMED_HIT(用原名按 PK 执行),否则 → ORPHAN(404)

FlowController.run(platform-metadata/.../web/FlowController.java:146-180)按解析类型分派:UUID_PASSTHROUGH/NAMED_HIT 直接 flowExcuteService.excute(map, ctx, id);SYNTHESIZED 用合成 key 执行;WRITE_REDIRECT/ORPHAN 返 404。

关键观察:OA_NOTICEMANAGE_ADD / _ADD_AND_SUBMIT / _PUBLISH / _UPDATE_AC / _SUBMIT 不以 _SAVE/_UPDATE/_DELETE 结尾,所以走第 4 步 NAMED_HIT → 会被 /api/flow/{id} 真正执行(写流也会跑!)。只有恰好叫 …_UPDATE / …_DELETE(如 OA_NOTICEMANAGE_UPDATE、OA_NOTICEMANAGE_DELETE)才会被后缀闸挡成 WRITE_REDIRECT。这是个语义不一致点(见 §5 风险)。


3. 保存触发

3.1 多保存按钮:每个 <method name> = 表单页一个底部按钮

点「添加」打开 GridTemplateInsertWindow,createButtons() 遍历该按钮的 List<EditFormButton>(来自 getMethodsByButtonId),每个 method 渲染成一个底部按钮,按钮的 excuteservice 即其 servicename:

  • GridTemplateInsertWindow.createButtons() :114-132(serviceName = button.getExcuteservice())
  • onClick:commitForm() 收表单 → ViewEngineActionUtil.excuteService(updateParam, serviceName) —— :134-179(:151)

所以「添加」表单页底部有两个按钮:

  • 保存 → OA_NOTICEMANAGE_ADD
  • 保存并提交审批 → OA_NOTICEMANAGE_ADD_AND_SUBMIT

_ADD 与 _ADD_AND_SUBMIT 何时各调:由用户点哪个底部按钮决定,不是引擎自动判断。两者是并列的独立服务流(_ADD_AND_SUBMIT 推断 = 保存 + 触发审批,contentxml 待核)。

3.2 前置加载流(load/method)

修改/查看/发送通知 的首个无 name 的 <method> 是打开表单页前的数据加载流(OA_NOTICEMANAGE_LOAD / _LOAD_SENDNOTICE),由 getInsertLoadMethod/getUpdateLoadMethod/getSelectLoadMethod(grid/CRUDUtil.java:747-800)解析。iscontrol=0(读流)。

3.3 保存做了什么(为什么不能裸存)

OA_NOTICEMANAGE_ADD 的 contentxml 实测含 getCurrentUserId + USER_ID + SAVETIME,且内含 <service beanName="pojoCRUDService">…save(DB grep)。即:服务流 = 在 pojoCRUDService.save 外面包了「盖拟稿人 USER_ID + 盖保存时间 SAVETIME」等业务逻辑。 直接调 POJOCRUDService.save 会丢掉这层。


4. EIP4 转换设计建议

(a) 各按钮该生成什么 amis 动作

按 button @type + 是否带 pageid + <method> 列表生成:

老按钮形态 amis 动作
insert/update(带 pageid,多 method) 列表工具栏 button → 打开 dialog/drawer 表单(pageid 对应的表单 schema)。表单底部每个带 name 的 <method> 渲染一个提交按钮,actionType:ajax,api:"POST /api/flow/{servicename}",body=表单数据。打开前若有 load <method>,dialog 的 initApi:"POST /api/flow/{loadServicename}" 预填。
delete(单 method,无 pageid) 列表行/工具栏 button,actionType:ajax(可配 confirmText=showmsg),api:"POST /api/flow/{servicename}",body 带选中行主键。注意:通知的「删除/文件归档/提交审批」语义各异,统一走各自 servicename 即可,不要按字面 type 归类。
read(带 pageid) button → 打开只读 dialog,initApi:"POST /api/flow/{loadServicename}"(如 OA_NOTICEMANAGE_LOAD)。
列表查询(display@selectservice) crud api:"GET /api/flow/{TABLE}_SEARCH",由 FlowNameResolver 合成或命中。

调用端点统一是 /api/flow/{servicename}(servicename 取自 XML <method>/@servicename),不是别的。

(b) 写端点/保存该怎么调服务流引擎

核心矛盾:现状 EntityWriteController(platform-metadata/.../web/EntityWriteController.java:77-116)的 /api/entity/{table}/save 绕过服务流,直接 pojoCRUDService.save/update,并用 MandatoryUserColumnFiller(:108)手工补「拟稿人 USER_ID」——这正是 OA_NOTICEMANAGE_ADD 流 contentxml 里本就有的逻辑的手工复刻。对零业务流模块尚可,但对有业务流的写动作(盖章/审批/状态机/级联)会丢逻辑。

建议:写/动作路径改走服务流,而非通用 save:

  • 保存/动作按钮的 amis api 指向 POST /api/flow/{servicename}(如 OA_NOTICEMANAGE_ADD),让引擎跑 contentxml 全套逻辑(含拟稿人/时间戳/级联),不再走 /api/entity/*/save。
  • 这要求放宽 FlowController 当前「只放查询类」的运维纪律(FlowController.java:44-52 注释自陈)——需补 §5 的写流防护后才能放心放行写流。
  • 仅当某模块确无业务流(纯元数据 CRUD)时,才回退用 /api/entity/{table}/save 通用端点。判定方法:转换期查该按钮 <method servicename> 是否存在于 sys_serviceflow 且 iscontrol=1(写流)——存在则走 /api/flow/{servicename},不存在才走通用 save。

(c) 命名约定/关联表怎么在转换期解析出每个按钮的目标服务流

转换期直接读 view_template.xml 的 <button>/<method>/@servicename,零推断:

  1. 取 crud XML:SELECT xml FROM eip3.view_template WHERE view_template_id = ?
  2. 对每个 <button>:读 @type/@id/@name/@pageid/@onloadscript;遍历其 <method>,取 @servicename/@name/@successmsg/@icon;首个无 name 的(或 load/method)= 前置加载流。
  3. (可选校验)SELECT sys_serviceflow_id, iscontrol FROM eip3.sys_serviceflow WHERE sys_serviceflow_id = ANY(?) 验证每个 servicename 存在、判读/写(iscontrol)。
  4. 生成 amis:动作 api = /api/flow/{servicename};读/写分流按 (b)。

不要依赖 {TABLE}_{ADD/...} 命名约定反推 servicename——命名只是习惯,真值在 XML。view_template_service 仅作辅助校验(登记了 _SEARCH),不作派发依据。

(d) 风险与未知项 —— 见 §5


5. 风险与未解决的未知项

  1. 写流后缀闸不全(语义不一致,高优先):FlowNameResolver 只挡 _SAVE/_UPDATE/_DELETE 后缀(FlowNameResolver.java:57-59)。通知的写流 OA_NOTICEMANAGE_ADD/_ADD_AND_SUBMIT/_PUBLISH/_UPDATE_AC/_SUBMIT 不带这些后缀 → 当前会被 /api/flow/{id} 当 NAMED_HIT 直接执行(含写)。而 _UPDATE/_DELETE 又被挡成 WRITE_REDIRECT。同一批写流,命名不同、放行策略相反。转 (b) 方案后这反而是「需要写流能执行」——但意味着 FlowController「只读纪律」名存实亡,必须落实写流防护。
  2. 写流防护缺位(FlowController 自陈,安全):FlowController.java:44-52 注释明示引擎不区分读写,入口理论上可触发写流,P2 才补「流定义 service 节点 method 白名单 + 只读连接 + statement_timeout」。走 (b)(写动作经 /api/flow)前,必须先把这层防护和「写流显式放行清单」做出来。
  3. 服务控制(SYS_TEMPLATECONTROL)未覆盖:按钮可配前置控制流(§1.4,GridTemplateComponent.java:653-665 / FlowExcuteServiceImpl.checkControl)。通知模块未实测到配置,但 EIP4 转换器目前未处理 button 控制链;若有控制配置的模块会漏跑前置校验流。需登记并在引擎侧确认 checkControl 是否已在 EIP4 执行路径生效。
  4. _ADD_AND_SUBMIT / _SUBMIT / _PUBLISH / _UPDATE_AC 的 contentxml 未逐一审阅:只确认了 _ADD 含拟稿人/时间戳逻辑。这些写流是否触发 Flowable 审批、是否级联多表、是否依赖前端额外参数(如 onloadscript 2a753a3d 预填的发送参数),需逐一读 contentxml 才能定 amis 表单字段与 body。
  5. onloadscript(查看 d7a82532 / 发送通知 2a753a3d)的前端脚本语义未解析:老引擎在打开页时跑 ViewScript(JS-like),可能改字段可见性/默认值/联动。amis 侧需评估能否用 initApi + 表达式覆盖,或需自定义逻辑。
  6. 多保存按钮的 amis 表单复用:「添加」一个表单页挂两个提交按钮(保存 / 保存并提交审批),amis form 需支持多 submit 各自不同 api——可行(多 button actionType:ajax 指不同 api),但要确认 amis-fork 已支持本项目用法。
  7. type=delete 实为改状态:转换器若按 type 字面映射「删除」交互(红色/危险确认),会误导用户——文件归档/提交审批应按 name + servicename 语义渲染,不能按 type=delete 一刀切。

附:关键证据索引

  • 按钮模型字段 excuteservice:framework/com.dsasp.client.viewFramework/src/com/dsasp/client/viewframework/template/editform/EditFormButton.java:13
  • <method>→EditFormButton:…/template/util/ToolButtonUtil.java:30-55
  • 按 type+id 取 servicename:…/template/grid/CRUDUtil.java:725-809, 859-869
  • 按钮渲染+onClick+执行:…/template/grid/GridTemplateComponent.java:679-922, 927, 950
  • 表单页多保存按钮:…/template/grid/GridTemplateInsertWindow.java:114-179
  • 执行入口:…/component/ViewEngineActionUtil.java:165-181
  • 引擎按名查流:framework/com.dsasp.server.core/.../FlowServiceImpl.java:70-88;FlowExcuteServiceImpl.java:78-102
  • EIP4 解析器:eip4-platform/platform-metadata/.../flow/FlowNameResolver.java:99-176
  • EIP4 flow 门面:eip4-platform/platform-metadata/.../web/FlowController.java:146-180
  • EIP4 现状写端点(绕流直存):eip4-platform/platform-metadata/.../web/EntityWriteController.java:77-116
  • DB:view_template(crud XML)、sys_serviceflow(servicename=PK)、view_template_service(仅 _SEARCH)。连接 psql -h localhost -p 5433 -U zhengwr -d eip4dev,search_path=eip3。