remove unused spec

2026-08-22 13:12:56 +02:00 · 2026-08-01 18:17:29 +08:00
parent be83c727ec
commit 8d45860170
5 changed files with 11 additions and 491 deletions
@@ -85,11 +85,10 @@ v0.6.0 保持三个固定角色：
 3. Playbook 执行可观测性和控制。
 4. Custom Variables。
 5. Worker Health。
-6. Integration Health。
-7. SLA 管理，待详细讨论。
-8. AI 质量评估，待详细讨论。
-9. 抑制规则，待详细讨论。
-10. Operations 页面整合，待详细讨论。
+6. SLA 管理，待详细讨论。
+7. AI 质量评估，待详细讨论。
+8. 抑制规则，待详细讨论。
+9. Operations 页面整合，待详细讨论。

 SLA、AI 质量评估和抑制规则都是 v0.6.0 正式发布的阻断项，但必须限制为最小可用闭环。

@@ -6,14 +6,13 @@ Status: Confirmed

 让 Admin 不依赖 Docker CLI 或日志文件，就能判断后台 Worker 是否存活、正在做什么、是否失败以及业务积压情况。

-v0.6.0 最终监控六个逻辑 Worker：
+v0.6.0 最终监控五个逻辑 Worker：

 1. Agentic Module。
 2. Case Analysis。
 3. Playbook。
 4. ELK Action。
 5. Dashboard Cache。
-6. Integration Health。

 监控粒度是逻辑进程类型，不是每个 Module/Playbook definition，也不是 Docker container ID。

@@ -115,7 +114,7 @@ Worker 启动：
 5. 启动 heartbeat thread。
 6. 进入主循环。

-这适用于所有六个正式 Worker。`--once` 是运维命令，不应长期占用 singleton lease；如果它会与正式 Worker 并行影响同一数据，需要显式决定是否短暂获取 lease，默认建议获取以避免并发。
+这适用于所有五个正式 Worker。`--once` 是运维命令，不应长期占用 singleton lease；如果它会与正式 Worker 并行影响同一数据，需要显式决定是否短暂获取 lease，默认建议获取以避免并发。

 ## 6. States

@@ -218,12 +217,6 @@ class WorkerIterationResult:
 - configured interval。
 - cache missing 标记。

-### Integration Health
-
- enabled target count。
- Healthy/Unhealthy/Disabled counts。
- current serial check progress（如果可安全获得）。
-
 Backlog 查询失败不应使 heartbeat 消失。API 行级 diagnostics 可返回 safe warning。

 ## 9. Error safety
@@ -290,7 +283,7 @@ Redis health storage 无法访问：

 - HTTP 503。
 - 固定信息：`Worker health monitoring is unavailable.`
- 不返回六个伪造 Down 状态。
+- 不返回五个伪造 Down 状态。

 API 不提供：

@@ -333,15 +326,14 @@ API 不提供：

 ## 14. Compose changes

- 新增 Integration Health Worker 服务。
- 六个 Worker 使用明确 command 和 log role。
+- 五个 Worker 使用明确 command 和 log role。
 - 不挂载 Docker socket。
 - 不通过 Web app 重启容器。
 - Worker singleton 冲突应在日志中明确显示。

 ## 15. Acceptance criteria

-1. 六类 Worker 正常显示 Starting→Idle/Running。
+1. 五类 Worker 正常显示 Starting→Idle/Running。
 2. 第二个同类型实例拒绝启动。
 3. heartbeat 10 秒、30 秒过期行为正确。
 4. 长 Running 任务保持 heartbeat，不被判 Stalled/Down。
