SuperBizAgent-java/openspec/changes/archive/2026-07-03-mvp-demo-trace-acceptance/design.md

Context

The MVP already persists diagnosis execution data across three tables:

• diagnosis_session: query, status, answer, counts, feedback, and self_evaluation.
• agent_step: ordered agent execution records.
• tool_invocation: evidence tool calls and retrieval metadata.

Recent work unified chat session ids and persisted tool invocations, so a single session id can now connect user input, agent steps, evidence tools, verifier evaluation, final answer, and feedback. The missing piece is a read-only aggregation API and a documented demo profile/workflow that a reviewer can run without reading database tables manually.

Goals / Non-Goals

Goals:

• Add a trace API that returns one aggregated view for a diagnosis session.
• Keep the trace API read-only and based on existing persistence tables.
• Add an mvp-demo profile that makes the demo intent explicit and keeps mock log/metric tools enabled.
• Add a documented end-to-end acceptance case for start, chat, trace query, and feedback.
• Add focused tests for trace aggregation.

Non-Goals:

• Do not clean up committed sensitive configuration in this change.
• Do not add database migrations.
• Do not alter /api/chat, /api/chat_stream, verifier routing, feedback, or document upload behavior.
• Do not create a fully offline fake LLM runtime.

Decisions

Decision	Choice	Alternative Considered	Rationale
Trace API shape	Add GET /api/diagnosis/{sessionId}/trace	Extend /api/chat response	Trace is an observability concern and should not make chat responses larger or change chat clients.
Aggregation ownership	New DiagnosisTraceService	Put aggregation in controller	Keeps controller thin and allows focused unit tests with mocked repositories.
Response DTO	Dedicated nested DTO	Return raw entities or maps	DTO avoids leaking JPA entity details and gives a stable demo-facing contract.
Missing session handling	Throw SessionNotFoundException and use existing global 404 handler	Return empty success payload	A missing trace is a real lookup miss and should be visible to callers.
self_evaluation handling	Return raw JSON string and best-effort parsed JSON	Parse only, or ignore parse failures	Raw value preserves evidence even if JSON shape evolves; parsed value improves frontend/demo readability.
Demo profile	Add application-mvp-demo.yml overlay	Change default application.yml	Overlay avoids disturbing current runtime and keeps demo choices explicit.

Interface Impact

• Level: L3 collaboration API.
• Reason: This adds a new HTTP endpoint and response contract intended for frontend/demo/reviewer consumption.
• Compatibility: Additive only. Existing callers do not need to change.
• Documentation: The endpoint is documented in the MVP demo acceptance case.

Data Structures

The trace response contains:

• session: session id, query, status, flow, counts, timing, created/updated time, final answer, raw self-evaluation JSON, parsed self-evaluation object, and feedback.
• steps: ordered agent steps with step index, agent name, model input/output, thought, tool flag, duration, token count, and created time.
• toolInvocations: ordered tool records with id, step id, tool name, input params, output preview, retrieval metadata, duration, success, error, and created time.
• summary: counts derived from the returned collections and session fields.

Risks / Trade-offs

• [Risk] Trace responses may become large for long sessions. -> Mitigation: the MVP returns persisted previews and structured metadata, not raw full external logs.
• [Risk] self_evaluation JSON shape may evolve. -> Mitigation: return both raw and best-effort parsed forms.
• [Risk] Demo profile still depends on real DB/Redis/Milvus/LLM. -> Mitigation: document prerequisites and keep mock logs/metrics enabled for repeatable tool evidence.
• [Risk] New endpoint becomes a de facto frontend contract. -> Mitigation: use a dedicated DTO and document L3 additive API impact.

Migration Plan

• Deploying this change requires only application restart with the new code.
• No database migration is required.
• Rollback is deleting the new endpoint/profile/docs; persisted data remains unchanged.

Open Questions

• None for this slice. Security and full offline test profile remain deferred by explicit user decision.