# Catalog 与 Treatment 首轮产品化迭代

> 状态：已实现的首轮讨论基线，供下一轮产品评审使用。本文不替代 `sql_catalog_demo_design_v2.md` 中的完整领域设计。

## 1. 本轮判断

Findings 页面解决的是“外部发现进入系统后，发生了多少、来自哪里、严重程度如何、是否首次出现”。Catalog 与 Treatment 不能继续复制同一套事件分析视图，而应承接发现后的两个不同管理问题：

- `Catalog Item` 是某个集群中一个 SQL Digest 的长期档案，回答“这个 SQL 长期发生过什么、当前如何处置、是否反复出现、曾经治理过什么”。
- `Treatment` 是一次明确的治理或干预过程，回答“这一次由谁处理、推进到哪里、使用了哪些证据、结论是什么、是否验证有效”。
- `Record` 同时承担结构化治理信息和 Markdown 分析笔记；Catalog 聚合自身及关联 Treatment 的 Record，Treatment 保留本次治理的 Record。
- `Timeline` 记录重要事实历史，不能替代 Record，也不能替代当前状态。
- `Timeline Event` 是审计事实，详情页 Timeline 是面向人的历史投影。连续、同源且语义一致的自动 Findings
  应聚合为可展开的 Signal Episode；判断、Treatment 里程碑和 Records 保持独立，系统同步事件默认降级到
  System 分类。任何聚合都不得删除原始事件或阻断对 Finding、Record、Treatment 的下钻。

因此，本轮没有新增另一套复杂领域对象，而是补齐现有对象的管理信号、列表信息架构和详情主次关系。

## 2. Catalog 要回答的问题

### 2.1 资产与状态

- 当前范围内登记了多少个 SQL Digest？
- 多少仍待分诊，多少正在治理，多少处于观察，多少已经形成终态处置？
- 严重程度分布如何？

### 2.2 待关注对象

- 哪些 Critical SQL 还没有 active Treatment？
- 哪些 SQL 最近七天反复被检出？
- 哪些档案没有 Owner？
- 哪些 SQL 在历史治理后又重新出现？

### 2.3 单个档案

- SQL Digest 与归一化 SQL 是什么？
- 24 小时、7 天、30 天和全历史的核心活动指标是什么？
- 当前处置状态是什么，是否有 active Treatment？
- 历史 Findings、Records、Treatments、Evidence 和 Timeline 分别是什么？

## 3. Catalog 页面结构

### 3.1 Catalog List

页面依次由四层组成：

1. 全局 Scope：限定 Organization、Cluster 或 Cluster Group。
2. Query Filters：搜索 Digest/SQL，并按状态、Severity、Owner、Active Treatment 过滤。
3. Catalog Portfolio：紧凑呈现档案状态、Severity 和待关注信号。
4. Catalog Items Table：用于逐项扫描和进入档案。

表格优先呈现：Digest、SQL、Severity、Status、Symptoms、Scope、Owner、近 7 天/全部 Findings、active/全部 Treatments、Records、最近 Finding、最近 Record、Reappeared Signal。

### 3.2 Catalog Detail

详情页首屏顺序为：

1. Metadata：当前状态、Severity、Scope、Owner、时间及关联数量。
2. SQL Identity：完整 Digest 和归一化 SQL，长 SQL 仅在自身容器中横向滚动。
3. SQL Performance History：以 Finding `observed_at` 为时间轴，首屏展示通用 SQL Activity 趋势；
   来源通过 `symptoms[].metric_keys` 显式绑定的指标按 symptom 分组，例如 `large_key_scan` 下的
   Total Keys 与 Processed Keys。只有命中该 symptom 的 Finding 进入对应曲线；缺失值保留为图表
   缺口，窗口汇总保留在 `All Metrics` Tab。
4. Catalog Decision：创建 Triage Record，并基于合格 Record 执行 Watch 或 No Action；需要干预时创建 Treatment。
5. Dossier Tabs：Timeline、Findings、Records、Treatments、All Metrics、Evidence。

## 4. Treatment 要回答的问题

### 4.1 周期成果与变化

- 过去一周为当前 Organization、Cluster 或 Cluster Group 启动了多少次治理？相比上一周如何？
- 过去一周有多少份优化建议已经明确交付给客户？相比上一周是增加还是减少？
- 过去一周关闭了多少 Treatment，其中多少以 Fixed 或 Improved 成功完成？具体是哪些？
- 周期开始和结束时各有多少 active backlog；新增、交付和关闭是否保持平衡？

