first commit

openspec/changes/init-promptcr-platform/specs/analysis-metrics/spec.md

@@ -0,0 +1,59 @@
+# Spec: analysis-metrics
+
+## ADDED Requirements
+
+### Requirement: 缺陷检出率（Recall）
+系统 SHALL 计算缺陷检出率：模型正确指出的预埋缺陷数 ÷ 预埋缺陷总数；模型输出与 Ground Truth 自动比对，位置命中 + 类型匹配视为检出。
+
+#### Scenario: 自动比对计算 Recall
+- **WHEN** 一个 run 的输出解析成功
+- **THEN** 系统与 Ground Truth 比对并计算该 run 的检出率
+
+### Requirement: 误报率（FPR）
+系统 SHALL 计算误报率：模型指出的"问题"中未命中任何预埋缺陷的比例。
+
+#### Scenario: 计算 FPR
+- **WHEN** 模型指出了若干问题项
+- **THEN** 系统计算其中未命中任何预埋缺陷的比例
+
+### Requirement: 审查覆盖率
+系统 SHALL 计算审查覆盖率：模型指出的问题行号对预埋缺陷行号的覆盖程度。
+
+#### Scenario: 计算覆盖率
+- **WHEN** 模型输出包含指出问题的行号
+- **THEN** 系统计算其对预埋缺陷行号的覆盖程度
+
+### Requirement: 建议可操作性（李克特五级量表）
+系统 SHALL 支持研究者按统一 rubric 对每条修复建议人工盲评打分（1 不可操作 / 2 方向性 / 3 部分可操作 / 4 基本可操作 / 5 完全可操作），并按"模型 × 提示词级别"聚合计算算术均值与各等级频数分布。
+
+#### Scenario: 录入并聚合李克特评分
+- **WHEN** 研究者在分析页录入某条建议的 1–5 分评分
+- **THEN** 系统保存评分并按模型 × 级别聚合输出均值与频数分布
+
+### Requirement: 输出稳定性
+系统 SHALL 计算输出稳定性：同一配置三次重复实验输出的一致性度量，具体为三次输出的指出项集合两两（共 3 对）Jaccard 相似度的平均值。
+
+#### Scenario: 三次重复稳定性
+- **WHEN** 同一配置的三个独立 run_id 均有结果
+- **THEN** 系统计算三个指出项集合两两 Jaccard 相似度并取平均值作为稳定性得分
+
+### Requirement: 统计分析
+系统 SHALL 提供描述性统计、方差分析（ANOVA）与配对 t 检验（pandas + scipy）。
+
+#### Scenario: 统计检验输出
+- **WHEN** 对实验结果发起统计分析
+- **THEN** 系统输出描述性统计、ANOVA 与配对 t 检验结果
+
+### Requirement: 论文用静态图
+系统 SHALL 用 matplotlib 生成交叉对比热力图、箱线图、分组柱状图，样式统一、支持中文显示、可直接插入学位论文。
+
+#### Scenario: 生成三类论文图
+- **WHEN** 研究者触发论文图表导出
+- **THEN** 系统产出热力图、箱线图、分组柱状图三类图片文件
+
+### Requirement: 前端数据接口
+系统 SHALL 以 JSON 形式向前端提供与静态图同口径的统计数据，供 ECharts 渲染交互图表；所有指标计算 MUST 在后端完成，前端 MUST NOT 内置业务计算。
+
+#### Scenario: 同口径 JSON 数据
+- **WHEN** 前端按模型/提示词级别/语言维度请求统计数据
+- **THEN** 后端返回同口径 JSON，前端仅做渲染与筛选交互