claw/docs/superpowers/reports/2026-04-18-lineloss-family-minimum-contract-table.md

线损家族新增变体最小合约表

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 仅保留为候选扩展或回归观察对象