### 4.2 流量与瓶颈

- 每天新增、交付建议和关闭的数量如何变化，是否出现新增持续高于消化的情况？
- 是否出现“新增越来越多，但给客户交付的建议没有同步增长”的情况？
- 当前 active Treatment 主要集中在哪些 Stage？各 Stage 的中位停留时间和最长停留时间是多少？
- 哪些 Stage 出现超过七天仍未流转的 Treatment，哪些 Observation 已到期？

### 4.3 当前治理组合

- 当前有多少 active Treatment，各自处于哪个阶段？
- 哪些 Treatment 在 Alignment，哪些已进入 Observation，哪些 Observation 已经到期？
- 哪些 active Treatment 没有 Owner，哪些需要立即跟进？
- 单个 Treatment 的关联 SQL、风险、Owner、最新进展、Record 数量和更新时间是什么？

### 4.4 单次治理过程

- 本次 Treatment 覆盖哪些 Catalog Items 和 Findings？
- 当前治理阶段是什么，可合法转移到哪些阶段？
- 分析、方案、客户同步、执行和观察记录是什么？
- 观察基线与结果是否支持所选 Outcome？

## 5. Treatment 页面结构

### 5.1 Treatment List

Treatment 一级页拆成互斥的 `List` 与 `Insights`，不再把当前工作列表和组织级汇报内容纵向堆在同一屏。

List 只承接逐条治理工作：Search、Owner、Assignee、Stage、State、Priority、Outcome、Observation Due
等筛选只控制 Treatment 明细；列表默认 active 优先，其中 Observation Due 优先，完成和取消历史排在
后面。Reporting Period 和 Comparison Period 不出现在 List，因为它们并不定义当前存量列表。

### 5.2 Treatment Insights

Insights 固定为三层：

1. `Scope + Reporting Toolbar`：Scope 限定 Organization、Cluster 或 Cluster Group；Reporting Period
   与可选 Comparison Period 决定事件统计周期；
2. `Governance Progress`：用一条紧凑指标带回答本周期最重要的结果问题，只保留 New、
   Recommendations Shared、Closed、Ending Backlog、Successful 和 Median Completion 六项；
3. `Treatment Analysis`：固定高度的分析工作区，通过 Trend、Distribution、Comparison 三个一级 Tab
   切换，不因内容不同导致页面跳动。

State、Stage、Owner 等 List 筛选不参与 Insights 的事件统计，避免吞吐和积压口径被无提示地缩小。
点击 Stage 分布会切换到 List，并带入对应的 active Stage 筛选。

`Treatment Analysis` 的职责严格划分为：

- `Trend / Throughput`：按天展示 New、Closed 和日末 Backlog，Tooltip 同时交代 Reopened，回答新增、
  重新进入和消化是否失衡。
- `Trend / Delivery`：按天展示 New、Recommendations Shared 和日末 Backlog，回答治理输入增加时，
  面向客户的建议交付是否同步增加。
- `Distribution / Current Stage`：展示当前 active 存量在五个 Stage 的分布、报告期内流入/流出、当前
  中位/最长停留时间、历史离开该 Stage 的中位耗时及注意信号；点击某一行后只看该 Stage 的 active
  Treatment，再次点击成组撤销 Stage 和 Active 条件。
- `Distribution / Active Age`：展示当前 active Treatment 从创建至今的年龄分布，用于识别长期积压。
- `Distribution / Started Cohort`：只取报告期内创建的 Treatment，并按报告期结束时所处 Stage/State
  分布，回答“这批新增目前推进到哪里”。
- `Distribution / Closed Outcomes`：只取报告期内关闭的 Treatment，按 Fixed、Improved、Failed、
  Cancelled 等 Outcome 分布，避免把“关单”直接等同于“成功”。
- `Comparison`：明确列出当前与基线的准确时间范围，并对比 New、Reopened、Shared、Closed、
  Successful、Backlog 和 Median Completion；右侧列出当前周期成功完成的具体 Treatment 与 Catalog
  Item，可直接下钻。

分析中必须明确区分三类统计对象：

