## 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:

```json
{
  "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:

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

## Data Flow

```text
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.