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

Context

The AIOps endpoint is currently useful as a standalone alert-analysis demo, but it is not aligned with the MVP trace story:

• ChatController.aiOps() accepts no request body.
• AiOpsService.executeAiOpsAnalysis(...) creates a random 8-character session id internally.
• The caller cannot reliably discover that id and query GET /api/diagnosis/{sessionId}/trace.
• extractFinalReport(...) returns the report text but does not persist it to diagnosis_session.answer.

The existing trace API already aggregates diagnosis_session, agent_step, and tool_invocation, so this change should reuse that storage rather than introduce new persistence.

Goals / Non-Goals

Goals:

• Make /api/ai_ops usable as an alert-triggered diagnosis entry point.
• Preserve backward compatibility for callers that post with no request body.
• Return the resolved sessionId through SSE.
• Persist the final report into the existing diagnosis session.
• Keep the AIOps path observable through the existing trace API.

Non-Goals:

• Do not merge AIOps into ChatService.
• Do not add a new Verifier Agent to AIOps in this slice.
• Do not change GET /api/diagnosis/{sessionId}/trace.
• Do not add database migrations.
• Do not clean up sensitive configuration.

Decisions

Decision	Choice	Alternative Considered	Rationale
API compatibility	Keep POST /api/ai_ops SSE and make body optional	Add a new /api/ai_ops/v2 endpoint	Optional body keeps existing demo callers working while enabling traceable alert input.
Session identity	Accept request sessionId, otherwise generate UUID	Continue internal-only 8-char id	Reviewers need the id to query trace and submit feedback.
Query persistence	Build a concise alert diagnosis query from request fields	Store only "AI Ops 告警分析"	Trace should show what alert was diagnosed.
Final answer persistence	Save extracted final report to diagnosis_session.answer	Only stream the report	Trace replay must include the final answer without relying on SSE logs.
Verifier scope	Defer AIOps Verifier integration	Add Chat Verifier now	The minimum interview value is traceability; Verifier unification can be a follow-up after this entry point is stable.
GitNexus	Skip by user decision	Block until MCP available	GitNexus tools are not exposed in this session, and the user explicitly requested skipping GitNexus. Local impact analysis and tests cover this slice.

Interface Impact

• Level: L3 API behavior extension.
• Endpoint: POST /api/ai_ops
• Compatibility: callers may still omit a body. New callers may send:

{
  "sessionId": "mvp-demo-aiops-payment-latency-001",
  "alertName": "payment-service-latency-high",
  "service": "payment-service",
  "severity": "P1",
  "description": "支付服务 P95 延迟升高并伴随超时错误",
  "timeRange": "last_15m"
}

The SSE stream emits a first content message containing the resolved session id:

sessionId: mvp-demo-aiops-payment-latency-001

Data Flow

POST /api/ai_ops
  -> ChatController resolves request body and tools
  -> AiOpsService.executeAiOpsAnalysis(chatModel, tools, request)
  -> create diagnosis_session(agentFlow=AI_OPS, query=<alert summary>)
  -> set SessionContextHolder(sessionId)
  -> ai_ops_supervisor -> planner_agent -> executor_agent
  -> persist agent_step and tool_invocation through existing hooks/tools
  -> extract final report
  -> persist diagnosis_session.answer/status/counts
  -> caller queries GET /api/diagnosis/{sessionId}/trace

Risks / Trade-offs

• [Risk] AIOps still lacks the Chat Verifier quality gate. -> Mitigation: document as follow-up and keep this slice focused on traceability.
• [Risk] SSE clients may not parse the new first message. -> Mitigation: message is additive content; existing clients still receive the final report.
• [Risk] Optional request body in Spring MVC can be easy to mishandle. -> Mitigation: use @RequestBody(required = false) and default request values in service code.
• [Risk] AIOps generated reports may still depend on real infrastructure. -> Mitigation: demo profile already enables mock logs/metrics where available; full offline mode remains out of scope.

Migration Plan

• No database migration.
• Deploy with application restart.
• Rollback by reverting controller/service/DTO changes; existing persisted sessions remain valid.