Bkn report

报告生成

公约：../_shared/contract.md

做什么

汇总 pipeline 各阶段产物，生成结构化报告并归档。

输入

• pipeline：当前流程类型
• artifacts：各阶段产物（建模清单、绑定结果、测试结果、推送结果等）
• network_dir：归档目录

报告类型

类型	触发时机	内容
阶段报告	pipeline 中间节点	当前阶段摘要 + 下一步
最终报告	pipeline 完成	全流程回顾 + 产物清单 + 质量评分
测试报告	bkn-test 完成后	测试结果 + 覆盖率 + 通过率
诊断报告	validate pipeline 完成	检查结果 + 问题清单 + 修复建议

最终报告结构

1. 网络概览：名称、领域、对象数、关系数
2. 建模摘要：路径（A/B/C）、收敛轮数
3. 绑定摘要：绑定率、覆盖率、风险项
4. 对象类详情：每个对象的属性列表、主键、映射状态（关键内容）
5. 测试摘要：通过率、关键失败项
6. 业务规则：规则数、锚定对象数
7. Q&A 验证：通过率、验证路径
8. 问题与修复：pipeline 执行中遇到的问题及解决方案
9. 产物清单：文件路径列表

诊断报告结构

当 report_type: diagnosis 时生成，输出文件为 DIAGNOSIS_REPORT.md / DIAGNOSIS_REPORT.html：

1. 网络概览：名称、kn_id、来源（本地/pulled）、检查时间
2. 检查摘要：各阶段状态总览（pass/fail/skipped）
3. 门禁检查详情：每条门禁结果 + 不达标项明细
4. 预检详情：关系映射/动作绑定/concept_group 检查结果
5. 静态检查详情：schema_review 结果（如有）
6. 质量评分：综合分 + 各维度分 + 降级说明
7. 问题清单：按严重度排序的问题列表（critical/warning/info）
8. 修复建议：每条建议 + 目标 skill + 预估工作量
9. 后续行动：推荐路由（update/feedback）+ 用户可选路径

诊断报告输入来源：

• pipeline_state.yaml 中的 validation_result 字段
• 各阶段检查结果（gate_check、prepush_validation、static_check、quality_score）
• diagnosis 字段中的问题清单和修复建议

输出

1. Markdown 报告（必须）

• 文件：{network_dir}/reports/REPORT.md
• 用途：版本控制友好、方便 diff
• 内容：完整报告（上述 1–9 节）

2. HTML 报告（可选）

• 生成条件：references/report-template.html 模板存在时生成，不存在时跳过
• 模板：references/report-template.html
• 文件：{network_dir}/reports/REPORT.html
• 用途：可视化展示、直接浏览器打开
• 生成方式：读取模板，替换 {{placeholder}} 占位符
• 占位符映射：

占位符	数据来源
{{network_name}}	network.bkn → name
{{domain}}	network_context.domain
{{timestamp}}	当前时间
{{trace_id}}	ARCHIVE_ID
{{quality_score}}	bkn-review 评分（未执行写 N/A）
{{verdict_class}}	score >= 80 → pass, >= 60 → warn, < 60 → fail
{{score_rows}}	各维度评分行 <tr><td>维度</td><td>分数</td><td>权重</td></tr>
{{object_count}}	对象类数量
{{relation_count}}	关系类数量
{{binding_rate}}	绑定率
{{mapping_coverage}}	映射覆盖率
{{object_detail_rows}}	对象类属性详情（每对象一节，含属性表格 + Keys）
{{test_rows}}	测试结果行
{{rule_count}}	业务规则数
{{anchor_count}}	锚定对象数
{{qa_pass_rate}}	Q&A 通过率
{{artifact_list}}	产物路径 <li> 列表

诊断报告 HTML 占位符映射

当生成诊断报告（report_type: diagnosis）时，使用以下占位符：

占位符	数据来源
{{network_name}}	network.bkn → name 或平台查询结果
{{kn_id}}	network.bkn → kn_id 或平台查询结果
{{source}}	pipeline_state.yaml → source（local / pulled_from_platform）
{{check_timestamp}}	检查执行时间
{{trace_id}}	ARCHIVE_ID
{{gate_status}}	gate_check.status（pass/fail）
{{gate_rows}}	门禁检查结果行
{{prepush_status}}	prepush_validation.status（pass/fail）
{{prepush_errors}}	预检错误列表
{{static_check_status}}	static_check.status（pass/fail/blocked/skipped）
{{quality_score}}	bkn-review 评分
{{verdict_class}}	score >= 80 → pass, >= 60 → warn, < 60 → fail
{{score_rows}}	各维度评分行
{{problem_rows}}	问题清单行（按严重度排序）
{{fix_rows}}	修复建议行
{{routing_primary}}	diagnosis.routing_suggestion.primary
{{routing_reason}}	diagnosis.routing_suggestion.reason

{{object_detail_rows}} 生成格式

每个对象类生成如下 HTML 片段：

<div class="object-section">
  <h3>{{object_name}} <small class="meta">{{存储位置}}</small></h3>
  <table class="properties-table">
    <tr><th>Name</th><th>Display Name</th><th>Type</th><th>Mapped Field</th><th>Status</th></tr>
    <!-- 每个属性一行 -->
    <tr><td>{{property_name}}</td><td>{{display_name}}</td><td>{{type}}</td><td>{{mapped_field}}</td><td class="{{status_class}}">{{status}}</td></tr>
  </table>
  <p class="keys">Primary Key: {{primary_key}} | Display Key: {{display_key}}</p>
</div>

字段说明：

字段	来源
{{object_name}}	object_types/*.bkn → frontmatter.name
{{存储位置}}	对象清单 → 存储位置（platform / local），local 对象标注灰色
{{property_name}}	Data Properties 表格 → Name 列
{{display_name}}	Data Properties 表格 → Display Name 列
{{type}}	Data Properties 表格 → Type 列
{{mapped_field}}	Data Properties 表格 → Mapped Field 列（无映射写 -）
{{status}}	bkn-map 输出 → 映射状态（mapped / waived / blocked），仅 platform 对象显示
{{status_class}}	mapped → pass, waived → warn, blocked → fail
{{primary_key}}	object_types/*.bkn → Keys → Primary Keys
{{display_key}}	object_types/*.bkn → Keys → Display Key

local 对象处理：存储位置为 local 的对象，Mapped Field 列显示 -，Status 列不显示（无数据视图绑定），整体标注灰色样式。

约束

• 报告不编造数据，数值必须来自实际产物
• 归档路径遵循 _shared/contract.md 中的归档规则
• Markdown 报告为必须产物；HTML 报告在模板可用时生成，不可用时跳过并在 Markdown 报告末尾注明
• HTML 报告必须基于 references/report-template.html 模板生成，不可自行编写 HTML