Files
eip4-platform/platform-converter/P4批量转换报告.md
zhengwr f563b472e6 P4-1 转换器线:扩 EDITFORM/主子表/树/选择窗/<report> 段 + 全量 1516 模板批量转换双闸分级
转换器扩展(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>
2026-06-11 16:27:49 +08:00

174 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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)。