244 lines
7.9 KiB
Markdown
244 lines
7.9 KiB
Markdown
# G1-E Light Enrichment Report Design
|
||
|
||
**Goal:** 定义 `G1-E 轻量补查汇总型` 的正式实现口径，使生成器能够在“单主请求 + 少量补查请求 + 单次汇总输出”的边界内，稳定恢复出可编译的业务语义，并与普通 `G1 single_request_table` 明确区分。
|
||
|
||
**Status:** Draft
|
||
|
||
---
|
||
|
||
## Decision Summary
|
||
|
||
1. `G1-E` 是 `G1` 的上边界子型，不是 `G6/G7/G8` 的过渡桶。
|
||
2. `G1-E` 只承接“主查询清晰、补查轻量、最终仍归并为单次汇总结果”的报表场景。
|
||
3. `G1-E` 的编译目标不是继续伪装成纯 `single_request_table`，而是显式生成“主请求 + 轻量补查 + 汇总整形”三段式契约。
|
||
4. `G1-E` 必须在证据层恢复三类对象：主请求证据、补查请求证据、汇总映射证据。
|
||
5. 当补查链路升级为宿主桥接 workflow、多 endpoint 盘点或本地落库分析时，必须 fail-closed 并重分类，不得继续生成 `G1-E` skill。
|
||
6. `高低压新增报装容量月度统计表` 作为当前 `G1-E` 的 P0 样板，用于冻结最小可编译答案。
|
||
|
||
---
|
||
|
||
## Why This Family Exists
|
||
|
||
当前 `G1` 的问题不只是“识别率不够”，而是把两类结构混在了一起：
|
||
|
||
1. 真正的单主请求单表报表。
|
||
2. 主请求之外还带少量补查、补齐、映射拼装的轻量汇总报表。
|
||
|
||
这两类场景都长得像“普通报表”，但第二类如果硬塞进 `single_request_table`，会导致以下问题：
|
||
|
||
1. 只能抽到主页面状态，抽不出真实业务请求。
|
||
2. 即使生成成功，也没有补查契约，运行结果不完整。
|
||
3. 生成器会误把补查型样本当成通用模板，继续污染 `G1` 家族。
|
||
|
||
因此需要把这类场景单独收束为 `G1-E`，既保留它们仍属于通用报表上边界的事实，又防止继续伪装成纯单请求报表。
|
||
|
||
---
|
||
|
||
## Canonical P0 Sample
|
||
|
||
当前 `G1-E` 的标准样板固定为：
|
||
|
||
- `高低压新增报装容量月度统计表`
|
||
|
||
该场景的结构特征是：
|
||
|
||
1. 存在清晰主查询入口：`getWkorderAll`
|
||
2. 存在少量补查请求：
|
||
- `queryElectCustInfo`
|
||
- `queryBusAcpt`
|
||
- `getBatchPerCust97`
|
||
3. 最终输出仍是单次统计汇总，而不是宿主驱动的多步任务，也不是本地落库分析后再出文档
|
||
|
||
`G1-E` 的第一阶段实现和验收都以这个样板为准，不在本阶段横向扩更多家族。
|
||
|
||
---
|
||
|
||
## Non-Negotiable Boundaries
|
||
|
||
### 1. `G1-E` 仍属于报表直生家族
|
||
|
||
`G1-E` 仍应保持“场景页面直接可恢复业务查询”的基本属性，不能引入以下结构：
|
||
|
||
1. 宿主桥接主导执行
|
||
2. callback 串联的显式多步 workflow
|
||
3. 多 endpoint 分类盘点后再统一聚合
|
||
4. `localhost` 落库、SQL 分析、文档导出等二段式后链路
|
||
|
||
### 2. `G1-E` 不是兜底分类
|
||
|
||
只有在主请求明确、补查数量受控、补查职责单一的情况下，才能进入 `G1-E`。
|
||
如果只是“看起来比 G1 复杂一些”，但证据无法收敛为轻量补查模型，就必须阻断并重新分流。
|
||
|
||
### 3. 编译输出必须显式表达补查链路
|
||
|
||
对于 `G1-E`，生成器不能再只输出一个模糊的“请求 + 表格”骨架。
|
||
输出结构里必须能看见：
|
||
|
||
1. 主请求是谁
|
||
2. 每个补查请求补的是什么
|
||
3. 补查结果如何并回主结果
|
||
|
||
---
|
||
|
||
## Family Definition
|
||
|
||
`G1-E 轻量补查汇总型` 的最小定义如下：
|
||
|
||
1. 存在一个可识别的主查询请求，负责拉取主列表或主统计结果。
|
||
2. 存在少量补查请求，数量通常为 `1-3` 个，且职责明确，不形成开放式 workflow。
|
||
3. 补查请求的触发方式可通过主结果行字段、固定上下文参数或有限枚举维度推导。
|
||
4. 最终输出仍为单次汇总表或单份统计结果，不依赖本地持久化再分析。
|
||
5. 页面整体仍可被视为“同一报表任务”，而不是多个独立业务流程拼接。
|
||
|
||
---
|
||
|
||
## Evidence Requirements
|
||
|
||
`G1-E` 至少需要恢复以下三层证据。
|
||
|
||
### 1. Main Request Evidence
|
||
|
||
必须恢复：
|
||
|
||
1. 主请求 endpoint
|
||
2. 主请求参数模板
|
||
3. 主请求响应路径
|
||
4. 主表字段或主结果字段映射
|
||
|
||
### 2. Enrichment Request Evidence
|
||
|
||
对每个补查请求，必须恢复：
|
||
|
||
1. 补查 endpoint
|
||
2. 触发条件
|
||
3. 关键入参来源
|
||
4. 返回字段中被消费的部分
|
||
|
||
### 3. Merge / Normalize Evidence
|
||
|
||
必须恢复：
|
||
|
||
1. 主结果与补查结果的关联键
|
||
2. 汇总列、补充列或映射列的生成规则
|
||
3. 最终输出字段与来源字段之间的映射关系
|
||
|
||
如果三层证据中任一层缺失到无法闭环，`G1-E` 应阻断，不得伪生成 runnable skill。
|
||
|
||
---
|
||
|
||
## Scene IR Contract
|
||
|
||
`G1-E` 的最小 `Scene IR` 不应再复用纯 `single_request_table` 的扁平结构，而应扩展为三段式：
|
||
|
||
1. `main_request`
|
||
- 主查询定义
|
||
2. `enrichment_requests[]`
|
||
- 补查请求列表
|
||
3. `merge_plan`
|
||
- 主结果与补查结果的并回、字段补齐与最终汇总规则
|
||
|
||
建议最小字段如下：
|
||
|
||
- `main_request.endpoint`
|
||
- `main_request.params`
|
||
- `main_request.response_path`
|
||
- `main_request.columns`
|
||
- `enrichment_requests[].endpoint`
|
||
- `enrichment_requests[].param_bindings`
|
||
- `enrichment_requests[].response_path`
|
||
- `enrichment_requests[].consumed_fields`
|
||
- `merge_plan.join_keys`
|
||
- `merge_plan.field_mappings`
|
||
- `merge_plan.aggregate_rules`
|
||
- `merge_plan.output_columns`
|
||
|
||
---
|
||
|
||
## Compiler Contract
|
||
|
||
`G1-E` 编译阶段至少应新增以下 gate：
|
||
|
||
1. `main_request_resolved`
|
||
- 主请求是否恢复完整
|
||
2. `enrichment_requests_resolved`
|
||
- 是否识别出所有必要补查请求
|
||
3. `merge_plan_resolved`
|
||
- 是否恢复出主补查并回规则
|
||
4. `g1e_scope_compatible`
|
||
- 是否仍处于轻量补查边界内，而没有越界为 `G6/G7/G8`
|
||
|
||
编译器行为要求如下：
|
||
|
||
1. 若 `main_request_resolved = false`，直接阻断。
|
||
2. 若补查请求疑似存在但 `enrichment_requests_resolved = false`，不得退化为 `G1` 成功。
|
||
3. 若 `merge_plan_resolved = false`，不得输出缺少并回逻辑的伪 skill。
|
||
4. 若检测到宿主桥接、多 endpoint 扫数、落库分析等越界特征，直接阻断并给出家族重排建议。
|
||
|
||
---
|
||
|
||
## Runtime Shape
|
||
|
||
`G1-E` 的运行时目标形态应固定为：
|
||
|
||
1. 先执行主请求
|
||
2. 基于主结果触发有限补查
|
||
3. 将补查结果并回主结果
|
||
4. 输出单次汇总结果
|
||
|
||
这里的“有限补查”必须可控：
|
||
|
||
1. 不能无限递归
|
||
2. 不能升级为宿主驱动式多步任务编排
|
||
3. 不能变成接口盘点扫描
|
||
|
||
---
|
||
|
||
## Failure Taxonomy
|
||
|
||
`G1-E` 第一版至少要显式区分以下失败类型：
|
||
|
||
1. `missing_main_request`
|
||
- 主请求未恢复
|
||
2. `missing_enrichment_request`
|
||
- 补查请求存在，但未恢复完整
|
||
3. `missing_merge_plan`
|
||
- 能看见主链和补查链，但并回关系不完整
|
||
4. `scope_upgraded_to_g6`
|
||
- 实际是宿主桥接多步查询
|
||
5. `scope_upgraded_to_g7`
|
||
- 实际是多接口盘点汇总
|
||
6. `scope_upgraded_to_g8`
|
||
- 实际是抓取落库分析出文档
|
||
|
||
---
|
||
|
||
## Acceptance Criteria
|
||
|
||
`G1-E` 第一阶段完成的标志不是“能产出某个 skill 目录”，而是以下条件成立：
|
||
|
||
1. `高低压新增报装容量月度统计表` 能稳定恢复主请求、补查请求和并回规则三段式语义。
|
||
2. 生成结果不再退化为只有 `page_state_eval`、`params=[]`、`requestEntries=[]` 的空壳。
|
||
3. 编译器不会再把缺失补查契约的结果误判为普通 `G1` 成功。
|
||
4. 当样本越界时，系统能够明确阻断并说明应转入 `G6/G7/G8`，而不是继续产出低质量 skill。
|
||
|
||
---
|
||
|
||
## Out of Scope
|
||
|
||
本 spec 当前不覆盖：
|
||
|
||
1. `G6 宿主桥接多步查询型` 的 workflow 建模
|
||
2. `G7 多接口盘点汇总型` 的多 endpoint 盘点框架
|
||
3. `G8 抓取落库分析出文档型` 的本地存储与文档生成后链路
|
||
4. `G1-E` 之外的大规模家族扩展
|
||
|
||
---
|
||
|
||
## Next Step
|
||
|
||
这份 spec 冻结后，下一步应直接派生对应实施计划，内容只围绕以下三个实现对象展开：
|
||
|
||
1. `G1-E` 证据层补齐
|
||
2. `G1-E` 三段式 `Scene IR` / compiler gate 落地
|
||
3. `高低压新增报装容量月度统计表` 的 P0 样板验证
|