root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
14a12342b5165d83602a2656e230f2e67ede729e
Neo-ZQYY/docs/specs/dev-trace-log/tasks.md
Neo 2a7a5d68aa feat: 2026-04-15~04-20 累积变更基线 — 多主线合流 
主线 1: rns1-customer-coach-api + 04-miniapp-core-business 后端实施
  - 新增 GET /xcx/coaches/{id}/banner 轻量接口
  - performance/records 加 coach_id 参数 + view_board_coach 权限分流
  - coach/customer/performance/board/task 服务层重构
  - fdw_queries 结算单粒度聚合 + consumption_summary 视图统一
  - task_generator 回访宽限 72h + UPSERT 替代策略 + Step 5 保底清理
  - recall_detector settle_type=3 双重限制 + 门店级 resolved

主线 2: 小程序权限分流 + 新增 coach-service-records 管理者视角业绩明细页
  - perf-progress 共享模块去重 task-list/coach-detail 动画逻辑
  - isScattered 散客标记端到端
  - foodDetail/phoneFull/creator* 字段透传

主线 3: P19 指数回测框架 Phase 1+2
  - 3 个指数表 stat_date 日快照模式
  - 新增 DWS_INDEX_BACKFILL / DWS_TASK_SIMULATION 工具任务
  - task_engine 升级 HTTP 实时 + 推演回测双模式

主线 4: Core 维度层启用
  - 新增 CORE_DIM_SYNC 任务（DWD → core 4 维度表）
  - 修复 app 视图空查询问题

主线 5: member_project_tag 改为 LAST_30_VISITS 消费次数窗口

主线 6: 2 个迁移 SQL 已执行（stat_date + member_project_tag 新窗口）
  - schema 基线与 DDL 快照同步

主线 7: 开发机路径迁移 C:\NeoZQYY → C:\Project\NeoZQYY（约 95% 改动量）

附带: 新建运维脚本（churned_customer_report / simulate_historical_tasks /
      backfill_index_snapshots）+ tools/task-analysis/ 任务分析工具

合计 157 文件。未包含中间产物（tmp/ .playwright-mcp/ inspect-* excel/sheet 分析 txt）。
审计记录见下一个 commit。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-20 06:32:07 +08:00