@@ -1,355 +0,0 @@
-# Integration Health
-
-Status: Confirmed
-
-## 1. Purpose
-
-通过独立定时 Worker 主动验证正式支持的外部集成和关键依赖，并在 Admin Operations 页面展示每个配置实例的当前状态。
-
-该功能表达“最近一次轻量检查是否成功”，不保证所有业务查询、数据权限或具体动作都可用。
-
-## 2. Targets
-
-定时检查：
-
- Splunk singleton config。
- ELK singleton config。
- 每个 enabled OpenAI-compatible LLM Provider。
- AlienVault OTX。
- OpenCTI。
- LDAP。
- Redis。
- S3-compatible object storage。
-
-不检查 PostgreSQL；Web/API 本身已依赖 PostgreSQL。
-
-大量 EnrichmentProvider 枚举值不等于可检查的官方集成。
-
-## 3. Dedicated Worker
-
-新增 `run_integration_health_worker`：
-
- 使用公共 `run_worker()`。
- 作为第六类 singleton Worker 出现在 Worker Health。
- 固定每 5 分钟检查一次。
- 串行检查目标。
- 单目标超时 10 秒。
- 单项失败后继续其他目标。
- iteration 中任一失败使 Integration Health Worker 本轮 `failure_count > 0`，因此 Worker 状态 Degraded。
-
-页面加载不直接 fan-out 外部请求。
-
-## 4. States
-
-持久状态只有：
-
- Healthy
- Unhealthy
- Disabled
-
-附加 reason 表达细节：
-
-| Situation | State | Reason |
-| --- | --- | --- |
-| enabled, never checked | Unhealthy | never_checked |
-| check running | 保持原状态 | transient `checking=true` |
-| last check succeeded | Healthy | ok |
-| last check failed | Unhealthy | normalized failure code |
-| config disabled | Disabled | disabled |
-| config incomplete/not configured | Disabled | not_configured |
-
-不使用 Unknown/Degraded/Checking 作为持久 state。
-
-未配置和 Disabled 是中性状态，不算健康也不算故障。页面不计算整体 platform/integration status。
-
-## 5. Data model
-
-建议模型 `IntegrationHealth`：
-
-| Field | Type | Notes |
-| --- | --- | --- |
-| id | UUID | primary key |
-| integration_type | string enum | splunk/elk/llm/otx/opencti/ldap/redis/storage |
-| config_object_id | nullable string | LLM Provider UUID；singleton/dependency 使用稳定 sentinel |
-| display_name | string | safe display label |
-| state | enum | Healthy/Unhealthy/Disabled |
-| reason_code | string | normalized |
-| message | string | fixed safe message |
-| checking_started_at | nullable datetime | transient check marker |
-| last_checked_at | nullable datetime | any completed check |
-| last_success_at | nullable datetime | successful check |
-| last_failure_at | nullable datetime | failed check |
-| duration_ms | nullable integer | latest check |
-| consecutive_failures | nonnegative integer | reset on success |
-| updated_at | datetime | auto |
-
-Constraints:
-
- unique `(integration_type, config_object_id)`，null/sentinel 处理必须稳定。
- index `(state, integration_type)`。
- 不保存完整 config、URL、username、Secret、response body。
-
-只保存当前状态，不保存历史行或趋势。
-
-## 6. Configuration synchronization
-
-### Create
-
- 新 enabled config：创建 Unhealthy/never_checked。
- 新 disabled config：创建 Disabled/disabled。
-
-### Update
-
-相关配置字段改变：
-
- Enabled：立即 Unhealthy/configuration_changed。
- Disabled：Disabled/disabled。
- 不保留旧 Healthy 到下一个检查。
-
-现有 Settings 保存逻辑应在同一 transaction commit 后同步 health 状态。
-
-### Delete
-
- 多实例配置（例如 LLM Provider）删除时同步硬删除 health row。
- singleton config 不删除；Disabled 时保留 Disabled row。
- 配置 CRUD 自身继续由现有 AuditLog 追溯。
-
-## 7. Check depth by target
-
-### LLM
-
- 对每个 enabled Provider 发最小 Chat Completions 请求。
- 验证 base URL、认证、model 和实际推理路径。
- 限制最大 token，接受每 5 分钟极低但非零费用。
- 不保存 prompt/response content。
-
-### Splunk
-
- 使用轻量认证管理/信息接口。
- 不执行 SPL。
- 不依赖 index、time field 或数据存在。
-
-### ELK
-
- 使用集群 info/health 或等价轻量认证接口。
- 不搜索用户 index。
- 不将 yellow 等集群业务状态自动扩展为复杂 Degraded；检查器应按能否满足现有连接需求返回 Healthy/Unhealthy，并在 reason code 中规范化。
-
-### LDAP
-
- 连接服务器。
- 使用配置的 bind DN/password 进行 service bind。
- 验证 search base 可访问。
- 不保存或使用专用普通用户测试密码。
- 没有 bind DN 时执行当前支持模式下可行的基础连接/search check。
-
-### OTX/OpenCTI
-
- 调用轻量身份/账户 endpoint。
- 验证 Token。
- 不执行 IOC 搜索。
-
-### Redis
-
- PING。
- 读取安全的基础 INFO：版本、内存、连接状态。
- 不写测试 key。
- 不重复 Module stream backlog diagnostics。
-
-### Object storage
-
- 验证 endpoint、凭据和目标 bucket metadata/list 权限。
- 不写入或删除 probe object。
-
-## 8. Check service contract
-
-统一内部结果：
-
-```python
-@dataclass(frozen=True)
-class IntegrationCheckResult:
-    success: bool
-    reason_code: str
-    message: str
-    duration_ms: int
-```
-
-规范 reason_code 至少包括：
-
- ok
- never_checked
- configuration_changed
- not_configured
- disabled
- authentication_failed
- timeout
- tls_error
- connection_refused
- dns_error
- invalid_response
- permission_denied
- service_unavailable
- unknown_error
-
-message 必须来自固定映射，不直接使用 exception message。
-
-## 9. State update rules
-
-检查开始：
-
- 设置 checking_started_at。
- 不改变当前 state。
-
-成功：
-
- state=Healthy。
- reason_code=ok。
- last_checked_at/last_success_at=now。
- consecutive_failures=0。
- 清空 checking_started_at。
-
-失败：
-
- 第一次失败立即 state=Unhealthy。
- last_checked_at/last_failure_at=now。
- consecutive_failures += 1。
- 保存 normalized reason/message。
- 清空 checking_started_at。
-
-Worker 崩溃遗留 checking_started_at 时，下次 Worker 可覆盖；持久 state 仍是上一次结果。
-
-## 10. Manual Settings tests
-
-保留现有各配置页 Test：
-
- 用于测试未保存或已保存配置。
- 已保存配置的 Test 结果更新对应 IntegrationHealth。
- 未保存临时配置的 Test 不更新 health。
- Manual Test 继续写现有 AuditLog。
- Unified Integration Health 页面不提供 Check Now。
-
-普通业务调用的成功/失败永不更新 IntegrationHealth，避免查询输入、限流或业务权限错误污染集成状态。
-
-## 11. API
-
-建议：
-
-`GET /api/settings/operations/integrations/`
-
-仅 Admin。
-
-返回每个目标/配置实例的独立状态：
-
-```json
-{
-  "results": [
-    {
-      "integration_type": "llm",
-      "config_object_id": "...",
-      "display_name": "OpenAI Production",
-      "state": "Healthy",
-      "reason_code": "ok",
-      "message": "The provider responded successfully.",
-      "checking": false,
-      "checking_started_at": null,
-      "last_checked_at": "...",
-      "last_success_at": "...",
-      "last_failure_at": null,
-      "duration_ms": 821,
-      "consecutive_failures": 0,
-      "settings_route": "/system/llm-providers/..."
-    }
-  ]
-}
-```
-
- 不返回 overall status。
- 不返回 Secret、完整 endpoint、username 或 response preview。
- API 只读取 PostgreSQL，不执行检查。
- Redis target 的健康状态也是定时检查结果；与 Worker Health Redis 503 是不同语义。
-
-## 12. Error safety
-
-UI/API 只显示：
-
- normalized reason code。
- 固定安全 message。
- check time/duration。
-
-禁止：
-
- 原始 exception。
- traceback。
- response body。
- URL query。
- username。
- API key/token/password。
-
-完整异常进入 Integration Health Worker log，仍需遵循现有日志 Secret 规范。
-
-## 13. Permissions and audit
-
- 仅 Admin 可看 API/UI。
- User/Viewer 403。
- Scheduled check 不写 AuditLog。
- 定时状态变化不写 AuditLog。
- Manual saved-config Test 写现有 AuditLog。
- 不发送 Inbox/Webhook 健康通知。
-
-## 14. Frontend
-
-位置：`System Settings → Operations → Integration Health`。
-
- 与 Worker Health 独立表格/API。
- 每 30 秒读取 PostgreSQL 当前状态。
- 提供页面手动 Refresh，但不触发外部检查。
- 展示 integration type/name/state/reason/last check/duration/consecutive failures。
- Disabled/Not configured 可见且使用中性样式。
- enabled never checked 显示 Unhealthy + Never checked。
- checking 时保留原 state Tag并显示 Checking 辅助标记。
- 行可跳转对应 Settings 页面。
- 不显示 overall status。
- 不提供 Check Now。
-
-## 15. Worker Health interaction
-
-Integration Health Worker 自身：
-
- 使用第六个 Worker type。
- heartbeat/lease 遵循 Worker Health Spec。
- 本轮任一集成失败时 WorkerIterationResult.failure_count > 0，Worker Health 显示 Degraded。
- Integration 表显示具体失败目标。
- Redis health target 失败可能同时导致 Worker 心跳不可用；此时 Worker Health API 可能 503，但 PostgreSQL 中最后 Integration Health 结果仍可显示。
-
-## 16. Migration
-
- 创建 IntegrationHealth 表。
- 为现有配置生成初始行：
-  - enabled/configured → Unhealthy/never_checked。
-  - disabled/incomplete → Disabled。
- 不在 migration 中访问外部服务。
- 添加 Integration Health Worker Compose service。
- 更新 log role mapping。
-
-## 17. Acceptance criteria
-
-1. Worker 每 5 分钟串行检查所有 eligible targets。
-2. 每项超时 10 秒，失败不阻止后续目标。
-3. 各目标使用已确认的轻量检查深度。
-4. enabled 首次检查前 Unhealthy/never_checked。
-5. 一次失败立即 Unhealthy，一次成功立即恢复。
-6. config 修改立即 configuration_changed。
-7. saved-config Test 更新状态，unsaved Test 不更新。
-8. 业务请求不更新状态。
-9. 删除 LLM Provider 同步删除 health row。
-10. API 不执行外部请求、不返回敏感信息。
-11. Admin-only 和 30 秒 UI 刷新正确。
-12. Worker 自身出现在 Worker Health。
-
-## 18. Known tradeoffs
-
- 没有历史趋势和整体状态。
- 没有统一 Check Now。
- LLM 检查产生持续小额调用成本。
- 一次瞬时失败立即 Unhealthy，可能产生短暂抖动，但当前不发送通知。
- 轻量管理接口 Healthy 不等于所有索引、模型能力或业务查询均正常。
@@ -11,7 +11,6 @@
 | [02-case-merge.md](02-case-merge.md) | Confirmed | 多源案件合并、数据迁移、只读源案件与幂等 |
 | [03-playbook-execution.md](03-playbook-execution.md) | Confirmed | Playbook Run、结构化 Stage、取消、重试与 Worker 语义 |
 | [05-worker-health.md](05-worker-health.md) | Confirmed | Redis 心跳、Worker 状态、积压指标与 Admin API |
