SuperBizAgent-java/openspec/changes/archive/2026-07-04-aiops-traceable-diagnosis-entry/specs/aiops-traceable-diagnosis-entry/spec.md

ADDED 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