feat: add traceable scoped AIOps diagnosis

2026-07-04 22:57:28 +08:00
parent 246c99b954
commit 23ee05c7c3
32 changed files with 1179 additions and 25 deletions
@@ -0,0 +1,44 @@
+# aiops-traceable-diagnosis-entry Specification
+
+## Purpose
+TBD - created by archiving change aiops-traceable-diagnosis-entry. Update Purpose after archive.
+## Requirements
+### Requirement: AIOps endpoint accepts optional alert input
+The system SHALL allow `POST /api/ai_ops` to accept an optional JSON request body describing the alert diagnosis request.
+
+#### Scenario: Caller supplies alert input
+- **WHEN** a caller posts to `/api/ai_ops` with alert fields such as session id, alert name, service, severity, description, and time range
+- **THEN** the AIOps analysis uses those fields to build the diagnosis task prompt and persisted session query
+
+#### Scenario: Caller omits alert input
+- **WHEN** a caller posts to `/api/ai_ops` without a body
+- **THEN** the system still starts the default AIOps alert-analysis flow
+
+### Requirement: AIOps session id is traceable
+The system SHALL resolve a stable AIOps session id from the request when provided, otherwise generate one, and SHALL expose that session id to the SSE caller.
+
+#### Scenario: Request includes session id
+- **WHEN** a caller posts to `/api/ai_ops` with `sessionId`
+- **THEN** the created `diagnosis_session.session_id` equals that value
+- **AND** the SSE stream includes the same session id
+
+#### Scenario: Request omits session id
+- **WHEN** a caller posts to `/api/ai_ops` without `sessionId`
+- **THEN** the system generates a session id
+- **AND** the SSE stream includes the generated session id
+
+### Requirement: AIOps report is persisted for trace replay
+The system SHALL persist the final AIOps report into the existing `diagnosis_session.answer` field when a report is available.
+
+#### Scenario: AIOps report is generated
+- **WHEN** the AIOps planner/executor flow returns a final report
+- **THEN** the corresponding diagnosis session is marked successful
+- **AND** `diagnosis_session.answer` stores the final report
+- **AND** `GET /api/diagnosis/{sessionId}/trace` can include that answer
+
+### Requirement: AIOps trace uses existing evidence tables
+The system SHALL continue using existing `agent_step` and `tool_invocation` persistence for AIOps trace evidence.
+
+#### Scenario: AIOps uses evidence tools
+- **WHEN** the AIOps flow calls available evidence tools
+- **THEN** existing hooks and recorders persist agent steps and tool invocations under the resolved AIOps session id