# Overview 三层结构与 AI 效果口径

## Current Design

- MySQL ticket snapshot、最新 initial job/run、`/ao` feedback 和 answer evaluation 是 canonical source。
- `ticket-analytics.ts` 将 canonical facts 投影到 Base `Tickets` 表；Dashboard 只读取 Base，不反向计算或写回事实。
- 当前 `AI Effect` 混合人工 `/ao` 评价与自动 AI-vs-人工评估，而且把 `revise` 计为不可接受，导致比例和分布不可解释。

## Risks

- 同一条记录同时有 `/ao` feedback 与自动评估时，必须由人工反馈覆盖自动评估。
- “没有 ao”指没有 `/ao` 人工评价，不代表 ticket 没有进入 Auto-oncall；AI 效果图仍只统计当前进入 Auto-oncall 的记录。
- 当前非 L1 ticket 不得进入处理原因、AI 效果或差场景归因。

## Target Contract

- `AI Evaluation Source`：优先 `/ao 人工评价`；无 feedback 且有有效 verdict 时为 `后续 AI-vs-人工评估`；否则 `待评价`。
- `AI Effect` 使用来源限定 ID，避免人工 `/ao` 与 LLM review 混淆：
  `ao: accept/revise/wrong/human`；自动 verdict 使用
  `llm_review: 比人工好/与人工相当/不同但有效/比人工差`；无结果为
  `待评价`。人工反馈仍优先覆盖自动 verdict。
- `AI Acceptable Value`：`accept/revise` 为 1，`wrong/human` 为 0；无人工反馈时，`ai_better/equivalent/different_but_valid` 为 1，`human_better` 为 0，未评价为 null。
- `Manual Evaluation Value`：存在 `/ao` feedback 为 1，否则为 0。
- `Auto-handled Rate Value` 与 `AI Acceptable Value` 保持 0/1 计算契约；
  新增 `Auto-handled Percent Value` 与 `AI Acceptable Percent Value`，只为
  Base 指标卡提供 0/100 展示值。Dashboard 对 0～1 的平均值按整数展示，
  会把 `0.55`、`0.588` 都错误显示为 `1`，因此不能直接用原始比例字段。
- `L1 Auto-handled Percent Value` 对当前 L1 ticket 投影 0/100，用于计算
  整体自动处理率；`Auto-handled Percent Value` 继续只对 Coverage 已放行
  ticket 投影，用于计算流程内自动处理率。两张卡的分母分别为当前 L1
  和进入 Auto-oncall 的 ticket，不能混用。
- 除 `L1 Auto-handled Percent Value` 外，上述流程内处理率和 AI 效果字段
  只对当前 `Coverage Admitted Value = 1` 的记录投影；当前未进入
  Auto-oncall（包括非 L1）的记录不得进入后续效果归因。
- Overview 固定三层：核心信息；处理情况；AI 效果。统一使用“进入 Auto-oncall”命名。
- AI 效果区同时包含当前效果分布，以及按 `Ticket Week + AI Effect`
  分组计数的周变化图。

## Implementation Steps

1. 先增加本地投影契约测试。
2. 修改 `ticket-analytics.ts` 的评价来源、效果标签、可接受率和人工评价数量字段。
3. 在 Base 创建字段并回填 `Tickets` 表。
4. 更新两个指标卡使用 0/100 展示字段，标题明确 `%`；只新增 AI
   效果周变化图，不删除或重建现有组件，不调用 `dashboard-arrange`，
   保留用户手工布局。

## Verification Checklist

- `revise` 的 `AI Acceptable Value` 为 1。
- 人工反馈覆盖自动 verdict，来源标记为 `/ao 人工评价`。
- 无人工反馈时，自动 verdict 决定效果和可接受值。
- 自动处理率和 AI 可接受比例的原始计算仍分别为 0/1 平均值；指标卡
  展示值为对应的 0/100 平均值，不再显示为 `1`。
- 自动处理率使用当前 L1 作为分母；流程内自动处理率使用 Coverage 已
  放行 ticket 作为分母。
- Overview 顶部为漏斗、自动处理率、AI 可接受比例。
- 处理区名称统一，未处理原因和处理类型只统计当前 Auto-oncall 口径。
- AI 区展示人工评价数量、效果分布、可接受率周趋势和效果差场景。
- AI 区新增 `Ticket Week` 为横轴、`AI Effect` 为系列的周变化图。

## Non-goals

- 不改变 poller/worker gate、Jira 写入、自动化开关或生产部署。
- 不从 Dashboard 或日报告反向生成 canonical 数据。
- 不为历史非 L1 ticket 保留效果归因 fallback。