claw/docs/superpowers/specs/2026-04-08-fault-details-report-operation-analysis.md

# fault-details-report 操作分析

## 1. 场景概述

`fault-details-report` 对应“故障明细”场景，目标表述为查询故障明细并生成包含明细与汇总分区的结构化报表。根据 `D:\data\ideaSpace\rust\sgClaw\claw\claw\skills\skill_staging\scenes\fault-details-report\scene.json`、`D:\data\ideaSpace\rust\sgClaw\claw\claw\skills\skill_staging\skills\fault-details-report\SKILL.md` 与 `D:\data\ideaSpace\rust\sgClaw\claw\claw\skills\skill_staging\skills\fault-details-report\scripts\collect_fault_details.js`，当前最强直接证据在于：已打包脚本明确了报表 artifact 的列结构、汇总 section 名称、空结果形态与 `status: "ok"` 默认值，证据等级：`code-confirmed`。

但同一批证据并没有展示真实浏览器页面抓取、请求触发、行级归一化或汇总派生的实际执行代码。也就是说，当前 packaged script 对 artifact schema / section template 的定义，明显强于对实时浏览器采集行为的证明，证据等级：`code-confirmed`。

## 2. 证据来源

本分析统一只使用四个证据等级标签：`code-confirmed`、`contract-defined`、`implementation intent exists but not rigorous / buggy`、`no direct evidence / candidate only`。其中，脚本直接定义的 artifact schema / section template 归入 `code-confirmed`；未见脚本直接实现的运行语义与下游动作，不拔高于其对应较弱标签。

1. `D:\data\ideaSpace\rust\sgClaw\claw\claw\skills\skill_staging\skills\fault-details-report\scripts\collect_fault_details.js`
   - 直接定义 `DETAIL_COLUMNS`、`SUMMARY_COLUMNS`、返回对象字段、空 `rows`、空 `sections[0].rows`、`status: "ok"`、`partial_reasons: []`，证据等级：`code-confirmed`。
2. `D:\data\ideaSpace\rust\sgClaw\claw\claw\skills\skill_staging\skills\fault-details-report\SKILL.md`
   - 说明预期工作流为读取时间范围、收集原始故障明细、按规范列顺序归一、派生汇总 sheet、返回 artifact；这是技能说明与目标运行契约，能证明意图与期望输出，但不能单独证明脚本已实现全部步骤，整体证据等级以 `contract-defined` 与 `implementation intent exists but not rigorous / buggy` 并存描述更严谨。
3. `D:\data\ideaSpace\rust\sgClaw\claw\claw\skills\skill_staging\scenes\fault-details-report\scene.json`
   - 定义场景输入为 `period`、依赖为 `browser` / `report-history` / `local-report-service`、动作包括 `query` / `collect-report` / `build-summary-section`，属于场景元数据定义，证据等级：`code-confirmed`。
4. `D:\data\ideaSpace\rust\sgClaw\claw\claw\skills\skill_staging\skills\fault-details-report\references\collection-flow.md`
   - 给出“读取开始结束时间、触发 repair-order query、收集明细、按 `excleIni[0].cols` 归一、派生 summary-sheet、再返回 artifact”的参考流程；它定义了预期采集语义，证据等级：`contract-defined`。
5. `D:\data\ideaSpace\rust\sgClaw\claw\claw\skills\skill_staging\skills\fault-details-report\references\data-quality.md`
   - 给出必填列、可空列、summary 派生期望、partial 规则与 empty/failure 区分，属于质量约束参考，证据等级：`contract-defined`。
6. `D:\data\ideaSpace\rust\sgClaw\claw-new\docs\superpowers\specs\2026-04-08-command-center-virtual-employee-inventory.json`
   - 已把该场景整理为 `workflow`、`result.key_fields`、`status_model` 与 `open_questions`，可作为当前 command-center 侧归纳结果，但其中部分内容是对 scene/skill/reference 的再整理，不应反向当作新实现证据；证据等级：`no direct evidence / candidate only`（仅限 inventory 不能单独证明 packaged script 已实现的部分）。

## 3. 实际入口与运行边界

实际入口已在 `scene.json` 中声明为浏览器场景 `index.html`，技能包工具名为 `fault-details-report.collect_fault_details`，artifact 类型为 `report-artifact`，这些都是当前仓库可直接定位的定义，证据等级：`code-confirmed`。

运行边界方面：

- 场景元数据只声明了 `inputs: ["period"]`，证据等级：`code-confirmed`。
- 参考流程却明确要求从页面 datetime range control 读取 `start` / `end` 时间，证据等级：`contract-defined`。
- 因而“外部统一输入叫 `period`，但页面真实业务输入更像 `startTime/endTime` 二元组”这一判断是当前最严谨的归纳，且 inventory 文件也把它列入 `open_questions`，证据等级：`implementation intent exists but not rigorous / buggy`。