| 类型 | 原子 | 时间语义 | 典型指标 |
| --- | --- | --- | --- |
| Flow | Timeline Event | 事件发生在报告周期内 | New、Reopened、Shared、Closed |
| Stock | Treatment 在某个时点的状态 | 当前时点或每日/周期结束时 | Backlog、Current Stage、Active Age |
| Cohort | 报告期内创建的一批 Treatment | 取该批对象在报告期结束时的状态 | Started Cohort |

Flow、Stock、Cohort 不能相加，也不能用当前 Stage 分布代替历史周期进展。Stage 和 State 同样必须
区分：State 表示 Treatment 是 Active、Completed 或 Cancelled；Stage 只定位 Active Treatment 当前
正在进行的工作。

表格不再将每个字段机械拆成独立列，而按用户判断任务组合为：

- `Treatment`：Treatment No、Title、Objective。
- `Catalog Item`：关联 SQL Digest 和归一化 SQL；可直接进入长期档案。多 SQL Treatment 显示主项和剩余数量。
- `Risk`：Severity、Priority。
- `Lifecycle`：active 阶段或终态，以及当前 Cycle。
- `Outcome`：终态结果；active Treatment 保持为空。
- `Attention`：Observation Due 或 Overdue。
- `Scope`：根据全局 Scope 上下文动态显示 Cluster 和 Organization。
- `Ownership`：Owner、Assignee。
- `Evidence`：关联 SQL、Findings、Records 数量。
- `Latest Activity`：最近 Record 和 Treatment 更新时间。

首屏优先保证 Treatment、Risk、Lifecycle、Outcome、Attention、Scope、Ownership 可见；Evidence
和 Latest Activity 通过表格自身的上下同步横向滚动查看。

Stage 语义固定为：

| Stage | 短释义 | 含义 |
| --- | --- | --- |
| Assessment | Confirm problem | 确认 SQL、证据、影响范围和干预必要性 |
| Planning | Design action | 定义变更、Owner、依赖、风险、步骤和成功标准 |
| Alignment | Agree change | 与必要干系人就变更、时间、职责和风险达成一致 |
| Execution | Apply change | 执行约定的 SQL、Schema、配置或应用变更并记录动作 |
| Observation | Validate result | 对比治理前后数据，收集证据并决定 Outcome |
| Completed | Close outcome | 记录 Outcome 和支撑结论后结束 Treatment |

### 5.2 Treatment Detail

详情页首屏顺序为：

1. Metadata：状态、阶段、Outcome、Severity、Owner、关联数量、周期和更新时间。
2. Objective and Success Criteria：明确本次 Treatment 要改变什么、如何判断成功。
3. Treatment Lifecycle：直接解释当前 Stage 和 State，只提供领域规则允许的下一阶段；不重复
   绘制完整单线流程。进入 Observation 仍必须通过 Observation Record。
4. Treatment Scope：前置展示本次治理覆盖的 Catalog Items，而不是埋在 Tab 中。
5. Process Tabs：Timeline、Records、Findings、Observation。

从 Treatment List 直接创建 Treatment 时不再自动选择第一条 Catalog Item，避免用户无意识地把治理过程关联到错误 SQL；从 Catalog Detail 创建时继续显式预填当前 Catalog Item。

## 6. 当前统计定义

所有 Finding 数量仅统计未逻辑删除的 Finding，并先应用当前页面 Scope 与 Query Filters。

| 指标 | 当前定义 |
| --- | --- |
| Needs Review | `current_posture.state` 为 `needs_review` 或 `reviewing` |
| Critical without Treatment | `current_posture.risk` 为 `critical` 且没有 active Treatment 的 Catalog Item |
| Recurring in 7d | 最近 7 天至少存在 2 条 Finding 的 Catalog Item |
| Reappeared | 历史治理后再次出现，且当前没有 active Treatment |
| New Treatments | `treatment_created` Timeline 事件发生在报告周期内的数量 |
| Reopened Treatments | `treatment_reopened` Timeline 事件发生在报告周期内的数量；它增加 Backlog，但不重复计为 New |
| Recommendations Shared | Proposal Record 首次同时满足 Reviewed、Customer Visible 时写入的 `recommendation_shared` 事件数量；同一 Record 后续修改不重复计数；active Treatment 若在 Assessment 或 Planning，则同时进入 Alignment，表达等待客户确认或执行 |
| Closed Treatments | 周期内 `treatment_completed` 与 `treatment_cancelled` 事件数量之和 |
| Successful Completions | 周期内完成且 Outcome 为 `fixed` 或 `improved` 的 Treatment |
| Backlog | 指定时间点已经创建或重新打开，且尚未完成或取消的 Treatment 数量 |
| Net Backlog Change | `周期结束 Backlog - 周期开始 Backlog`；由于包含 Reopened，不保证等于 New - Closed |
| Median Completion | 报告周期内 Completed Treatment 从首次创建到完成的中位耗时；Cancelled 不进入该指标 |
| Stage Age | `now - 当前 Stage 最近一次进入时间`；进入时间来自 Stage Transition、Reopen 或创建 Timeline 事件 |
| Treatment Cycle | active Treatment 为 `now - created_at`；终态 Treatment 为 `completed_at - created_at` |

