# 线损家族新增变体最小合约表
> Date: 2026-04-18
> Scope: `docs/superpowers/plans/2026-04-18-lineloss-family-variant-expansion-plan.md`
> Purpose: 完成 Phase 2 交付物，明确新增线损变体的最小可用口径与候选验证门槛。

## 1. 设计原则

本表只定义“最低可生成”的合约，不直接承诺完整业务语义重建。原则如下：

1. 主合约只覆盖能稳定抽取的主链路。
2. 页面内计算、拼接、下钻逻辑如果尚不能稳态恢复，先作为扩展证据，不强行塞入主合约。
3. 无法满足主合约的样本继续 `fail-close`。

## 2. 合约表

### 2.1 `G2-D 预测计算型`

代表样本：

1. `线路月度高负损预测`
2. `台区线损台区月度高负损预测`

最小主合约：

1. `bootstrap`
   - 必须能定位到线损业务域 `gsllys`
   - 不要求额外外部系统联动
2. `primary evidence`
   - 存在预测型标识，如 `reportType` 中含预测语义
   - 页面内存在 `lineLossRate / powerLoss / lineLossType` 等计算结果字段
3. `request contract`
   - 至少识别一个主查询入口或主输入数据源
   - 若原页面由文件输入或多个表拼装触发，可先将其视为“single primary collection + local compute”
4. `response / column contract`
   - 至少恢复以下列中的 3 个以上：
     - `lineId`
     - `lineName`
     - `lineLossType`
     - `lineLossRate`
     - `powerLoss`
   - 必须恢复 `lineLossRate` 或 `powerLoss` 之一
5. `normalize contract`
   - 对计算结果过滤空值
   - 保证每条记录至少保留主键列和一个核心预测结果列

候选验证门槛：

1. 能稳定落到 `G2-D`
2. 生成结果中存在预测结果核心列
3. 不把这类场景误判为 `G2-A/G2-B/G2-C`

扩展证据，不计入主合约：

1. 复杂白名单逻辑
2. 多表 Excel 预处理
3. 全量预测规则完全复刻

### 2.2 `G2-E 核查对比型`

代表样本：

1. `台区零度户月度用电量与台区线损电量对比核查报表`

最小主合约：

1. `bootstrap`
   - 必须定位到线损主域 `gsllys`
2. `primary evidence`
   - 同时出现 `getUserElectricList` 与 `getTqLinelossInfoListRank`
   - 页面内存在按 `TG_NO` 或 `CONS_NO` 的拼接逻辑
3. `request contract`
   - 至少恢复主排名接口和用户电量接口
   - 主接口保留分页参数 `page / rows`
4. `response / column contract`
   - 至少恢复以下列中的 4 个以上：
     - `TG_NO`
     - `TG_NAME`
     - `consno`
     - `userNmae`
     - `thisMonth`
     - `beforeMonth1`
   - 必须同时具备一个台区维度列和一个用户维度列
5. `normalize contract`
   - 允许先以主链路行为单位输出
   - 允许暂不完整复刻所有拼接字段，但必须能看出“台区 + 用户”的双层语义

候选验证门槛：

1. 能稳定识别为核查对比型，而不是简单周报或双模式报表
2. 生成结果中保留 `TG_NO` 且保留至少一个用户维度字段
3. 关联补查证据写入 generation report

扩展证据，不计入主合约：

1. 多月历史字段完全展开
2. 所有异常兜底行填充逻辑
3. 报表导出标题文案完全一致

### 2.3 `G2-F 异常诊断 / 下钻型`

代表样本：

1. `线损大数据-窃电分析`

最小主合约：

1. `bootstrap`
   - 必须定位到线损主域 `gsllys`
2. `primary evidence`
   - 出现主筛选接口 `getTqLinelossInfoListRank`
   - 出现至少一个诊断或下钻接口：
     - `tqAutoDiagnoseAnalyse/search`
     - `stealElecAnalyse/getFlqdyhDetailList`
     - `stealElecAnalyse/userVoltsAndElecflowMoniter/search`
3. `request contract`
   - 至少恢复主筛选请求
   - 至少记录存在一个后续诊断请求
4. `response / column contract`
   - 至少恢复以下列中的 4 个以上：
     - `TG_NO`
     - `LL_TYPE_NAME`
     - `LOSS_PQ`
     - `LINELOSS_RATE`
     - `remark`
   - 若暂不能稳定恢复完整 `remark`，也必须显式标记为诊断链路未完备
5. `normalize contract`
   - 主表记录必须可输出
   - 诊断 remark 允许退化为部分诊断结果或空值，但不能伪造完整语义

候选验证门槛：

1. 能稳定识别该类为“主筛选 + 下钻诊断”链路
2. generation report 中能写出诊断接口证据
3. 若 `remark` 合约不完整，readiness 不能伪装成 A

扩展证据，不计入主合约：

1. 所有异常分类规则
2. 各类诊断 remark 拼接细节
3. 多轮异步诊断时序

## 3. 本轮实施结论

按当前最小合约成熟度排序：

1. `G2-D` 最适合先进入实现
2. `G2-E` 适合紧随其后
3. `G2-F` 先作为高复杂候选组，只有在主链路实现稳定后再推进

因此，Phase 3 的实现顺序固定为：

1. 先扩 `G2-D`
2. 再扩 `G2-E`
3. `G2-F` 仅保留为候选扩展或回归观察对象