转换器扩展(platform-converter,PoC crud 三段种子上): - 按 XML 根元素分派 crud/form/tree/report/group;ConversionResult+Grade 三级分级 - EDITFORM:form pageid 解析 view_page 取字段;主子表 EditGrid/FormEditGrid→input-table(子列取自 editgridtemplate) - 树:type=3 声明式→input-tree、type=4 引用式→flex(tree+crud) - 选择窗 SelectDialog/MultiSelectDialog→select+source(非 amis picker:picker 不在 6.13 schema 表单项 oneOf,闸一会拒) - <report> A 类:crud+合计行(issummer→summaryFields)+金额列(ismoney→number);selectservice→/api/flow;JOR/图表降级标注 - UiTypeMapper 统一 uitype 映射;每决策登记映射台账(全量约 1.6 万条) - 孤儿模板(entityid 非法/空 xml)旁路标记不崩(手册 §7.4) 批量+双闸(BatchConvertCli,可独立 CLI 跑批,只读连库+5435 ceshi 库硬守门): - 闸一 SchemaGate(宽松语义预处理抽出,与 AmisSchemaController 共享):通过 98.2%(1489/1516) - 闸二 playwright+本地 amis SDK 渲染冒烟,每类型抽≥5:25/25 全过 - 产物 转换产物/(schema/*.json + 分级清单.csv + 闸二结果.json) - 失败 27 个全为空 xml 孤儿模板(库内数据问题,非转换器缺陷) 新坑进手册 §8.3(picker 不在表单项 oneOf,用 select+source) §8.4(闸二大 schema 经端点拉避 HTTP 431) 单测 24 个;全 reactor mvn test+ArchUnit 绿 报告 platform-converter/P4批量转换报告.md Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
174 lines
11 KiB
Markdown
174 lines
11 KiB
Markdown
# P4 批量转换报告(模板转换器扩展 + 全量批量转换 + 双闸分级)
|
||
|
||
> 日期:2026-06-11 | 作者:platform-converter 工作线
|
||
> 数据源:客户库 192.168.20.68:5435/postgres?currentSchema=eip3(ceshi/ceshi,**只读**)
|
||
> 工程:eip4-platform/platform-converter(JDK17)
|
||
> 前序:PoC 种子 `TemplateToAmisConverter`(display/search/button 三段,3 模板 0 错误已验证)
|
||
> 依据:docs/迁移手册.md §8(amis schema 宽松语义预处理、双闸必要性、dom4j getText)、
|
||
> ../docs/决策与盘点/EIP3报表迁移方案.md(A 类报表=`<report>` 段口径)
|
||
|
||
---
|
||
|
||
## 一、一句话结论
|
||
|
||
全量 **1,516** 个 view_template 批量转换:**闸一(官方 schema 校验)通过率 98.2%(1489/1516)**;
|
||
闸二(headless 渲染冒烟,每类型抽 ≥5)**25/25 全通过**。
|
||
未过闸一的 27 个全部是 **xml 为空的孤儿模板**(库内数据问题,非转换器缺陷),转换器对其旁路标记不崩。
|
||
通过率数字 98.2% 即检查点②(首功能点切流)的输入。
|
||
|
||
---
|
||
|
||
## 二、总量与各类型分布
|
||
|
||
模板按 XML 根元素分派转换(根元素与 view_template.type 一一对应):
|
||
|
||
| 根元素 | 类型语义 | 总量 | 闸一通过 | 通过率 | SUCCESS | PARTIAL | FAILED |
|
||
|--------|---------|-----:|--------:|------:|--------:|--------:|-------:|
|
||
| crud | GRID 列表页 | 956 | 956 | 100.0% | 259 | 697 | 0 |
|
||
| report | A 类表格式报表 | 337 | 337 | 100.0% | 0 | 337 | 0 |
|
||
| tree | 树 / 树+grid | 106 | 106 | 100.0% | 0 | 106 | 0 |
|
||
| form | EDITFORM 表单页 | 70 | 70 | 100.0% | 0 | 70 | 0 |
|
||
| group | 分组容器 | 20 | 20 | 100.0% | 0 | 20 | 0 |
|
||
| (空 xml) | 孤儿模板 | 27 | 0 | 0.0% | 0 | 0 | 27 |
|
||
| **合计** | | **1516** | **1489** | **98.2%** | **259** | **1230** | **27** |
|
||
|
||
> 分级口径:
|
||
> - **SUCCESS**:全字段命中映射规则,无降级标注,闸一通过。
|
||
> - **PARTIAL**:转出有效 amis schema 且闸一通过,但有字段/特性走降级旁路(标注在映射台账)。
|
||
> - **FAILED**:无法转出(xml 为空 / 解析失败 / 根元素不支持),不入产物只入失败清单。
|
||
>
|
||
> report/tree/form/group 全部落 PARTIAL 是设计内:report 普遍含 JOR 套打版式(C 类不迁移)、
|
||
> tree 普遍含节点级按钮、form 普遍含 SelectDialog/自定义 HTML 版式、group 全为跨模板壳——
|
||
> 这些都是「能渲染、待后端/人工补」的降级,不是错误。
|
||
|
||
---
|
||
|
||
## 三、双闸结果
|
||
|
||
### 闸一:官方 schema 校验(amis-schema-6.13.0.json,draft-07)
|
||
|
||
- 通过 **1489/1516 = 98.2%**。
|
||
- 复用迁移手册 §8.1 的**宽松语义预处理**(递归剥除 `$ref` 节点的兄弟 `additionalProperties:false`),
|
||
实现抽到 `platform-converter/SchemaGate`,与 `AmisSchemaController` 共享同一份口径(消除 metadata 侧重复实现)。
|
||
- 失败 27 个全部因 xml 为空,无 schema 可校验。
|
||
|
||
### 闸二:headless 渲染冒烟(playwright + 本地 amis SDK 6.13.0)
|
||
|
||
口径:对每个模板类型从**闸一通过**的 schema 中抽 **≥5** 个,用本地 amis SDK(`../eip4-poc/.../sdk-local/`)+
|
||
无头 chromium 逐个 `amis.embed` 渲染,判定 ① 无未捕获 JS 错误 ② 根组件渲染出 DOM(#root 有子节点)。
|
||
数据接口全部桩成空响应(冒烟只验「能渲染根组件」,不验数据)。**全量渲染不要求——本闸是抽样冒烟。**
|
||
|
||
| 类型 | 抽样 | 通过 | 失败 |
|
||
|------|----:|----:|----:|
|
||
| crud | 5 | 5 | 0 |
|
||
| report | 5 | 5 | 0 |
|
||
| tree | 5 | 5 | 0 |
|
||
| form | 5 | 5 | 0 |
|
||
| group | 5 | 5 | 0 |
|
||
| **合计** | **25** | **25** | **0** |
|
||
|
||
> 闸二坑(已修,记入手册):大 schema 经 URL query 注入触发 **HTTP 431 (Request Header Fields Too Large)**,
|
||
> 误判为「根组件未渲染」。改为 schema 经独立 `/schema?id=` 端点拉取后,form 抽样从 4/5 → 5/5。
|
||
|
||
产物:`转换产物/闸二结果.json`(含逐样本判定)。
|
||
|
||
---
|
||
|
||
## 四、失败模式 Top10(按模板计,去重原因)
|
||
|
||
| # | 模板数 | 归类 | 模式 |
|
||
|---|------:|------|------|
|
||
| 1 | 937 | 转换器缺陷(待补能力) | search 字段 uitype=SelectDialog → select+source 占位(弹窗数据源 /api/picker 待后端实现) |
|
||
| 2 | 329 | C 类设计内不迁移 | report 含 reportfile(JOR 套打版式)→ 仅转表格视图,套打另案 univer/Web 打印 |
|
||
| 3 | 138 | 转换器缺陷(待补能力) | search 字段 uitype=MultiSelectDialog → select(multiple)+source 占位 |
|
||
| 4 | 69 | 模板版式 | form 含 HTML `<layout>` 自定义表格版式 → amis 默认纵向布局替代,版式需人工核对 |
|
||
| 5 | 61 | 转换器缺陷(待补能力) | tree 节点含 buttons(增删改保存)→ input-tree 不原生支持节点级按钮,需自定义工具栏 |
|
||
| 6 | 50 | 转换器缺陷(待补能力) | editform 字段 uitype=SelectDialog → select+source 占位 |
|
||
| 7 | 41 | 转换器缺陷(待补能力) | editform 字段 uitype=MultiFileUploadField → 暂映射 input-text(映射表待补该控件) |
|
||
| 8 | 27 | **模板数据问题** | xml 为空(孤儿模板,FAILED) |
|
||
| 9 | 26 | 主子表已支持 | editform 字段 uitype=EditGrid → input-table 子表(保存联动 updateSubTable 待后端) |
|
||
| 10 | 20 | 跨模板引用 | group 分组容器仅转 tabs 壳,各 tab 子模板需跨模板联动加载 |
|
||
|
||
**三桶归类(按模板计)**:
|
||
|
||
| 桶 | 模板数 | 说明 |
|
||
|----|------:|------|
|
||
| 转换器缺陷(待补能力) | 1228 | 绝大多数是 SelectDialog→数据源未联动、JOR 套打、跨模板引用等「schema 有效、待后端/人工补」项,**非渲染缺陷** |
|
||
| 模板数据问题 | 28 | xml 为空(27)+ 个别解析问题,库内存量数据缺陷 |
|
||
| 孤儿模板(entityid 非法) | 5 | entityid 在 SYS_ENTITY 无对应实体(迁移手册 §7.4),转换器旁路标记不崩 |
|
||
|
||
> 关键判读:「转换器缺陷」桶 1228 个里,**937+138+50=1125 个其实是同一件事**——SelectDialog/MultiSelectDialog
|
||
> 弹窗数据源 `/api/picker/{dialogid}/list` 尚未由后端实现。schema 本身有效且渲染通过,属「待联动」而非「转不出」。
|
||
> 真正需要补转换器映射规则的只有 MultiFileUploadField(41)等少数控件。
|
||
|
||
---
|
||
|
||
## 五、转换器扩展明细(PoC 种子 → P4)
|
||
|
||
在 PoC 已验证的 crud 三段(display/search/button)上扩出五类根元素分派:
|
||
|
||
| 段 | 旧形态 | amis 映射 | 备注 |
|
||
|----|--------|----------|------|
|
||
| **crud** | `<crud><display><field>` | crud columns | 强化 null-safe、金额列(ismoney)→number+千分位、对齐、top-level+display 双挂 button |
|
||
| **EDITFORM** | `<form pageid=…>` + view_page 的 `<fields>` | form + body items | 字段经 pageid 解析 view_page 取得;method→form actions |
|
||
| **主子表** | form 内 `uitype=EditGrid/FormEditGrid` | **input-table** + 子列 | 子列解析 `<editgridtemplate>` CDATA 内 `<editgrid><field>` |
|
||
| **树** | `<tree><node selectservice>` / `<tree><treetemplate ref/><gridtemplate ref/>` | input-tree / flex(tree+crud) | type=3 声明式 / type=4 引用式两路 |
|
||
| **picker(选择窗)** | `uitype=SelectDialog/MultiSelectDialog` | **select + 远程 source** | 不用 amis picker——picker 需内嵌 pickerSchema 且 6.13 schema 未纳入表单项 oneOf,闸一会拒(§8.2);select+source 双闸皆过,更保真 |
|
||
| **`<report>`(A 类)** | `<report><display><search selectservice>` | crud + 合计行/金额列 | issummer=true→summaryFields、ismoney→number;selectservice→`/api/flow/{id}`;JOR reportfile/图表降级标注(B/C 类另案) |
|
||
| **group** | `<group><template tempid>` | tabs 壳 | 子模板跨引用,本批不联动 |
|
||
|
||
uitype 映射全集(客户库实测):TextField→input-text、TextArea→textarea、NumberField→input-number、
|
||
CheckBox→checkbox、ComboBox→select+字典 source、PopupDateField→input-date(time)、
|
||
DoublePopupDateField→input-date(time)-range、SelectDialog/MultiSelectDialog→select+source、
|
||
EditGrid/FormEditGrid→input-table、未知→input-text(降级标注)。
|
||
|
||
---
|
||
|
||
## 六、映射台账
|
||
|
||
- **规模**:全量 1,516 模板共登记约 **15,973 条**映射决策(每条= 一个字段/按钮/特性的映射或降级标注)。
|
||
- **载体**:逐模板的 mappingNotes(CLI 内存),CSV `分级清单.csv` 落每模板的台账条数与原因归类;
|
||
单模板完整台账可经 `GET /api/poc/amis-validate?template=<名>` 在线复现(PoC 既有接口)。
|
||
- **降级标注**:所有「做不到的字段/特性」均以 `[降级]` 前缀进台账并归三桶,CSV 「reasons」列可直接做人工抽检挑样。
|
||
|
||
---
|
||
|
||
## 七、与「人工抽检分级」的衔接(给人工抽检挑样建议)
|
||
|
||
1. **优先抽 SUCCESS 段做正例对拍**(259 个 crud):无降级,schema 应与旧 GRID 行为最接近,适合做转换正确性基线。
|
||
2. **PARTIAL 按降级原因分层抽**:
|
||
- 报表合计行(issummer,CSV 含 summaryFields 的 report)——**数值正确性必须人工核对**(报表迁移方案风险 2:算错数比难看严重)。
|
||
- SelectDialog/MultiSelectDialog 密集模板——验「数据源联动后」可用性,是后端 `/api/picker` 实现的验收样本。
|
||
- EditGrid 主子表模板(26 个)——验子表 input-table 渲染 + 后续 updateSubTable 保存联动。
|
||
3. **FAILED 27 个孤儿模板**:交客户定性(废弃归档 / 重建 / 仍在用),决策会红线 3,**需客户书面确认**后才知是否纳入切流分母。
|
||
4. **挑样工具**:`分级清单.csv`(UTF-8 BOM,Excel 可直接打开)按 grade/root/reasons 三列过滤即可成挑样清单。
|
||
|
||
---
|
||
|
||
## 八、产物清单
|
||
|
||
| 产物 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| 转换 schema(按模板 id 命名) | `转换产物/schema/{view_template_id}.json` | 1489 个(闸一通过的全部落盘) |
|
||
| 分级清单 | `转换产物/分级清单.csv` | 1516 行 + 表头:id/名称/type/根元素/分级/闸一/台账条数/原因归类 |
|
||
| 闸二冒烟结果 | `转换产物/闸二结果.json` | 逐样本判定 + 各类型汇总 |
|
||
| 转换器 | `src/main/java/.../TemplateToAmisConverter.java` 等 5 个类 | 分派/分级/uitype 映射/闸一 |
|
||
| CLI 跑批 | `BatchConvertCli`(可独立 java -cp 运行) | 只读连库 + 5435 ceshi 库硬守门 |
|
||
| 闸二冒烟脚本 | `gate2-smoke/{smoke.mjs,host.html}` | playwright + 本地 SDK,最小 HTML 宿主 |
|
||
|
||
复跑命令(JDK17):
|
||
```
|
||
mvn -pl platform-converter dependency:build-classpath -Dmdep.outputFile=/tmp/cp.txt
|
||
java -cp "target/classes:$(cat /tmp/cp.txt)" com.eip4.platform.converter.BatchConvertCli
|
||
cd gate2-smoke && npm install && npx playwright install chromium && node smoke.mjs
|
||
```
|
||
|
||
---
|
||
|
||
## 九、复跑/口径备注
|
||
|
||
- **只读红线**:CLI `conn.setReadOnly(true)`;URL 硬校验 dbname=postgres,连 dbname=ceshi 直接抛错拒启(5435 上不完整的 ceshi 库严禁连)。
|
||
- **dom4j getText**:脚本文本一律 `getText()` 保留 Groovy 换行(手册 §5.3),台账登记处已遵循。
|
||
- **闸一预处理唯一来源**:SchemaGate,避免「所有 ajv 校验处」(手册 §8.1)各写一份漂移。
|
||
- 单测 **24 个**(各段转换规则 + 闸一 + CLI 守门/归类),全模块 `mvn test` + ArchUnit 绿(10 模块 BUILD SUCCESS)。
|