默认基线是与当前周期等长且首尾相接的前一周期；完整自然月与上一个自然月比较，当月尚未结束时按
相同月内进度比较；用户也可以显式指定任意 Comparison Period。趋势按天聚合，并使用全局时区决定
日界线。以上定义是当前 MVP 的显式规则，不隐含 SLA。`Over 7d` 只是中性的注意信号，不等于
Stalled；在没有为不同 Stage 定义 SLA、Blocked Reason 和暂停规则前，系统不做“卡住”的强结论。

每一次 Treatment 创建、Stage Transition、进入 Observation、完成、取消与 Reopen 都必须写入
带领域动作发生时间的 Timeline Event。`updated_at` 只能表示实体最后写入时间，不能用于还原历史流转；
同一秒内存在多个动作时使用 Timeline 插入序号作为确定性次序，不能按随机 ID 排序。

## 7. 本轮补齐的 API 投影

Catalog Item 列表投影新增：

- `finding_count`、`finding_count_7d`、`finding_count_30d`
- `symptom_codes`
- `treatment_count`、`active_treatment_count`
- `record_count`、`latest_record`

Catalog Stats 新增：

- `posture_counts`、`attention_counts`、`risk_counts`、`needs_review_count`
- `critical_without_active_treatment_count`、`unowned_count`
- `recurring_7d_count`、`finding_count_7d`

其中 `needs_review_count` 与 Workbench 的待研判入口保持一致，包含 `needs_review`、
`reviewing` 和尚未开始研判的 `registered`。

Treatment 列表投影新增：

- `record_count`、`latest_record`
- `cycle_time_hours`
- `catalog_items`、`linked_sql_count`
- `stage_entered_at`、`stage_age_hours`

Treatment Stats 新增：

- `period`、`comparison_period`、`comparison_mode`、`summary`、`comparison`、`deltas`
- `time_series`：每日 New、Reopened、Recommendations Shared、Completed、Cancelled、Closed、Backlog
- `current_snapshot`：当前 active、终态、Observation Due、Unowned 和 Over 7d 存量
- `stage_health`：各 active Stage 的数量、中位/最长 Stage Age、周期流入/流出、离开 Stage 的中位耗时和注意信号
- `distributions`：当前 Active Age、报告期 Started Cohort、报告期 Closed Outcomes
- `successful_treatments`：当前周期内成功完成的 Treatment 与 Catalog Item 摘要

这些字段是服务端领域投影，避免各页面自行拼接并产生不一致口径。

## 8. 下一轮需要讨论的问题

1. Catalog Owner 是档案责任人、当前治理责任人，还是两者需要分开？
2. 一个 Treatment 在产品交互上是否应支持一次选择多个 Catalog Items；后端已支持，当前 UI 仍以一个主 Catalog Item 为入口。
3. Treatment 是否需要 Due Date、SLA、Blocked Reason，何时才可以把 Treatment 定义为 Stalled？
4. Catalog 的 Reappeared 应只基于“治理后再次检出”，还是还要区分 Regression、Known Recurrence 和 Observation Failure？
5. 来源特有 Metrics 的聚合语义由谁定义；当前首屏只使用稳定指标，完整来源指标不承诺都可以直接求和比较。
6. 是否需要单独记录客户 Acknowledged/Accepted；当前 `Recommendations Shared` 只证明已交付，不代表客户接受或执行。
7. 是否需要按 Owner 展示吞吐量、在手量与 Stage Age 分布；当前可以筛选，但还没有负责人横向比较。
8. Treatment 成效是否需要沉淀统一的延迟、CPU、成本等量化收益；当前 Success 由 Outcome 与证据门禁表达。