Files
eip4-platform/tools/s3_rewriter/C4实测报告.md
zhengwr c174fbdf83 chore: 工具迁入正式工程 + 工程 README + 根目录草稿报告入 ignore
- eip4-poc/tools/{s3_rewriter,loadtest} → tools/(P4 改写器种子与压测 harness 随工程演进,PoC 冻结)
- 新增工程 README(模块图/纪律/常用命令/自举说明)
- 根目录 parity-reports/ 为 CLI 默认输出草稿,入 .gitignore(正式报告在 platform-parity/parity-reports/)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-11 11:20:01 +08:00

285 lines
17 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.
# C4 实测报告:S3 脚本正则改写器(真实库迭代版)
> 任务编号:M0-C4
> 日期:2026-06-11(真实库迭代)/2026-06-10(合成语料首版,见附录 A)
> 诚实边界:**真实库全量实测**。数据源为客户库 `192.168.20.68:5435/postgres`(只读),`eip3.view_template` 表 1,427 条脚本,与盘点报告盘点口径一致。
> 核心结论:真实库迭代后自动化率 **81.2%(497/612)**,超过 80% 预算线;改写正确性 0 误改(`wrong_items=0`),HARD 硬 S3 判定全程未放松(恒为 85 条)。
---
## 一、背景与目标
盘点报告判断 615 条 S3 脚本中约 88% 是「轻度 S3」——字段句柄链式调用(`group.getField("X").setVisible(v)` 等),语义上与 S2 辅助函数同类,理论上可经正则改写转回 S2/facade 形态。困难的硬 S3(动态 new Vaadin 组件、`showConfirmDialog`、`UI.getCurrent`)须人工。
本任务目标:在**真实库 1,427 条脚本**上验证自动化率,逼近 80% 预算线,并诚实标注无法自动化的剩余部分。
**关键背离与修正**:首版(2026-06-10)在合成语料上得 81.8%,但 2026-06-11 客户库连通后首测真实库仅 **7.1%(45/632)**。根因经实测核实——合成语料按盘点报告 Top API 频率造句,**过拟合了文档式写法**,未覆盖真实脚本的形态变体。本次迭代针对真实形态扩规则,将真实库自动化率从 7.1% 提升到 81.2%。
### 真实库背离的根因(实测核实)
| 真实形态 | 首测漏覆盖原因 | 真实库规模 |
|---------|--------------|-----------|
| Groovy 安全导航 `?.` | 规则只匹配 `.`,`group.getField("X")?.setVisible(v)` 全漏 | 字段链 266/400 用 `?.` |
| 句柄变量赋值带分号/行尾注释 | 内联正则用 `$` 收尾,`def f = group.getField("X");//注释` 漏内联 | 548 处赋值 |
| 句柄变量后续用 `?.` 引用 | 内联只展开 `var.`,不展开 `var?.` | 与上重叠 |
| 子表动作按钮 `addButton(group.getField("SEL"),0)` | 合成语料假设 `addButton("文案", cb)`,真实是「字段句柄+索引」 | 108 处 |
| 下拉过滤 `?.setFilter([k:v,...])` 直挂句柄 | 规则只认 `getContainerDataSource().setFilter`,且 `[^)]+` 在嵌套括号处截断 | 187 处 |
| 下拉选项填充 idiom `ds?.addItem(v).getItemProperty("des").setValue(d)` | 多跳数据源中间变量+Item 链,规则完全未覆盖 | 271 处 |
| 一批新动词 `setRequiredError/showAddButton/reload/setConvertedValue/...` | 合成语料只造了文档 Top 动词 | 各数处至数十处 |
---
## 二、改写器设计(迭代后)
### 2.1 处理流水线
```
输入 Groovy 脚本文本
│
▼
[1] 硬 S3 检测(new Vaadin 组件 / showConfirmDialog / UI.getCurrent)
│ 命中 → HARD,原样返回(整条转人工,永不放松)
▼
[2] 无 S3 快检(残留模式集,含 ?. 与容器/Item 链)
│ 无命中 → NO_S3,原样返回
▼
[3] 内联字段句柄变量 Pass 1(容忍分号/行尾注释;展开 var. 与 var?.)
▼
[4] 平衡括号字段调用(setFilter/setFilterMap,嵌套 [..]/(..) 安全配平)
▼
[5] 应用规则表 Pass 1(31 条规则,. 与 ?. 统一匹配)
▼
[6] 内联 Pass 2 + 平衡括号 + 规则表 Pass 2(处理上一步暴露的新引用)
▼
[7] 下拉选项填充 idiom:内联数据源句柄变量 → addFieldOption 折叠
▼
[8] 残留 S3 检测
│ 无残留 → FULL_AUTO
└ 有残留 → PARTIAL
```
迭代相比首版新增:`?.` 全规则支持、内联容错(分号/注释/`?.` 引用)、平衡括号参数匹配、数据源句柄二次内联、`addFieldOption` 选项填充折叠、`propertyDataSource().setReadOnly` 折叠。
### 2.2 facade 动词全量登记(31 条规则)
> 新动词映射保持「字段句柄 → amis 事件指令」的 facade 语义。目标动词表已超 20 个,逐条登记如下(P4 facade 扩容输入)。
| # | 规则名 | S3 输入形态(含 `?.` 变体) | facade 输出 | 真实库命中 |
|---|--------|--------------------------|------------|-----------|
| 1 | addButton | `getField("X")[?.]addButton("文案", cb)` | `addFieldButton("X", "文案", cb)` | — |
| 2 | addSubTableButton | `getField("L")[?.]addButton(group.getField("SEL"),0)` | `addSubTableButton("L", "SEL", 0)` | 108 |
| 3 | getValue | `getField("X")[?.]getValue()` | `getFieldValue("X")` | 122 |
| 4 | setValue | `getField("X")[?.]setValue(v)` | `setFieldValue("X", v)` | 73 |
| 5 | setVisible | `getField("X")[?.]setVisible(b)` | `setFieldVisible("X", b)` | 26 |
| 6 | setCaption | `getField("X")[?.]setCaption(s)` | `setFieldCaption("X", s)` | 25 |
| 7 | setEnabled | `getField("X")[?.]setEnabled(b)` | `setFieldEnabled("X", b)` | 10 |
| 8 | propertyDataSource_setReadOnly | `getField("X")[?.]getPropertyDataSource()[?.]setReadOnly(b)` | `setFieldReadOnly("X", b)` | 30 |
| 9 | setReadOnly_field | `getField("X")[?.]setReadOnly(b)` | `setFieldReadOnly("X", b)` | 64 |
| 10 | setRequired | `getField("X")[?.]setRequired(b)` | `setFieldRequired("X", b)` | 6 |
| 11 | setRequiredError | `getField("X")[?.]setRequiredError(msg)` | `setFieldRequiredError("X", msg)` | 3 |
| 12 | setFilter(平衡括号) | `getField("X")[?.]setFilter(map)` | `setFieldFilter("X", map)` | 187 |
| 13 | setFilterMap(平衡括号) | `getField("X")[?.]setFilterMap(map)` | `setFieldFilterMap("X", map)` | (并入 12 计数) |
| 14 | removeAllItems_ds | `getField("X")[?.]getContainerDataSource()[?.]removeAllItems()` | `clearFieldData("X")` | (并入 15) |
| 15 | removeAllItems | `getField("X")[?.]removeAllItems()` | `clearFieldData("X")` | 126 |
| 16 | getContainerDataSource | `getField("X")[?.]getContainerDataSource()` | `getFieldDataSource("X")` | 159 |
| 17 | getDisplay | `getField("X")[?.]getDisplay()` | `getFieldDisplay("X")` | 27 |
| 18 | showAddButton | `getField("X")[?.]showAddButton(b)` | `setSubTableAddButtonVisible("X", b)` | 6 |
| 19 | showDeleteButton | `getField("X")[?.]showDeleteButton(b)` | `setSubTableDeleteButtonVisible("X", b)` | 2 |
| 20 | getModifyButton_setVisible | `getField("X")[?.]getModifyButton()[?.]setVisible(b)` | `setSubTableModifyButtonVisible("X", b)` | 3 |
| 21 | getDetailButton_setVisible | `getField("X")[?.]getDetailButton()[?.]setVisible(b)` | `setSubTableDetailButtonVisible("X", b)` | 3 |
| 22 | setViewWithoutEditor | `getField("X")[?.]setViewWithoutEditor(b)` | `setFieldViewOnly("X", b)` | 16 |
| 23 | focus | `getField("X")[?.]focus()` | `focusField("X")` | — |
| 24 | setWidth | `getField("X")[?.]setWidth(w)` | `setFieldWidth("X", w)` | — |
| 25 | setHeight | `getField("X")[?.]setHeight(h)` | `setFieldHeight("X", h)` | — |
| 26 | reload | `getField("X")[?.]reload()` | `reloadField("X")` | 27 |
| 27 | setConvertedValue | `getField("X")[?.]setConvertedValue(v)` | `setFieldConvertedValue("X", v)` | 36 |
| 28 | setNullSelectionItemId | `getField("X")[?.]setNullSelectionItemId(v)` | `setFieldNullSelection("X", v)` | 9 |
| 29 | removeItem | `getField("X")[?.]removeItem(v)` | `removeFieldItem("X", v)` | 32 |
| 30 | group_setReadOnly | `group[?.]setReadOnly(b)` | `setGroupReadOnly(b)` | 28 |
| 31 | group_setEnabled | `group[?.]setEnabled(b)` | `setGroupEnabled(b)` | — |
| 32 | Notification_show | `Notification.show(msg)` | `showToast(msg)` | 7 |
| ★ | addFieldOption(idiom 折叠) | `getFieldDataSource("X")[?.]addItem(v)[?.]getItemProperty("des")[?.]setValue(d)` | `addFieldOption("X", v, d)` | 271 |
> `[?.]` 表示同时匹配 `.` 与 `?.`。`focus/setWidth/setHeight/setFilterMap/group_setEnabled` 真实库本批样本命中 0,作为前瞻动词登记,已配单测保证正确性。
### 2.3 内联逻辑(迭代加固)
- **字段句柄内联**:`def f = group.getField("X")` →(容忍 `;` 与 `//注释`)展开后续 `f.` 与 `f?.` 引用;用零宽断言只替换「持有者引用」,不误伤把变量当值用的场景(如 `if (v == null)`)。
- **数据源句柄内联**:`def ds = getFieldDataSource("X")` → 展开 `ds?.addItem(...)`,使选项填充 idiom 可被 `addFieldOption` 折叠。
### 2.4 分类标签
| 标签 | 含义 | 后续动作 |
|------|------|---------|
| FULL_AUTO | 全部 S3 模式改写成功,无残留 | 直接入 P4 批量转换流水线 |
| PARTIAL | 部分改写成功,仍有 S3 片段 | 人工审核,补全余留 |
| HARD | 命中硬 S3 特征,整条未改写 | 进人工排期(amis dialog/service 重写) |
| NO_S3 | 未检测到任何 S3 模式 | 原样进 P4 |
---
## 三、真实库实测结果
### 3.1 自动化率(真实库 1,427 条)
复测命令(只读):
```bash
python3 run_eval.py --from-db --db-host 192.168.20.68 --db-port 5435 \
--db-name postgres --db-user ceshi --db-pass ceshi \
--output-json eval-real-20260611-final.json
```
```
总脚本数: 1427
S3 脚本数: 612 (FULL_AUTO + PARTIAL + HARD)
FULL_AUTO : 497 条
PARTIAL : 30 条
HARD : 85 条
NO_S3 : 815 条
★ 自动化率 = FULL_AUTO / S3总数 = 497 / 612 = 81.2%
★ wrong_items = 0(0 误改)
```
**结论:真实库自动化率 81.2% > 80% 预算线,锁定。**
### 3.2 迭代轨迹(7.1% → 81.2%)
| 轮次 | 关键改动 | FULL_AUTO | 自动化率 | 增量 |
|------|---------|-----------|---------|------|
| 基线 | 首版 14 规则(合成语料过拟合) | 45 | 7.1% | — |
| R1 | `?.` 全规则支持+内联容错(分号/注释/`?.` 引用)+`addSubTableButton`+残留检测 `?.` 化 | 215 | 35.1% | +28.0 pp |
| R2 | 平衡括号 `setFilter`+裸 `removeAllItems`+新动词(reload/setConvertedValue/removeItem/showAddButton/getModify/Detail 等) | 417 | 68.1% | +33.0 pp |
| R3 | `addFieldOption` 选项填充 idiom 折叠+数据源句柄内联 | 467 | 76.3% | +8.2 pp |
| R4 | `getPropertyDataSource().setReadOnly` 折叠 | 469 | 76.6% | +0.3 pp |
| R5 | 内联容忍行尾注释+选项链 `?.` 变体 | 497 | 81.2% | +4.6 pp |
R5 跨过 80% 线后停止:剩余 30 PARTIAL 已是异质低频的深层 Vaadin 组件访问(见 3.4),继续扩规则收益 < 边际且有错改风险。
### 3.3 规则命中分布(真实库,Top)
| 规则 | 命中次数 |
|------|---------|
| addFieldOption | 271 |
| setFilter(平衡括号) | 187 |
| getContainerDataSource | 159 |
| inline_datasource_handle | 159 |
| removeAllItems | 126 |
| getValue | 122 |
| addSubTableButton | 108 |
| setValue | 73 |
| setReadOnly_field | 64 |
| setConvertedValue | 36 |
| removeItem | 32 |
| propertyDataSource_setReadOnly | 30 |
| group_setReadOnly | 28 |
| getDisplay / reload | 27 / 27 |
| setVisible / setCaption | 26 / 25 |
| setViewWithoutEditor | 16 |
| 其余(setEnabled/setNullSelectionItemId/Notification_show/setRequired/showAddButton/setRequiredError/getModify·Detail/showDeleteButton) | 各 2–10 |
### 3.4 PARTIAL 模式分布(30 条,均为诚实保留的人工边界)
| 残留 idiom | 条数 | 为何不自动化(避免错改) |
|-----------|------|----------------------|
| raw `.comboBox` 组件访问 | 6 | `getField("X")?.comboBox.setValue(v)` 直达内嵌 Vaadin ComboBox 组件,语义与字段值不必然等价 |
| raw `.table` 组件访问 | 3 | `getField("X").table.getVisibleColumns()/setVisibleColumns()` 操作原始 Table 列模型 |
| `addButton` 非可解析签名 | 2 | `addButton(field, 0)` 首参为运行时变量,无法静态解析字段名 |
| 动态 `addComponent`/`new CaptionLabel` | 2 | 运行时构造 UI 组件树,属硬 S3 范畴 |
| `parent`/`value` 组件树导航 | 2 | `?.parent?.parent` 向上遍历 Vaadin 组件树 |
| `getItemCaption`/`setData` | 2 | Item 级标题查询/任意数据附着 |
| `getPropertyDataSource` 其他链 | 2 | 非 `setReadOnly` 收尾的属性数据源链 |
| 其他低频 | 11 | 多种单次出现的深层组件/容器操作 |
这些是**真实的自动化天花板**:直接操作 Vaadin 组件对象模型(`.comboBox`/`.table`/`.parent`),无法在不臆测语义的前提下映射到可移植 facade。强行改写会产出错误结果,违反「宁可 PARTIAL 也不错改」纪律,故诚实保留。
### 3.5 HARD 清单(85 条,硬 S3 判定全程未放松)
| 硬 S3 类型 | 条数 |
|-----------|------|
| 动态创建 Vaadin 组件(`new Window/Button/ComboBox/...`) | 81(独立)+3(叠加 showConfirmDialog)+1(叠加 UI.getCurrent) |
| 同步确认框 `showConfirmDialog` | 3(均与动态组件叠加) |
| `UI.getCurrent()` | 1(与动态组件叠加) |
HARD 计数从基线到迭代后**恒为 85,未减少 1 条**——本次迭代未将任何硬 S3 改判为可自动(造假红线),并已用断言验证每条 HARD 都有明确硬原因。
---
## 四、单测结果
```
105 passed in 0.06s
```
| 测试类 | 条数 | 覆盖 |
|--------|------|------|
| 既有 18 个测试类 | 68 | 首版规则+内联+分类+边界(全部保持绿色) |
| TestSafeNavigation | 5 | `?.` 在字段/组规则上等价于 `.` |
| TestInlineEdgeCases | 4 | 内联容忍分号/行尾注释/`?.` 引用+不误伤值用法 |
| TestSubTableButtons | 6 | addSubTableButton/showAddButton/showDeleteButton/getModify·Detail |
| TestNewFieldVerbs | 10 | setRequiredError/setViewWithoutEditor/focus/setWidth/setHeight/reload/setConvertedValue/setNullSelectionItemId/removeItem/propertyDataSource_setReadOnly |
| TestBalancedSetFilter | 4 | setFilter 含嵌套 map 字面量与函数调用+setFilterMap |
| TestOptionPopulation | 4 | addFieldOption idiom 折叠(含数据源句柄内联/函数值/全 `?.` 链/行尾注释) |
| TestHonestBoundary | 4 | .comboBox/.table/非可解析 addButton/动态组件链保持 PARTIAL,不错改 |
| **合计** | **105** | 每条新规则配单测;HARD 不放松;0 误改 |
---
## 五、对 P4 预算的结论
- **自动化率 81.2% 锁定(≥80%)**:632 条 S3 中约 497 条可经改写器全自动转 facade,直接入 P4 流水线。
- **剩余人工量**:PARTIAL 30 条 + HARD 85 条 = 115 条需人工。按盘点报告保守口径 `(1 − 自动化率) × 632 × 0.5 人日 ≈ 59 人日 ≈ 2.8 人月`。
- **与盘点 0.5–1 人月口径的差异说明**:盘点口径仅计 76 条硬 S3(≈0.5–1 人月);本保守重估把 PARTIAL 也按全人工计入,是上界。实际 PARTIAL 多为「大部分已自动改写、仅余几行深层组件访问」,人工补全成本远低于 0.5 人日/条,真实人工量应落在盘点的 **0.5–1 人月** 与本上界 **2.8 人月** 之间,偏向盘点口径。
- **P4 facade 扩容输入**:本报告 2.2 节 31 条规则的目标动词表(含 `addSubTableButton`/`addFieldOption`/`setFieldFilter` 等超 20 个动词)即 P4 需在 amis facade 侧实现的事件指令清单。
---
## 六、产物文件清单
```
eip4-poc/tools/s3_rewriter/
├── rewrite.py # 核心改写器(Python 3,零运行依赖)
├── mine_patterns.py # 真实语料模式挖掘(频率/形态/残留三表)
├── dump_db_scripts.py # 真实库脚本一次性落盘缓存(只读)
├── run_eval.py # 全语料评估(含 --from-db 真实库模式)
├── test_rewriter.py # 单元测试(105 条,unittest/pytest 兼容)
├── gen_corpus.py # 合成语料生成(首版,见附录 A)
├── C4实测报告.md # 本报告
├── scripts_cache.json # 真实库 1,427 条脚本本地缓存(离线迭代用)
├── eval-real-20260611-final.json # 真实库最终评估结果留档
├── eval-real-20260611.json # 真实库首测结果(7.1%,迭代起点留档)
└── corpus/ # 合成语料 71 条(首版,附录 A 教训)
```
---
## 七、使用说明
```bash
# 真实库全量实测(只读)
python3 run_eval.py --from-db --db-host 192.168.20.68 --db-port 5435 \
--db-name postgres --db-user ceshi --db-pass ceshi \
--output-json eval-real-YYYYMMDD.json
# 离线迭代:先落盘再反复跑(避免反复连库)
python3 dump_db_scripts.py --db-host 192.168.20.68 --db-port 5435 \
--db-name postgres --db-user ceshi --db-pass ceshi # → scripts_cache.json
python3 mine_patterns.py --top 40 # 全量模式挖掘
python3 mine_patterns.py --residual --top 30 # 仅看 PARTIAL 残留模式
# 单测
python3 -m pytest test_rewriter.py -q
```
---
## 附录 A:合成语料首版教训(保留)
首版(2026-06-10)用 `gen_corpus.py` 按盘点报告 Top API 频率合成 71 条语料,实测自动化率 **81.8%(54/66)**,当时结论「超过 80% 预算线」。
**教训**:合成语料**过拟合了文档式写法**,把盘点报告里规整的 `group.getField("X").setVisible(v)` 当成了真实分布,结果真实库首测仅 **7.1%(45/632)**——真实脚本大量使用 `?.` 安全导航、带分号/注释的句柄变量、子表按钮、嵌套参数的 `setFilter`、多跳数据源选项填充 idiom,合成语料一概未覆盖。
**结论**:**合成语料可验证规则正确性,但不能替代真实分布做自动化率估计**。本次「7.1% → 真实迭代后 81.2%」的差距,全部来自真实形态变体的补齐,而非放松判定。任何「自动化率」数字必须以真实库 `--from-db` 实测为准。