feat: archive mvp demo trace acceptance

2026-07-03 16:25:00 +08:00
parent 5b827fe90e
commit 6919092b83
24 changed files with 1343 additions and 2 deletions
@@ -0,0 +1,70 @@
+## 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.