kai/smart-support
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: complete phase 4 -- conversation replay API + analytics dashboard

Browse Source 
- Replay models: StepType enum, ReplayStep, ReplayPage frozen dataclasses
- Checkpoint transformer: PostgresSaver JSONB -> structured timeline steps
- Replay API: GET /api/conversations (paginated), GET /api/replay/{thread_id}
- Analytics models: AgentUsage, InterruptStats, AnalyticsResult
- Analytics event recorder: Protocol + PostgresAnalyticsRecorder + NoOp
- Analytics queries: resolution_rate, agent_usage, escalation_rate, cost, interrupts
- Analytics API: GET /api/analytics?range=Xd with envelope response
- DB migration: analytics_events table + conversations column additions
- 74 new tests, 399 total passing, 92.87% coverage
This commit is contained in:
Yaojia Wang
2026-03-31 13:35:45 +02:00
parent a2f750269d
commit 33db5aeb10
26 changed files with 1903 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
docs/phases/phase-4-dev-log.md Normal file
View File

@@ -0,0 +1,76 @@
# Phase 4: Conversation Replay + Analytics -- Development Log
> Status: COMPLETED
> Phase branch: `phase-4/analytics-replay`
> Date started: 2026-03-31
> Date completed: 2026-03-31
> Related plan section: [Phase 4 in DEVELOPMENT-PLAN](../DEVELOPMENT-PLAN.md#phase-4-对话回放--数据分析-第-6-7-周)
## What Was Built
- Replay data models (StepType enum, ReplayStep, ReplayPage frozen dataclasses)
- Checkpoint transformer converting PostgresSaver JSONB to structured timeline steps
- Replay API: GET /api/conversations (paginated list), GET /api/replay/{thread_id} (paginated timeline)
- Analytics data models (AgentUsage, InterruptStats, AnalyticsResult)
- Analytics event recorder with Protocol interface (PostgresAnalyticsRecorder + NoOpAnalyticsRecorder)
- Analytics queries: resolution_rate, agent_usage, escalation_rate, cost_per_conversation, interrupt_stats
- Analytics API: GET /api/analytics?range=Xd with envelope response
- DB migration: analytics_events table + conversations column additions (resolution_type, agents_used, turn_count, ended_at)
## Code Structure
New files created:
| File | Purpose | Lines |
|------|---------|-------|
| `app/replay/__init__.py` | Module entry | 2 |
| `app/replay/models.py` | StepType enum, ReplayStep, ReplayPage | ~80 |
| `app/replay/transformer.py` | Checkpoint JSONB -> ReplayStep[] | ~120 |
| `app/replay/api.py` | FastAPI router /api/replay + /api/conversations | ~80 |
| `app/analytics/__init__.py` | Module entry | 2 |
| `app/analytics/models.py` | AgentUsage, InterruptStats, AnalyticsResult | ~55 |
| `app/analytics/event_recorder.py` | AnalyticsRecorder Protocol + implementations | ~40 |
| `app/analytics/queries.py` | SQL query functions + get_analytics aggregator | ~130 |
| `app/analytics/api.py` | FastAPI router /api/analytics | ~50 |
Modified files:
- `app/db.py` -- Added analytics_events DDL + conversations migration
- `app/main.py` -- Wired replay + analytics routers, registered NoOpAnalyticsRecorder
Test files (74 new tests):
- `tests/unit/replay/test_models.py`
- `tests/unit/replay/test_transformer.py`
- `tests/unit/replay/test_api.py`
- `tests/unit/analytics/test_models.py`
- `tests/unit/analytics/test_event_recorder.py`
- `tests/unit/analytics/test_queries.py`
- `tests/unit/analytics/test_api.py`
- `tests/unit/test_db_phase4.py`
## Test Coverage
- 399 total tests passing (74 new + 325 existing)
- Overall coverage: 92.87% (requirement: 80%)
Per-module coverage:
- replay/models.py: 100%
- replay/transformer.py: 82%
- replay/api.py: 100%
- analytics/models.py: 100%
- analytics/event_recorder.py: 100%
- analytics/queries.py: 81%
- analytics/api.py: 100%
## Deviations from Plan
1. **Frontend UI deferred:** React pages (ReplayListPage, ReplayPage, DashboardPage) not implemented. Backend APIs are complete and testable.
2. **ws_handler event recording deferred:** Analytics event recording from WebSocket handler not wired yet (NoOpAnalyticsRecorder registered). Actual recording to be done in Phase 5.
3. **conversations.agents_used not populated yet:** Column added but not populated by existing ws_handler. Backfill logic deferred to Phase 5.
## Known Issues / Tech Debt
- Frontend pages need implementation (React Router, ReplayTimeline component)
- WebSocket handler needs to record analytics events via PostgresAnalyticsRecorder
- conversations.agents_used TEXT[] column needs population logic
- Checkpoint transformer depends on LangGraph JSONB structure -- may need version adaptation
- No auth on replay/analytics endpoints (same as Phase 3 -- Phase 5 concern)