还要强调：当前可直接运行的打包脚本并未包含浏览器操作、请求调用、页面解析或 localhost 导出调用代码，因此它的实际边界更接近“返回一个预定义空 artifact 的 schema stub”，而不是“已严格实现端到端浏览器采集器”，证据等级：`code-confirmed`。

## 4. 代码已证实的实际操作流程

当前代码真正能严格确认的流程只有以下最小闭环：

1. 调用 `collectFaultDetails(input)`。
2. 读取 `input.period || ""` 填入返回对象的 `period` 字段。
3. 将 `DETAIL_COLUMNS` 写入主表 `columns`。
4. 将空数组写入主表 `rows`。
5. 构造一个名为 `summary-sheet` 的 section，并写入 `SUMMARY_COLUMNS` 与空 `rows`。
6. 返回 `type: "report-artifact"`、`report_name: "fault-details-report"`、`status: "ok"`、`partial_reasons: []`。

以上每一步都能在 `collect_fault_details.js` 中直接定位，证据等级：`code-confirmed`。

至于以下操作：读取页面时间、触发 repair-order 查询、抓取故障行、归一字段、按明细派生汇总、判断 partial/empty/blocked、调用导出服务或报告日志服务，目前在 packaged script 中没有对应实现代码，只在 skill/reference 文本里出现，证据等级最多是 `contract-defined` 或 `implementation intent exists but not rigorous / buggy`，不能写成当前代码已证实的实际流程。

## 5. 标准化抽象流程

若为 command-center 做严格抽象，当前更合理的标准化流程应写成：

1. 解析外部任务输入。
2. 将业务时间范围映射到页面查询参数。
3. 执行浏览器态查询并收集故障明细行。
4. 按约定列顺序归一主表数据。
5. 基于明细结果派生 `summary-sheet`。
6. 生成 `report-artifact`。
7. 如有需要再执行导出/日志等下游动作。

其中第 6 步“生成具有主表+summary-sheet 的 artifact 结构”可由脚本直接支撑，证据等级：`code-confirmed`。第 2、3、4、5、7 步主要来自场景说明与 reference 文档，不是当前脚本已实现事实，证据等级应分别按 `contract-defined` 或 `implementation intent exists but not rigorous / buggy` 标注。

## 6. 输入、上下文与依赖

### 输入

- `period` 被 scene 元数据与脚本入参直接使用，证据等级：`code-confirmed`。
- “页面实际读取开始时间与结束时间”来自 `references/collection-flow.md` 和 `SKILL.md` 的 workflow 描述，证据等级：`contract-defined`。
- 因此 `period` 与 `startTime/endTime` 的关系当前并不严谨：很可能 `period` 只是上层统一抽象，而底层真实 collector 需要双时间字段，证据等级：`implementation intent exists but not rigorous / buggy`。

### 运行上下文

- 浏览器页面可访问、页面日期控件存在、会话已登录，来自 scene/inventory/reference 的联合描述，证据等级以 `code-confirmed`（元数据存在）和 `contract-defined`（具体语义）共同成立。
- `report-history`、`local-report-service` 被声明为依赖，但 reference 同时强调历史报告不是主数据源、localhost 服务是下游依赖，证据等级：`code-confirmed` 与 `contract-defined`。

### 依赖

- `browser`、`fault-detail-query-source`、`local-report-service` 等依赖名称或整理项可直接在 scene 或 inventory 中定位，证据等级：`code-confirmed`。
- `/a_js/YPTAPI.js`、`http://localhost:13313/ReportServices/*`、`faultDetailsExportXLSXS` 等更具体依赖来自 reference，证据等级：`contract-defined`。

## 7. 输出结构

当前输出结构是本场景最硬的直接证据。`collect_fault_details.js` 已直接定义：

- `type: "report-artifact"`
- `report_name: "fault-details-report"`
- `period`
- 主表 `columns` = `DETAIL_COLUMNS`
- 主表 `rows` = `[]`
- `sections[0].name = "summary-sheet"`
- `sections[0].columns = SUMMARY_COLUMNS`
- `sections[0].rows = []`
- `status = "ok"`
- `partial_reasons = []`

以上全部属于 `code-confirmed`。

但 `SKILL.md` 与 `data-quality.md` 还要求输出中体现 detail row count、summary row count、required column coverage、complete/partial status、missing columns、weak mappings、downstream failures 等诊断信息。除了 `status` 与 `partial_reasons` 字段壳子已经存在，其他诊断性内容并未在脚本中实现，证据等级：`implementation intent exists but not rigorous / buggy`。

## 8. 下游动作证据表

