- 从工作区根 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>
20 KiB
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 解析路径(源码逐跳)
- XML→对象:
GridTemplateConverter.convertXmlToGridTemplate逐个<button>调ToolButtonUtil.createToolButtonByElementframework/com.dsasp.client.viewFramework/.../grid/GridTemplateConverter.java:139-144
<method>→服务名:ToolButtonUtil把每个<method>转成一个EditFormButton,servicename→EditFormButton.excuteservice,name/successmsg/icon一并带上;首个load/method的 servicename 作为前置beforeServiceframework/com.dsasp.client.viewFramework/.../util/ToolButtonUtil.java:25-55(saveService = method.attributeValue("servicename");new EditFormButton(name, icon, excuteservice))
- 按钮 id→服务名(运行时分派表):
CRUDUtil(grid 包)从 XML 用 XPath 按@type+@id取<method>/@servicename:getInsertMethod(id)→//crud/button[@type='insert'][@id='…']/method/@servicename——grid/CRUDUtil.java:738-745getUpdateMethod(id)→…[@type='update']…——:756-763getDeleteMethod(id)→…[@type='delete']…——:774-781getSelectMethod(id)/getSelectLoadMethod/getInsertLoadMethod/getUpdateLoadMethod同理 ——:783-800, 747-754, 765-772getSearchMethod()特殊:取//crud/display/@selectservice(列表查询服务挂在 display 根属性上,不是按钮)——grid/CRUDUtil.java:725-728getMethodsByButtonId(id):返回该按钮全部<method>的 servicename 列表(多保存按钮场景)——grid/CRUDUtil.java:859-869
- 按钮渲染 + 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
- insert:
- 真正执行:
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)三级解析:
- UUID 格式 →
UUID_PASSTHROUGH,原样交引擎按 PK 查(:104-107) _SAVE/_UPDATE/_DELETE后缀 →WRITE_REDIRECT,引导走/api/entity/{table}/save(:109-112, 57-59)<TABLE>_SEARCH且 TABLE 在 SYS_ENTITY →SYNTHESIZED,运行时合成默认搜索流并缓存(:114-123, 141-166)- 其余命名服务:
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,零推断:
- 取 crud XML:
SELECT xml FROM eip3.view_template WHERE view_template_id = ? - 对每个
<button>:读@type/@id/@name/@pageid/@onloadscript;遍历其<method>,取@servicename/@name/@successmsg/@icon;首个无 name 的(或load/method)= 前置加载流。 - (可选校验)
SELECT sys_serviceflow_id, iscontrol FROM eip3.sys_serviceflow WHERE sys_serviceflow_id = ANY(?)验证每个 servicename 存在、判读/写(iscontrol)。 - 生成 amis:动作 api =
/api/flow/{servicename};读/写分流按 (b)。
不要依赖 {TABLE}_{ADD/...} 命名约定反推 servicename——命名只是习惯,真值在 XML。view_template_service 仅作辅助校验(登记了 _SEARCH),不作派发依据。
(d) 风险与未知项 —— 见 §5
5. 风险与未解决的未知项
- 写流后缀闸不全(语义不一致,高优先):
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「只读纪律」名存实亡,必须落实写流防护。 - 写流防护缺位(FlowController 自陈,安全):
FlowController.java:44-52注释明示引擎不区分读写,入口理论上可触发写流,P2 才补「流定义 service 节点 method 白名单 + 只读连接 + statement_timeout」。走 (b)(写动作经 /api/flow)前,必须先把这层防护和「写流显式放行清单」做出来。 - 服务控制(SYS_TEMPLATECONTROL)未覆盖:按钮可配前置控制流(§1.4,
GridTemplateComponent.java:653-665/FlowExcuteServiceImpl.checkControl)。通知模块未实测到配置,但 EIP4 转换器目前未处理 button 控制链;若有控制配置的模块会漏跑前置校验流。需登记并在引擎侧确认checkControl是否已在 EIP4 执行路径生效。 _ADD_AND_SUBMIT/_SUBMIT/_PUBLISH/_UPDATE_AC的 contentxml 未逐一审阅:只确认了_ADD含拟稿人/时间戳逻辑。这些写流是否触发 Flowable 审批、是否级联多表、是否依赖前端额外参数(如 onloadscript 2a753a3d 预填的发送参数),需逐一读 contentxml 才能定 amis 表单字段与 body。- onloadscript(查看 d7a82532 / 发送通知 2a753a3d)的前端脚本语义未解析:老引擎在打开页时跑 ViewScript(JS-like),可能改字段可见性/默认值/联动。amis 侧需评估能否用
initApi+ 表达式覆盖,或需自定义逻辑。 - 多保存按钮的 amis 表单复用:「添加」一个表单页挂两个提交按钮(保存 / 保存并提交审批),amis form 需支持多 submit 各自不同 api——可行(多 button
actionType:ajax指不同 api),但要确认 amis-fork 已支持本项目用法。 - 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。