-| [06-integration-health.md](06-integration-health.md) | Confirmed | 定时集成检查、当前状态持久化与安全错误 |
 | [07-sla-management.md](07-sla-management.md) | Confirmed | TTD/TTA/TTR 时限、Severity 策略、通知和 Dashboard 达标率 |

 ## 待讨论
@@ -22,9 +21,8 @@

 1. 先完成 Case 状态机，再实现批量分诊和案件合并。
 2. 完成 Playbook Run/Stage 后实现 Custom Variables。
-3. 完成通用 Worker Health 基础设施，再接入六类 Worker。
-4. 完成 Integration Health 数据层和 Worker，再实现 Operations 页面。
-5. 待剩余三个业务域定稿后，统一补齐 v0.6.0 验收规范。
+3. 完成通用 Worker Health 基础设施并接入五类 Worker，再实现 Operations 页面。
+4. 待剩余三个业务域定稿后，统一补齐 v0.6.0 验收规范。

 ## Spec 使用规则

@@ -1,114 +0,0 @@
-# v0.6.0 remaining domain TODO
-
-Status: Not discussed
-
-本文件用于在另一台电脑或新会话中继续产品讨论。以下内容仅是讨论清单，不是已确认需求。
-
-## TODO 1: AI quality evaluation
-
-Release blocking: Yes
-
-Goal: 用人工最终判断评估 AI 严重度、置信度、影响、优先级和 Verdict 的质量，形成可解释的反馈闭环。
-
-需要逐项决定：
-
- 评估对象是所有 AI 字段，还是先只做 Verdict/Severity。
- 何时生成评价记录：字段修改、Case Close 或定时快照。
- AI 输出与人工输出为空时如何处理。
- 一次 Case 多次 AI 分析如何选择被评估版本。
- 是否必须保存 model、provider、prompt slug/version 和 analysis job。
- 指标使用 agreement rate、confusion matrix、precision/recall 还是更简单统计。
- Verdict 多分类如何归并，Unknown/Insufficient Data 是否排除。
- 分析师是否提供显式 thumbs up/down 和错误原因。
- 是否允许抽样复核和争议标记。
- 时间窗口、Provider、Model、Playbook/Trigger、Case category 等筛选维度。
- 数据保留、历史不可变性和模型配置删除后的展示。
- Dashboard/独立页面的信息架构。
- 权限和匿名化要求。
- 是否将反馈用于自动 prompt 优化；建议 v0.6.0 排除自动学习。
- 审计、迁移和验收案例。
-
-输出目标：`08-ai-quality-evaluation.md`。
-
-## TODO 2: suppression rules
-
-Release blocking: Yes
-
-Goal: 在告警进入 Case 流程前降低已知噪声，同时保留可审计的命中记录，避免简单删除安全数据。
-
-需要逐项决定：
-
- Rule 匹配对象是原始 Webhook、标准化 Alert 字段还是 Module 输出。
- 可匹配字段白名单以及 text/exact/list/CIDR/regex 运算符。
- 多条件 AND/OR 能力和是否允许嵌套。
- Rule 作用域：全局、Module、rule_id、产品或数据源。
- 动作是 drop、mark suppressed、route to existing Case 还是不创建 Case。
- 被抑制事件是否持久化；存储多少原始数据。
- Rule 优先级、first-match 或 all-match。
- Enabled、有效期、自动过期和命中计数。
- 模拟/预览如何在历史样本上运行，是否必须先模拟再启用。
- 如何防止一条宽泛 Rule 隐藏大量真实告警。
- Admin/User/Viewer 权限；建议至少创建/修改仅 Admin。
- 命中 AuditLog、Rule 变更审计和 Secret/PII 脱敏。
- Module correlation 与 merged source routing 的执行顺序。
- 列表、详情、命中历史和筛选 UX。
- 数据库索引、性能目标和验收案例。
-
-输出目标：`09-suppression-rules.md`。
-
-## TODO 3: Operations Center
-
-Release blocking: Depends on final scope
-
-已确认的固定边界：
-
- 位于 `System Settings → Operations`。
- 包含 Worker Health 和 Integration Health 两个独立区块。
- 仅 Admin 可访问。
- Worker 每 10 秒刷新，Integration 每 30 秒刷新。
- 不提供 Worker Restart、Run Now、日志读取或健康通知。
- Integration 不提供统一 Check Now；保留各 Settings 页的 Test。
- 不计算整体 Integration Health。
-
-仍需决定：
-
- 页面布局、过滤、排序、状态颜色和移动端是否考虑。
- Worker backlog 的不同数据结构如何展示。
- 如何从 Integration 行跳转到对应 Settings。
- Redis 监控不可用时页面局部还是整体错误。
- Operations 导航徽标是否显示异常数量。
- 是否显示 Compose 修复命令，以及具体安全文本。
- 空状态、加载状态和权限拒绝 UX。
- API 聚合还是前端调用两个独立 API。
- 前端组件复用和验收案例。
-
-输出目标：`10-operations-center.md`。
-
-## TODO 4: v0.6.0 acceptance
-
-Release blocking: Yes
-
-需要在所有功能 Spec 完成后定义：
-
- 从 v0.5.2 生产备份副本升级的完整演练。
- 全新 Docker Compose 安装。
- medium 数据规模下的关键 API/页面性能阈值。
- Admin/User/Viewer 权限矩阵回归。
- Case 单条和批量状态机一致性。
- 部分成功批量分诊、原子合并、幂等重试和 merged source 路由。
- Playbook Pending/Running/终态、Cancel、Retry、Stage 和 Worker 崩溃恢复。
- Custom Variables 的 Secret masking、Reveal audit 和 Module/Playbook 读取。
- Worker Redis 故障、重复实例、优雅退出和心跳过期。
- 所有正式集成的 Healthy/Unhealthy/Disabled 行为。
- SLA、AI 质量评估和抑制规则端到端场景。
- 备份、恢复和回滚演练。
- 文档、release notes、已知限制和功能冻结条件。
- P0/P1 缺陷门槛和 RC 观察周期。
-
-输出目标：`11-release-acceptance.md`。
-
-## Suggested continuation prompt
-
-在新电脑上可从下面的提示继续：
-
-> 阅读 `docs/specs/v0.6.0/README.md` 和 `TODO-remaining-domains.md`。已确认 Spec 不要重新讨论。从 AI quality evaluation 开始，一次只问一个决策问题，每个问题给出推荐答案；确认完成后依次处理 suppression rules、Operations Center 和 release acceptance。