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，而不能被描述为已严谨落地的实时采集器。