MetricOps Agent

MetricOps Agent 是一个面向电商/零售经营数据的 AI 异常处理系统。当前版本实现了从指标异常检测、证据链分析、AI 归因、工单流转到处理复盘的闭环，并提供 Next.js 前端工作台用于完整演示。

快速启动

推荐直接在项目根目录一键启动数据库、后端和前端：

.\dev.cmd

启动后访问 http://127.0.0.1:3000。脚本会自动：

• 启动 Docker Compose 里的 Postgres localhost:5433
• 执行后端 Alembic 迁移
• 以 LLM_PROVIDER=mock 启动 FastAPI 后端 http://127.0.0.1:8000
• 启动 Next.js 前端 http://127.0.0.1:3000

脚本会打开后端和前端两个服务窗口。停止服务时，关闭对应窗口，或在窗口内按 Ctrl+C。

如需调整端口：

.\dev.cmd -BackendPort 8000 -FrontendPort 3000

也可以手动分步启动。后端默认连接本地 Postgres localhost:5433：

docker compose up -d db
cd backend
$env:DATABASE_URL="postgresql+asyncpg://postgres:postgres@localhost:5433/metricops"
$env:LLM_PROVIDER="mock"
.\.venv\Scripts\alembic.exe upgrade head
.\.venv\Scripts\uvicorn.exe app.main:app --reload --port 8000

前端默认连接 http://127.0.0.1:8000，也可通过 NEXT_PUBLIC_API_BASE_URL 覆盖：

cd frontend
pnpm install
pnpm dev

访问 http://127.0.0.1:3000。

核心流程

1. 检测退款率、差评率、GMV 等指标异常。
2. 进入异常详情，查看趋势、退款原因、评论关键词、badcase 和上下文指标。
3. 启动诊断工作流，后台执行工具调用和 AI 归因，通过 SSE 实时展示进度。
4. 创建/流转工单：pending_confirm → pending → processing → pending_review → closed。
5. 提交复盘，记录处理前后业务日期窗口指标，形成闭环。

技术栈

• Backend：FastAPI、SQLAlchemy Async、Alembic、PostgreSQL、Pydantic、pytest、mypy、ruff。
• AI：LLM Provider 抽象，支持 Anthropic / OpenAI 扩展 / Mock，本地和 CI 默认用 Mock。
• Frontend：Next.js App Router、TypeScript、Tailwind CSS、TanStack Query、Recharts、react-markdown、fetch-event-source。
• Workflow：Postgres 持久化步骤、工具调用、报告和复盘记录；单进程内存 SSE event bus 支持 demo 进度推送。

功能列表

• M0–M1：工程骨架、ORM/迁移、Olist 加载、模拟退款/评论标签/SOP、异常注入和日聚合。
• M2：指标 Overview / Trend API。
• M3：退款率、差评率和 GMV 异常检测。
• M4：异常证据链 API。
• M5：工单 API 和状态机。
• M6：AI 可调用工具函数和工具调用审计。
• M7：结构化 AI 归因报告、缓存和强类型 schema 校验。
• M8：固定八步诊断工作流。
• M9：后台工作流 + SSE 实时进度。
• M10：复盘 API 和处理前后指标对比。
• M11：Dashboard、异常列表、异常详情、工单列表、复盘页。

Demo 场景

推荐演示路径：

1. 首页查看核心指标、异常数量和待处理工单。
2. 进入异常列表，选择一个高严重度退款率/差评率异常。
3. 在异常详情页查看趋势图、退款原因、评论关键词和 badcase。
4. 点击“启动工作流”，观察 SSE 事件进度。
5. 查看生成的 AI 报告、根因和建议卡。
6. 在工单列表推进状态到 pending_review。
7. 进入复盘页提交复盘，查看处理前后指标对比。

项目截图

手动验收 M11 时，建议将演示截图保存到 docs/screenshots/：

• dashboard.png
• anomalies.png
• tickets.png

验证命令

cd backend
.\.venv\Scripts\ruff.exe check --no-cache .
.\.venv\Scripts\ruff.exe format --check .
.\.venv\Scripts\mypy.exe .
.\.venv\Scripts\pytest.exe -p no:cacheprovider

cd ..\frontend
pnpm lint
pnpm typecheck
pnpm build