435 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 实施计划：开发调试全链路日志系统（dev-trace-log）
## 概述
按依赖关系分五个阶段实施：基础设施层 → 核心采集层（HTTP + 鉴权 + DB + 中间件） → 扩展采集层（SSE + WebSocket + 后台 Job + 异常） → 后端 API + 前端页面 → 收尾。每个阶段完成后设置检查点验证。
后端使用 Python（FastAPI + contextvars），前端使用 TypeScript（React + Vite + Ant Design）。
覆盖范围：HTTP 请求全链路 + SSE 流式响应 + WebSocket 连接 + 后台 Job + 异常/错误 + 数据库连接生命周期 + 中间件层。
## 任务
### 阶段一：基础设施层 — Trace 核心模块
- [x] 1. 环境变量与配置模块
- [x] 1.1 在 `.env` 和 `.env.template` 中添加 trace 相关环境变量
- `DEV_TRACE_ENABLED=true`（总开关）
- `DEV_TRACE_LOG_DIR=export/dev-trace-logs`（日志目录）
- `DEV_TRACE_LOG_RETENTION_DAYS=7`（自动清理保留天数）
- `DEV_TRACE_LOG_SQL=true`（是否记录完整 SQL）
- `DEV_TRACE_LOG_PARAMS=true`（是否记录函数参数值）
- _Requirements: 8.1, 8.4, 8.5, 8.6, 5.3_
- [x] 1.2 创建 `apps/backend/app/trace/__init__.py` 和 `apps/backend/app/trace/config.py`
- 定义 `TraceConfig` 类，从环境变量读取所有配置项
- 实现运行时开关（内存状态），支持通过 API 动态修改
- 重启后回退到 .env 配置值
- _Requirements: 8.1, 8.2, 8.3, 8.5, 8.6_
- [x] 2. TraceContext 与 TraceSpan 数据模型
- [x] 2.1 创建 `apps/backend/app/trace/context.py`
- 定义 `TraceSpan` dataclass（span_type, module, function, description_zh, description_en, params, result_summary, duration_ms, timestamp, extra）
- span_type 支持全部类型：HTTP_IN, AUTH, ROUTE, SERVICE, DB_QUERY, DB_CONN, DB_CONN_RELEASE, HTTP_OUT, ERROR, DB_ERROR, MIDDLEWARE, MIDDLEWARE_ERROR, SSE_START, SSE_EVENT, SSE_END, AI_CALL, AI_STREAM, AI_ERROR, WS_CONNECT, WS_MESSAGE, WS_DISCONNECT, JOB_START, JOB_END, JOB_ERROR
- 定义 `TraceContext` dataclass（request_id, trace_type[http/sse/ws/job], start_time, method, path, user_id, site_id, spans）
- 使用 `contextvars.ContextVar` 存储请求级 TraceContext
- `request_id` 格式：HTTP 用 uuid hex[:12]，WS 用 `ws_` 前缀，Job 用 `job_` 前缀
- 提供 `add_span()` 方法追加 span
- _Requirements: 1.1, 1.5, 2.4, 13.6, 14.4, 15.5_
- [x] 2.2 编写属性测试：Request ID 唯一性
- **Property 1: Request ID 唯一性**
- 使用 Hypothesis 生成 N 个 TraceContext 实例，验证所有 request_id 互不相同
- **验证: 需求 1.1**
- [x] 2.3 编写属性测试：Span 顺序保持
- **Property 2: Span 顺序保持**
- 生成随机 TraceSpan 序列并按顺序 add_span，验证 spans 列表保持插入顺序
- **验证: 需求 1.5**
- [x] 3. JSON Lines 日志写入器
- [x] 3.1 创建 `apps/backend/app/trace/writer.py`
- 实现 `TraceWriter` 类，负责将 TraceContext 序列化为 JSON 并追加写入 `.jsonl` 文件
- 按日期分目录（`YYYY-MM-DD/`），按小时分文件（`trace_YYYY-MM-DD_HH.jsonl`）
- 单文件超过 10MB 自动轮转（`trace_YYYY-MM-DD_HH_NNN.jsonl`）
- 维护 `_index.json` 索引文件（文件列表、记录数、文件大小）
- 写入操作异步化，写入失败不影响请求处理
- 序列化输出包含完整字段：request_id, trace_type, timestamp, method, path, status_code, total_duration_ms, user_id, site_id, db_query_count, db_total_ms, error, spans
- _Requirements: 3.1, 3.2, 3.3, 3.4, 4.1, 4.2, 4.3, 4.4, 4.5_
- [x] 3.2 编写属性测试：TraceSpan 结构完整性
- **Property 3: TraceSpan 结构完整性**
- 使用 Hypothesis 生成任意 span_type 的 TraceSpan，验证序列化 JSON 包含所有必需字段
- 生成任意 TraceContext，验证顶层 JSON 包含所有必需字段
- **验证: 需求 2.4, 3.1, 3.2**
- [x] 3.3 编写属性测试：JSON 序列化往返一致性
- **Property 5: JSON 序列化往返一致性**
- 生成任意 TraceContext，序列化为 JSON line → 解析回 dict → 再序列化，验证两次输出等价
- **验证: 需求 3.5**
- [x] 3.4 编写属性测试：日志文件路径生成
- **Property 6: 日志文件路径生成**
- 生成任意 datetime，验证目录名匹配 `YYYY-MM-DD/`，文件名匹配 `trace_YYYY-MM-DD_HH.jsonl`
- **验证: 需求 4.1, 4.2**
- [x] 4. 日志自动清理模块
- [x] 4.1 创建 `apps/backend/app/trace/cleanup.py`
- 实现每日凌晨自动清理检查（可在 lifespan 中注册定时任务）
- 删除超过配置保留天数的日期目录
- 清理后更新 `_index.json`
- _Requirements: 5.1, 5.2, 5.3, 5.4_
- [x] 4.2 编写属性测试：清理保留期正确性
- **Property 8: 清理保留期正确性**
- 生成随机日期目录集合和保留天数 N，验证清理后：超期目录已删除、保留期内目录保留、索引不引用已删除目录
- **验证: 需求 5.2, 5.4**
- [x] 5. 检查点 — 基础设施层验证
- 运行 `cd C:\Project\NeoZQYY && pytest tests/ -v` 确保属性测试通过
- 确保 TraceContext、TraceWriter、TraceConfig、cleanup 模块可独立工作
- ask the user if questions arise.
### 阶段二：核心采集层 — HTTP + 鉴权 + DB + 中间件
- [x] 6. TraceMiddleware（ASGI 中间件）
- [x] 6.1 创建 `apps/backend/app/trace/middleware.py`
- 实现 ASGI 中间件，拦截 xcx_* 路由前缀的请求
- 非 xcx 路由直接跳过，不创建 TraceContext
- 检查 DEV_TRACE_ENABLED 开关，关闭时跳过所有采集
- 请求进入时：创建 TraceContext 存入 contextvars，记录 HTTP_IN span
- 请求结束时：记录 HTTP_OUT span（status_code, duration, body_size）
- 响应头写入 X-Request-ID, X-Process-Time, X-DB-Queries, X-DB-Time
- 记录 MIDDLEWARE span（ResponseWrapperMiddleware 执行耗时）
- 如果响应包装失败，记录 MIDDLEWARE_ERROR span
- 调用 TraceWriter 写入完整 trace
- _Requirements: 1.1, 1.2, 1.3, 1.4, 8.2, 8.3, 11.1, 11.2, 17.1, 17.2, 17.3_
- [x] 6.2 在 `apps/backend/app/main.py` 中注册 TraceMiddleware
- 在 ResponseWrapperMiddleware 外层添加
- 不影响现有 ResponseWrapperMiddleware 和 logging 配置
- _Requirements: 11.3_
- [x] 6.3 编写属性测试：路由前缀过滤
- **Property 15: 路由前缀过滤**
- 生成随机请求路径，验证仅 xcx_* 前缀路径产生 trace 数据
- **验证: 需求 11.1, 11.2**
- [x] 6.4 编写属性测试：开关关闭时无 Trace 产出
- **Property 13: 开关关闭时无 Trace 产出**
- DEV_TRACE_ENABLED=false 时验证无 TraceContext 创建、无 span 记录、无日志写入
- **验证: 需求 8.2, 8.3**
- [x] 7. 装饰器与鉴权层追踪
- [x] 7.1 创建 `apps/backend/app/trace/decorators.py`
- 实现 `trace_service(description_zh, description_en)` 装饰器
- 记录 SERVICE span：模块名、函数名、参数名+值、返回值摘要、耗时
- 当 DEV_TRACE_LOG_PARAMS=false 时省略参数值
- _Requirements: 2.2, 8.6_
- [x] 7.2 修改 `apps/backend/app/auth/dependencies.py`
- 在 get_current_user() / get_current_user_or_limited() 中添加 AUTH span
- 记录：token 前缀（非完整 token）、user_id、site_id、roles、审批状态
- 鉴权失败时记录详细原因分类：AUTH_EXPIRED / AUTH_INVALID / AUTH_MALFORMED / AUTH_LIMITED / AUTH_FORBIDDEN
- 将 user_id 和 site_id 写入 TraceContext
- _Requirements: 2.1, 2.5, 12.4_
- [x] 7.3 编写属性测试：Token 前缀截断
- **Property 4: Token 前缀截断**
- 生成任意长度 JWT token，验证 AUTH span 仅记录前缀
- **验证: 需求 2.5**
- [x] 7.4 编写属性测试：功能开关控制 Span 内容
- **Property 14: 功能开关控制 Span 内容**
- DEV_TRACE_LOG_SQL=false 时 DB_QUERY span 不含完整 SQL
- DEV_TRACE_LOG_PARAMS=false 时 SERVICE span 不含参数值
- **验证: 需求 8.5, 8.6**
- [x] 7.5 编写属性测试：鉴权失败原因分类
- **Property 20: 鉴权失败原因分类**
- 模拟各类鉴权失败场景，验证 AUTH span 的 failure_reason 正确分类
- **验证: 需求 12.4**
- [x] 8. 数据库连接包装与生命周期追踪
- [x] 8.1 创建 `apps/backend/app/trace/db_wrapper.py`
- 包装 cursor.execute()，记录 DB_QUERY span（SQL、参数、行数、耗时、调用来源）
- 包装 get_connection()，记录 DB_CONN span（连接获取耗时）
- 包装连接关闭，记录 DB_CONN_RELEASE span
- 数据库异常时记录 DB_ERROR span（PostgreSQL 错误码、消息、触发 SQL）
- 当 DEV_TRACE_LOG_SQL=false 时省略完整 SQL
- _Requirements: 2.3, 8.5, 12.3, 16.1, 16.2, 16.3_
- [x] 8.2 修改 `apps/backend/app/database.py`
- 在 get_connection() 中集成 trace db_wrapper（仅 trace 启用时包装）
- 不影响现有数据库连接逻辑
- _Requirements: 2.3, 16.1_
- [x] 8.3 编写属性测试：数据库连接生命周期配对
- **Property 21: 数据库连接生命周期配对**
- 验证每个 DB_CONN span 都有对应的 DB_CONN_RELEASE span
- **验证: 需求 16.3**
- [x] 9. 异常/错误全链路追踪
- [x] 9.1 创建 `apps/backend/app/trace/error_handler.py`
- 集成到全局异常处理器（http_exception_handler / unhandled_exception_handler）
- HTTPException → ERROR span（异常类型、status_code、detail、发生层级）
- 未捕获异常 → ERROR span（异常类型、消息、堆栈摘要前 5 行）
- 确保异常时 HTTP_OUT span 仍正确记录错误状态码
- 确保异常时 trace 仍能完整写入日志文件
- _Requirements: 12.1, 12.2, 12.5_
- [x] 9.2 修改 `apps/backend/app/middleware/response_wrapper.py`
- 在异常处理器中调用 trace error_handler 记录 ERROR span
- 不影响现有异常处理逻辑和响应格式
- _Requirements: 12.1, 12.2_
- [x] 9.3 编写属性测试：异常时 Trace 完整性
- **Property 16: 异常时 Trace 完整性**
- 模拟各类异常（HTTPException、未捕获异常、数据库异常），验证 trace 包含 ERROR/DB_ERROR span 且 HTTP_OUT span 仍存在
- **验证: 需求 12.1, 12.2, 12.3**
- [x] 10. xcx_* 路由与 Service 层装饰器集成
- [x] 10.1 为 xcx_* 路由处理函数添加 `@trace_service` 装饰器
- 覆盖：xcx_auth、xcx_tasks、xcx_notes、xcx_performance、xcx_chat、xcx_customers、xcx_coaches、xcx_board、xcx_config、xcx_ai_cache
- 每个路由函数添加中英文描述
- _Requirements: 11.1_
- [x] 10.2 为关键 Service 层函数添加 `@trace_service` 装饰器
- 优先覆盖联调涉及的 service：task_manager、note_service、performance_service、coach_service、customer_service、board_service、chat_service
- _Requirements: 2.2_
- [x] 11. 检查点 — 核心采集层验证
- 运行 `cd C:\Project\NeoZQYY && pytest tests/ -v` 确保属性测试通过
- 确保 xcx_* 请求能产生完整 span 链路（HTTP_IN → AUTH → SERVICE → DB_QUERY → DB_CONN → HTTP_OUT）
- 确保异常请求能产生 ERROR span
- 确保中间件层有 MIDDLEWARE span
- ask the user if questions arise.
### 阶段三：扩展采集层 — SSE + WebSocket + 后台 Job
- [x] 12. SSE 流式响应追踪
- [x] 12.1 创建 `apps/backend/app/trace/sse_wrapper.py`
- 包装 SSE event_generator，追踪流式响应全过程
- SSE_START span：流开始（端点、用户、chat_id）
- AI_CALL span：DashScope API 调用（app_id、prompt 长度、session_id）
- SSE_EVENT span：每 10 个 token 记录一次（避免 span 爆炸），含累计 token 数
- SSE_END span：流结束（总 token 数、总耗时、是否正常完成）
- AI_ERROR span：AI 调用失败（错误类型、消息）
- trace_type 设为 "sse"
- _Requirements: 13.1, 13.2, 13.3, 13.4, 13.5, 13.6_
- [x] 12.2 修改 `apps/backend/app/routers/xcx_chat.py`
- 在 chat_stream() 端点中集成 SSE trace wrapper
- 在 event_generator() 内部注入 trace context
- 不影响现有 SSE 事件格式和错误处理逻辑
- _Requirements: 13.1, 13.2_
- [x] 12.3 编写属性测试：SSE 流式 Trace 完整性
- **Property 17: SSE 流式 Trace 完整性**
- 验证 SSE trace 包含 SSE_START 和 SSE_END span，SSE_END 的 total_tokens 等于 SSE_EVENT 累计
- **验证: 需求 13.1, 13.2, 13.3**
- [x] 13. WebSocket 连接追踪
- [x] 13.1 创建 `apps/backend/app/trace/ws_wrapper.py`
- 包装 WebSocket 端点，追踪连接全生命周期
- WS_CONNECT span：连接建立（execution_id、客户端信息）
- WS_MESSAGE span：每 N 条消息记录一次（累计消息数、字节数）
- WS_DISCONNECT span：连接断开（原因、总消息数、总耗时）
- trace_type 设为 "ws"，request_id 用 `ws_` 前缀
- _Requirements: 14.1, 14.2, 14.3, 14.4_
- [x] 13.2 修改 `apps/backend/app/ws/logs.py`
- 在 ws_logs() 端点中集成 WS trace wrapper
- 不影响现有 WebSocket 逻辑和 TaskExecutor 订阅机制
- _Requirements: 14.1_
- [x] 13.3 编写属性测试：WebSocket Trace 生命周期
- **Property 18: WebSocket Trace 生命周期**
- 验证 WS trace 包含 WS_CONNECT 和 WS_DISCONNECT span，消息数一致
- **验证: 需求 14.1, 14.2**
- [x] 14. 后台 Job 执行追踪
- [x] 14.1 创建 `apps/backend/app/trace/job_wrapper.py`
- 包装 job handler 函数，追踪后台任务执行
- JOB_START span：任务开始（job_name、触发时间）
- 内部 SERVICE / DB_QUERY span 自动关联到 job trace（通过 contextvars）
- JOB_END span：任务正常结束（耗时、处理记录数）
- JOB_ERROR span：任务异常（异常类型、堆栈摘要）
- trace_type 设为 "job"，request_id 用 `job_` 前缀
- _Requirements: 15.1, 15.2, 15.3, 15.4, 15.5_
- [x] 14.2 修改 `apps/backend/app/main.py` lifespan 中的 job 注册
- 用 trace job_wrapper 包装 4 个 job handler：task_generator、task_expiry_check、recall_completion_check、note_reclassify_backfill
- 不影响现有 job 逻辑
- _Requirements: 15.1_
- [x] 14.3 编写属性测试：后台 Job Trace 完整性
- **Property 19: 后台 Job Trace 完整性**
- 验证 job trace 包含 JOB_START 和 JOB_END/JOB_ERROR span，内部 span 关联同一 request_id
- **验证: 需求 15.1, 15.2**
- [x] 15. 检查点 — 扩展采集层验证
- 运行 `cd C:\Project\NeoZQYY && pytest tests/ -v` 确保属性测试通过
- 确保 SSE 流式端点产生完整 trace（SSE_START → AI_CALL → SSE_EVENT → SSE_END）
- 确保 WebSocket 连接产生完整 trace（WS_CONNECT → WS_MESSAGE → WS_DISCONNECT）
- 确保后台 Job 产生完整 trace（JOB_START → SERVICE/DB_QUERY → JOB_END）
- ask the user if questions arise.
### 阶段四：后端 API + 前端页面
- [x] 16. 后端 API 路由
- [x] 16.1 创建 `apps/backend/app/routers/admin_dev_trace.py`
- `GET /api/admin/dev-trace/dates` — 返回有日志数据的日期列表
- `GET /api/admin/dev-trace/requests` — 按条件分页查询请求列表（date, start_time, end_time, trace_type, method, path_contains, status_code, min_duration, has_error, span_type, page, page_size）
- `GET /api/admin/dev-trace/request/{id}` — 返回指定 request_id 的完整 trace 记录（含所有 spans）
- `POST /api/admin/dev-trace/cleanup` — 按日期范围手动清理日志
- `GET /api/admin/dev-trace/settings` — 返回当前设置
- `PUT /api/admin/dev-trace/settings` — 更新运行时设置（不需重启）
- `GET /api/admin/dev-trace/coverage` — 返回最近一次覆盖率扫描结果
- `POST /api/admin/dev-trace/coverage/scan` — 手动触发覆盖率扫描
- 所有端点要求 admin 角色鉴权，非 admin 返回 403
- _Requirements: 6.1, 6.2, 6.3, 6.4, 6.5, 6.6, 7.1, 7.2, 7.3, 18.3, 18.4_
- [x] 16.2 创建 `apps/backend/app/trace/coverage.py`
- 实现覆盖率扫描器，通过 AST 解析 + inspect 检测以下维度：
- 路由覆盖：扫描 `app/routers/xcx_*.py` 中的路由函数，判断是否在 TraceMiddleware 路由前缀范围内
- Service 覆盖：扫描 `app/services/` 下所有公开函数（非 `_` 开头），检查是否有 `@trace_service` 装饰器
- Job 覆盖：扫描 lifespan 中注册的 job handler，检查是否被 `job_wrapper` 包装
- SSE/WS 覆盖：扫描 SSE/WS 端点，检查是否集成了对应 wrapper
- 输出结构：每个维度的 total、covered、uncovered 列表（含模块名和函数名）
- 扫描结果缓存在内存中，支持手动刷新
- 服务启动时自动扫描一次，之后按配置间隔定期扫描（默认 60 分钟）
- _Requirements: 18.1, 18.2, 18.5_
- [x] 16.3 在 `apps/backend/app/main.py` 中注册 admin_dev_trace router
- _Requirements: 6.1_
- [ ]* 16.4 编写属性测试：API 筛选正确性
- **Property 9: API 筛选正确性**
- 生成随机 trace 记录集合和筛选参数组合，验证返回结果满足所有筛选条件且无遗漏
- **验证: 需求 6.2**
- [ ]* 16.5 编写属性测试：Trace 写入-读取往返一致性
- **Property 10: Trace 写入-读取往返一致性**
- 写入 TraceContext 到日志文件，通过 API 按 request_id 查询，验证返回记录与原始数据等价
- **验证: 需求 6.3**
- [ ]* 16.6 编写属性测试：Admin 权限强制
- **Property 11: Admin 权限强制**
- 模拟非 admin 用户访问所有 Trace_API 端点，验证均返回 403
- **验证: 需求 6.5, 6.6**
- [ ]* 16.7 编写属性测试：设置更新往返一致性
- **Property 12: 设置更新往返一致性**
- 生成随机有效设置值，PUT 更新后 GET 读取，验证返回值与更新值一致
- **验证: 需求 7.2**
- [ ]* 16.8 编写属性测试：索引文件一致性
- **Property 7: 索引文件一致性**
- 执行一系列日志写入操作后，验证 `_index.json` 中每个引用文件存在、每个存在的日志文件被引用、记录数和文件大小匹配
- **验证: 需求 4.4, 4.5**
- [ ]* 16.9 编写属性测试：覆盖率扫描一致性
- **Property 22: 覆盖率扫描一致性**
- 验证扫描结果中每个维度的 total == covered + len(uncovered)
- 验证 uncovered 列表中的每个函数确实没有对应装饰器
- **验证: 需求 18.1, 18.2**
- [x] 17. 检查点 — 后端 API 验证
- 运行 `cd C:\Project\NeoZQYY && pytest tests/ -v` 确保属性测试通过
- 运行 `cd apps/backend && pytest tests/ -v` 确保后端测试通过
- 确保 6 个 API 端点均可正常响应，权限校验生效
- ask the user if questions arise.
- [x] 18. 前端 API 层与类型定义
- [x] 18.1 创建 `apps/admin-web/src/api/devTrace.ts`
- 封装所有 dev-trace API 调用（dates、requests、request/{id}、cleanup、settings、coverage、coverage/scan）
- _Requirements: 9.1, 10.1, 18.3, 18.4_
- [x] 18.2 创建 `apps/admin-web/src/types/devTrace.ts`
- 定义 TypeScript 类型：TraceRequest, TraceSpan, TraceDetail, TraceSettings, TraceFilter, TraceCoverage, CoverageCategory
- 包含所有 span_type 和 trace_type 枚举
- _Requirements: 9.4, 9.5, 18.6_
- [x] 19. 开发测试日志页面
- [x] 19.1 创建 `apps/admin-web/src/pages/DevTrace.tsx`
- 左右分栏布局（Ant Design Layout）
- 页面顶部：覆盖率状态栏（Alert 组件），展示路由/Service/Job/SSE/WS 各维度覆盖率百分比，未覆盖项列表，手动「扫描」按钮
- 左侧：请求列表（Table），展示 timestamp、trace_type、method、path、status_code、duration、db_query_count
- 右侧：选中请求的完整 span 链路树（层级缩进，span_type 颜色编码）
- 顶部：筛选栏（日期、时间范围、trace_type、方法、路径关键词、状态码、最小耗时、has_error、span_type）
- DB_QUERY span 展示 SQL 语句，ERROR span 红色高亮
- _Requirements: 9.1, 9.2, 9.3, 9.4, 9.5, 18.6, 18.7_
- [x] 19.2 在 `apps/admin-web/src/App.tsx` 中注册 DevTrace 页面路由和侧边栏菜单项
- _Requirements: 9.1_
- [x] 20. 设置面板
- [x] 20.1 在 DevTrace 页面中实现设置面板（Drawer 或 Modal）
- 日志开关（Switch，调用 settings API 即时生效）
- 保留天数配置（InputNumber + 保存按钮）
- SQL 记录开关、参数记录开关
- 手动清理（DateRangePicker + 清理按钮，展示清理结果）
- 磁盘占用统计展示
- 覆盖率扫描间隔配置（InputNumber，单位分钟，默认 60）
- _Requirements: 10.1, 10.2, 10.3, 10.4, 18.8_
- [x] 21. 检查点 — 前端页面验证
- 确保所有前端组件渲染正常，API 调用层工作正确
- 确保筛选、列表、span 树、设置面板交互流畅
- ask the user if questions arise.
### 阶段五：收尾
- [x] 22. 前后端联调与集成验证
- [x] 22.1 启动后端服务，使用测试库验证各端点完整请求-响应链路
- 发送 xcx_* 请求，验证 trace 日志文件正确生成
- 验证 JSON 响应结构与 Schema 定义一致（camelCase 序列化）
- 验证 admin 权限校验在真实请求中生效
- 验证响应头包含 X-Request-ID, X-Process-Time, X-DB-Queries, X-DB-Time
- _Requirements: 1.4, 6.5_
- [x] 22.2 前端联调验证
- 确认 DevTrace 页面能正确调用 API 并渲染请求列表和 span 链路树
- 验证按 trace_type 筛选（HTTP/SSE/WS/Job）工作正常
- 验证设置面板开关即时生效
- 验证空数据/降级场景下前端不崩溃
- _Requirements: 9.2, 9.3, 10.2_
- [x] 23. 文档同步更新
- [x] 23.1 更新后端 API 参考文档
- 在 `apps/backend/docs/API-REFERENCE.md` 新增 admin_dev_trace 路由模块文档（6 个端点）
- 更新 `apps/backend/README.md` 路由模块摘要（新增 trace 模块说明）
- _Requirements: 6.1_
- [x] 23.2 更新架构文档
- 在 `docs/architecture/backend-architecture.md` 新增 trace 模块架构说明
- [x] 23.3 更新文档地图
- 在 `docs/DOCUMENTATION-MAP.md` 新增本次模块条目
- _规范: doc-map.md_
- [x] 23.4 更新部署文档
- 在 `docs/deployment/EXPORT-PATHS.md` 新增 `DEV_TRACE_LOG_DIR` 路径说明
- _规范: export-paths.md_
- [x] 24. 最终检查点 — 全量验证
- 运行 Monorepo 属性测试：`cd C:\Project\NeoZQYY && pytest tests/ -v`
- 运行后端单元测试：`cd apps/backend && pytest tests/ -v`
- 确保所有属性测试（Property 1-22）和单元测试全部通过
- 确保 API 文档、后端 README、架构文档、文档地图、部署文档均已更新
- 确保前端页面连接真实后端运行正常
- 确保全链路覆盖：HTTP + SSE + WS + Job + 异常 + DB 连接 + 中间件
- 确保覆盖率扫描正确识别已覆盖和未覆盖的模块/函数
- ask the user if questions arise.
- [x] 25. 服务清理
- [x] 25.1 关闭浏览器、停止后端和前端服务、清理资源
- 停止 uvicorn 后端进程（controlPwshProcess stop）
- 停止前端开发服务器（controlPwshProcess stop）
## 备注
- 标记 `*` 的子任务为可选（属性测试），可跳过以加速 MVP
- 每个任务引用了具体的需求编号以确保可追溯性
- 属性测试验证通用正确性属性（Property 1-22），单元测试验证具体边界条件
- 检查点任务确保增量验证，避免问题累积
- 全链路覆盖范围：HTTP 请求 + SSE 流式 + WebSocket + 后台 Job + 异常/错误 + DB 连接生命周期 + 中间件层
- 本 spec 为全栈类，收尾遵循 `spec-closing-checklist.md`
Reference in New Issue View Git Blame Copy Permalink