feat: archive mvp demo trace acceptance
This commit is contained in:
zhuyongxin
@@ -0,0 +1 @@
|
||||
mvp-demo-trace-acceptance committed on 2026-07-03
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-07-03
|
||||
@@ -0,0 +1,29 @@
|
||||
{
|
||||
"id": "mvp-demo-trace-acceptance",
|
||||
"metadata": {
|
||||
"status": "committed",
|
||||
"created_at": "2026-07-03",
|
||||
"updated_at": "2026-07-03",
|
||||
"implementation_status": "implemented"
|
||||
},
|
||||
"summary": "Add an MVP demo profile, a read-only diagnosis trace API, and an end-to-end acceptance case.",
|
||||
"artifacts": {
|
||||
"proposal": "proposal.md",
|
||||
"design": "design.md",
|
||||
"tasks": "tasks.md",
|
||||
"specs": [
|
||||
"specs/mvp-demo-trace-acceptance/spec.md"
|
||||
],
|
||||
"devflow": "devflow/projects/2026-07-03-mvp-demo-trace-acceptance"
|
||||
},
|
||||
"tasks": [
|
||||
"Add DiagnosisTraceResponse DTO",
|
||||
"Add DiagnosisTraceService aggregation",
|
||||
"Add DiagnosisTraceController endpoint",
|
||||
"Add mvp-demo profile",
|
||||
"Add MVP demo acceptance documentation",
|
||||
"Add focused trace service tests",
|
||||
"Run targeted verification and GitNexus change detection",
|
||||
"Update MVP notes and devflow acceptance"
|
||||
]
|
||||
}
|
||||
@@ -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.
|
||||
@@ -0,0 +1,29 @@
|
||||
## Why
|
||||
|
||||
The MVP can already execute multi-agent diagnosis, persist session traces, and collect feedback, but it is still hard to demonstrate as a complete enterprise-style workflow. A demo profile, a trace query API, and an explicit end-to-end acceptance case make the project runnable, observable, and explainable for interview and portfolio review.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Add an `mvp-demo` Spring profile that keeps the existing external infrastructure contract but turns on mock log and metric providers for repeatable demonstrations.
|
||||
- Add a read-only trace query API: `GET /api/diagnosis/{sessionId}/trace`.
|
||||
- Aggregate `diagnosis_session`, `agent_step`, `tool_invocation`, verifier/self-evaluation, final answer, and feedback into one trace response.
|
||||
- Add an end-to-end MVP acceptance case that documents startup, chat request, trace query, and feedback submission.
|
||||
- Add focused service tests for trace aggregation without requiring MySQL, Redis, Milvus, or a real LLM.
|
||||
- Record the design decision in MVP notes for interview storytelling.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `mvp-demo-trace-acceptance`: Covers the MVP demo profile, trace query API, and end-to-end acceptance workflow for a reproducible agent diagnosis demo.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- None.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected code: new trace controller/service/DTOs, `application-mvp-demo.yml`, unit tests, MVP demo documentation.
|
||||
- Affected API: adds `GET /api/diagnosis/{sessionId}/trace`. This is an additive L3 collaboration API because it is intended for frontend, demo, and external reviewer consumption.
|
||||
- Affected runtime behavior: no change to chat execution, verifier, feedback, document upload, or persistence semantics.
|
||||
- Non-goals: no sensitive configuration cleanup, no database schema migration, no replacement of existing chat endpoints, no full offline mock LLM implementation.
|
||||
+33
@@ -0,0 +1,33 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Diagnosis trace can be queried by session id
|
||||
The system SHALL expose a read-only HTTP endpoint `GET /api/diagnosis/{sessionId}/trace` that returns the persisted diagnosis trace for the requested session id.
|
||||
|
||||
#### Scenario: Existing session trace is returned
|
||||
- **WHEN** a caller requests trace data for a session id that exists in `diagnosis_session`
|
||||
- **THEN** the system returns a success response containing the session summary, ordered agent steps, ordered tool invocations, self-evaluation data, final answer, and feedback
|
||||
|
||||
#### Scenario: Missing session returns not found
|
||||
- **WHEN** a caller requests trace data for a session id that does not exist in `diagnosis_session`
|
||||
- **THEN** the system returns a 404 response using the existing session-not-found error contract
|
||||
|
||||
### Requirement: Trace aggregation is read-only
|
||||
The system MUST build trace output from existing persisted diagnosis tables and MUST NOT mutate diagnosis sessions, agent steps, tool invocations, feedback, or chat session state while serving the trace request.
|
||||
|
||||
#### Scenario: Trace query does not change persisted state
|
||||
- **WHEN** a caller requests `GET /api/diagnosis/{sessionId}/trace`
|
||||
- **THEN** the system reads `diagnosis_session`, `agent_step`, and `tool_invocation` records and returns an aggregate without saving any of those records
|
||||
|
||||
### Requirement: MVP demo profile is available
|
||||
The system SHALL provide an `mvp-demo` Spring profile that documents the demo runtime intent and keeps mock log and metric providers enabled for repeatable diagnosis demonstrations.
|
||||
|
||||
#### Scenario: Demo profile loads mock evidence providers
|
||||
- **WHEN** the application starts with `--spring.profiles.active=mvp-demo`
|
||||
- **THEN** `prometheus.mock-enabled` and `cls.mock-enabled` are enabled by profile configuration
|
||||
|
||||
### Requirement: End-to-end MVP acceptance case is documented
|
||||
The project SHALL include an end-to-end acceptance case that demonstrates start-up, chat diagnosis, trace query, and feedback submission using the same session id.
|
||||
|
||||
#### Scenario: Reviewer follows the acceptance case
|
||||
- **WHEN** a reviewer follows the documented MVP demo acceptance steps
|
||||
- **THEN** they can run the application, submit a diagnosis question, query the trace endpoint, and submit feedback for the same session id
|
||||
@@ -0,0 +1,25 @@
|
||||
## 1. Trace Query API
|
||||
|
||||
- [x] 1.1 Add a `DiagnosisTraceResponse` DTO that represents session summary, ordered agent steps, ordered tool invocations, and derived summary counts.
|
||||
- [x] 1.2 Add `DiagnosisTraceService` that loads `DiagnosisSession`, `AgentStep`, and `ToolInvocation` records by session id and builds the response.
|
||||
- [x] 1.3 Add `DiagnosisTraceController` with `GET /api/diagnosis/{sessionId}/trace`.
|
||||
- [x] 1.4 Return 404 through `SessionNotFoundException` when the requested diagnosis session does not exist.
|
||||
|
||||
## 2. Demo Profile And Acceptance Case
|
||||
|
||||
- [x] 2.1 Add `src/main/resources/application-mvp-demo.yml` with MVP demo profile overlays and mock logs/metrics enabled.
|
||||
- [x] 2.2 Add `mvp/demo/README.md` documenting prerequisites, startup, chat request, trace query, and feedback submission.
|
||||
- [x] 2.3 Add a concrete payment-timeout acceptance case with request/response expectations.
|
||||
|
||||
## 3. Tests And Verification
|
||||
|
||||
- [x] 3.1 Add focused unit tests for `DiagnosisTraceService` success and missing-session behavior.
|
||||
- [x] 3.2 Run targeted tests for the new trace service.
|
||||
- [x] 3.3 Run compile verification.
|
||||
- [x] 3.4 Run GitNexus change detection before commit or handoff.
|
||||
|
||||
## 4. Notes And Flow Records
|
||||
|
||||
- [x] 4.1 Update MVP engineering notes with the demo/trace decision.
|
||||
- [x] 4.2 Update OpenSpec tasks as work completes.
|
||||
- [x] 4.3 Record verification results in devflow acceptance notes.
|
||||
@@ -0,0 +1,37 @@
|
||||
## Purpose
|
||||
|
||||
Provide a repeatable MVP demo flow that can run a chat diagnosis, expose its persisted execution trace, and submit feedback for the same session id.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Diagnosis trace can be queried by session id
|
||||
The system SHALL expose a read-only HTTP endpoint `GET /api/diagnosis/{sessionId}/trace` that returns the persisted diagnosis trace for the requested session id.
|
||||
|
||||
#### Scenario: Existing session trace is returned
|
||||
- **WHEN** a caller requests trace data for a session id that exists in `diagnosis_session`
|
||||
- **THEN** the system returns a success response containing the session summary, ordered agent steps, ordered tool invocations, self-evaluation data, final answer, and feedback
|
||||
|
||||
#### Scenario: Missing session returns not found
|
||||
- **WHEN** a caller requests trace data for a session id that does not exist in `diagnosis_session`
|
||||
- **THEN** the system returns a 404 response using the existing session-not-found error contract
|
||||
|
||||
### Requirement: Trace aggregation is read-only
|
||||
The system MUST build trace output from existing persisted diagnosis tables and MUST NOT mutate diagnosis sessions, agent steps, tool invocations, feedback, or chat session state while serving the trace request.
|
||||
|
||||
#### Scenario: Trace query does not change persisted state
|
||||
- **WHEN** a caller requests `GET /api/diagnosis/{sessionId}/trace`
|
||||
- **THEN** the system reads `diagnosis_session`, `agent_step`, and `tool_invocation` records and returns an aggregate without saving any of those records
|
||||
|
||||
### Requirement: MVP demo profile is available
|
||||
The system SHALL provide an `mvp-demo` Spring profile that documents the demo runtime intent and keeps mock log and metric providers enabled for repeatable diagnosis demonstrations.
|
||||
|
||||
#### Scenario: Demo profile loads mock evidence providers
|
||||
- **WHEN** the application starts with `--spring.profiles.active=mvp-demo`
|
||||
- **THEN** `prometheus.mock-enabled` and `cls.mock-enabled` are enabled by profile configuration
|
||||
|
||||
### Requirement: End-to-end MVP acceptance case is documented
|
||||
The project SHALL include an end-to-end acceptance case that demonstrates start-up, chat diagnosis, trace query, and feedback submission using the same session id.
|
||||
|
||||
#### Scenario: Reviewer follows the acceptance case
|
||||
- **WHEN** a reviewer follows the documented MVP demo acceptance steps
|
||||
- **THEN** they can run the application, submit a diagnosis question, query the trace endpoint, and submit feedback for the same session id
|
||||
Reference in New Issue
Block a user