| 下游动作 | 当前证据 | 证据等级 | 严谨结论 |
| --- | --- | --- | --- |
| 生成 `report-artifact` 返回给上游 | `collect_fault_details.js` 直接返回对象 | `code-confirmed` | 已有稳定的 artifact 结构桩实现，但当前返回为空数据模板。 |
| 明细列顺序标准化 | `DETAIL_COLUMNS` 明确定义 | `code-confirmed` | 只能确认列 schema 被定义，不能确认真实行数据已按此顺序完成映射。 |
| `summary-sheet` 分区存在 | `sections` 中直接构造 `summary-sheet` | `code-confirmed` | 只能确认 section 模板存在，不能确认真实汇总派生逻辑已实现。 |
| 页面采集故障明细行 | 只在 `SKILL.md` / `collection-flow.md` 中描述 | `contract-defined` | 存在明确目标流程，但当前 packaged script 未直接证明已实现。 |
| 汇总派生 | 只在 `SKILL.md` / `collection-flow.md` / `data-quality.md` 中描述 | `contract-defined` | 有契约与质量要求，但没有脚本级派生代码证据。 |
| 导出 Excel | scene 依赖与 reference 提到 localhost export service | `contract-defined` | 这是下游依赖定义，不等于本 skill 当前已实际执行导出。 |
| 写报告日志 | scene 依赖 `report-history`，reference 提到 report-log | `contract-defined` | 只能确认体系中有该下游概念，当前脚本未直接实现日志写入。 |
| partial / empty / blocked 状态细分 | skill/reference 有规则，脚本固定 `status: "ok"` | `implementation intent exists but not rigorous / buggy` | 状态模型意图存在，但 packaged script 目前未严格承载这些分支。 |

## 9. 当前代码疑点 / 不严谨点

1. `period` 与 `startTime/endTime` 的建模不一致。scene 与脚本只保留 `period`，reference 却明确要求读取开始/结束时间；这会让 command-center 难以判断标准输入究竟是一段字符串还是两个独立时间字段，证据等级：`implementation intent exists but not rigorous / buggy`。
2. 脚本把 `status` 固定为 `"ok"`，但 reference 与 `SKILL.md` 明确区分 success / partial / empty / blocked；当前实现无法承载这些语义，证据等级：`code-confirmed` 对现状成立，而“应支持细分状态”属于 `contract-defined`。
3. `partial_reasons` 虽存在字段，但脚本没有任何填充逻辑，只能算 schema 占位，证据等级：`code-confirmed`。
4. `DETAIL_COLUMNS` 与 `SUMMARY_COLUMNS` 已定义，但没有任何从页面数据到列值的映射代码；“字段归一化能力已落地”不能成立，证据等级最多为 `implementation intent exists but not rigorous / buggy`。
5. 下游导出与日志在参考资料中存在，但当前 skill 脚本并未调用相关服务，因此“报表可直接生成 Excel”不能写成当前代码事实，证据等级：`no direct evidence / candidate only`（就 packaged script 内实际执行而言）。

## 10. 对 command-center 标准配置的修订建议

1. 将本场景输入从单一 `period` 修订为更严谨的双层表达：
   - 对外统一层可保留 `period` 便于路由；
   - 执行层建议显式展开 `startTime` / `endTime`。
   其中“需要展开”的结论来自 scene 与 reference 的冲突修正，证据等级：`implementation intent exists but not rigorous / buggy`。
2. 在标准配置里把“artifact schema 已明确、live collector 未证实”作为单独字段或备注保留，避免 command-center 误把 schema stub 当成已实现采集器，证据等级：`code-confirmed`。
3. 将 `summary-sheet` 标记为 `section template confirmed`，而不是 `summary derivation implemented`。前者是 `code-confirmed`，后者当前没有同等强度证据。
4. 状态模型建议分成两层：
   - `declared_status_model`: success / partial / empty / blocked，来源于 skill/reference，证据等级：`contract-defined`；
   - `implemented_status_behavior`: 当前仅看到固定 `ok` 成功壳，证据等级：`code-confirmed`。
5. 对下游动作增加 `evidence_note`，明确 report-export / report-log 目前主要来自场景与参考定义，不是当前 packaged script 已证实行为。

## 11. 最终严谨结论

关于 `fault-details-report`，当前最可靠的结论是：仓库已经具备一个明确的报表 artifact 模板实现，能够稳定返回故障明细主表列定义、`summary-sheet` 汇总分区模板、空结果数组以及基础状态字段，证据等级：`code-confirmed`。

但如果把结论提升为“已经实现真实浏览器故障明细采集、列归一化、汇总派生、导出与日志闭环”，则证据并不充分。相关行为主要存在于 `SKILL.md`、`references/collection-flow.md`、`references/data-quality.md` 与 scene 元数据中，能够证明的是目标流程与契约要求，而不是当前 packaged script 已严格完成这些逻辑。因此，本场景目前应被描述为“artifact schema / section template 定义强，live browser collection 行为证据弱”的 staged report scene，而不能被描述为已严谨落地的实时采集器。