Neo-ZQYY/docs/specs/dev-trace-log/tasks.md

# 实施计划：开发调试全链路日志系统（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`