Files

- .kiro/specs/ → docs/specs/（41 个历史需求 spec 迁移，移除 .config.kiro）
- CLAUDE.md 三层拆分：根文件精简 + apps/backend/CLAUDE.md + .claude/commands/
- 新增 /spec-close、/pre-change 两个工作流命令
- DDL 基线刷新（从测试库重新导出 11 个文件，dws 35→38 表，biz 18→21 表）
- BD_Manual → BD_manual 命名统一（48 个文件）
- 修复 3 处文档与数据库不一致（auth.users.status 默认值、scheduled_tasks 字段、RLS 视图数）
- 新增 BD_manual_public_rbac_tables.md（public schema 8 张 RBAC/工作流表）
- 合并 biz.trigger_jobs 文档（10→12 字段，归档独立文档）
- docs/database/README.md 索引更新

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-04-06 00:02:37 +08:00

24 KiB

Raw Blame History

实施计划：开发调试全链路日志系统（dev-trace-log）

概述

按依赖关系分五个阶段实施：基础设施层 → 核心采集层（HTTP + 鉴权 + DB + 中间件） → 扩展采集层（SSE + WebSocket + 后台 Job + 异常） → 后端 API + 前端页面 → 收尾。每个阶段完成后设置检查点验证。

后端使用 Python（FastAPI + contextvars），前端使用 TypeScript（React + Vite + Ant Design）。

覆盖范围：HTTP 请求全链路 + SSE 流式响应 + WebSocket 连接 + 后台 Job + 异常/错误 + 数据库连接生命周期 + 中间件层。

任务

阶段一：基础设施层 — Trace 核心模块

1. 环境变量与配置模块
- 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
- 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
2. TraceContext 与 TraceSpan 数据模型
- 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
- 2.2 编写属性测试：Request ID 唯一性
  - Property 1: Request ID 唯一性
  - 使用 Hypothesis 生成 N 个 TraceContext 实例，验证所有 request_id 互不相同
  - 验证: 需求 1.1
- 2.3 编写属性测试：Span 顺序保持
  - Property 2: Span 顺序保持
  - 生成随机 TraceSpan 序列并按顺序 add_span，验证 spans 列表保持插入顺序
  - 验证: 需求 1.5
3. JSON Lines 日志写入器
- 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
- 3.2 编写属性测试：TraceSpan 结构完整性
  - Property 3: TraceSpan 结构完整性
  - 使用 Hypothesis 生成任意 span_type 的 TraceSpan，验证序列化 JSON 包含所有必需字段
  - 生成任意 TraceContext，验证顶层 JSON 包含所有必需字段
  - 验证: 需求 2.4, 3.1, 3.2
- 3.3 编写属性测试：JSON 序列化往返一致性
  - Property 5: JSON 序列化往返一致性
  - 生成任意 TraceContext，序列化为 JSON line → 解析回 dict → 再序列化，验证两次输出等价
  - 验证: 需求 3.5
- 3.4 编写属性测试：日志文件路径生成
  - Property 6: 日志文件路径生成
  - 生成任意 datetime，验证目录名匹配 YYYY-MM-DD/，文件名匹配 trace_YYYY-MM-DD_HH.jsonl
  - 验证: 需求 4.1, 4.2
4. 日志自动清理模块
- 4.1 创建 apps/backend/app/trace/cleanup.py
  - 实现每日凌晨自动清理检查（可在 lifespan 中注册定时任务）
  - 删除超过配置保留天数的日期目录
  - 清理后更新 _index.json
  - Requirements: 5.1, 5.2, 5.3, 5.4
- 4.2 编写属性测试：清理保留期正确性
  - Property 8: 清理保留期正确性
  - 生成随机日期目录集合和保留天数 N，验证清理后：超期目录已删除、保留期内目录保留、索引不引用已删除目录
  - 验证: 需求 5.2, 5.4
5. 检查点 — 基础设施层验证
- 运行 cd C:\NeoZQYY && pytest tests/ -v 确保属性测试通过
- 确保 TraceContext、TraceWriter、TraceConfig、cleanup 模块可独立工作
- ask the user if questions arise.

阶段二：核心采集层 — HTTP + 鉴权 + DB + 中间件

6. TraceMiddleware（ASGI 中间件）
- 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
- 6.2 在 apps/backend/app/main.py 中注册 TraceMiddleware
  - 在 ResponseWrapperMiddleware 外层添加
  - 不影响现有 ResponseWrapperMiddleware 和 logging 配置
  - Requirements: 11.3
- 6.3 编写属性测试：路由前缀过滤
  - Property 15: 路由前缀过滤
  - 生成随机请求路径，验证仅 xcx_* 前缀路径产生 trace 数据
  - 验证: 需求 11.1, 11.2
- 6.4 编写属性测试：开关关闭时无 Trace 产出
  - Property 13: 开关关闭时无 Trace 产出
  - DEV_TRACE_ENABLED=false 时验证无 TraceContext 创建、无 span 记录、无日志写入
  - 验证: 需求 8.2, 8.3
7. 装饰器与鉴权层追踪
- 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
- 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
- 7.3 编写属性测试：Token 前缀截断
  - Property 4: Token 前缀截断
  - 生成任意长度 JWT token，验证 AUTH span 仅记录前缀
  - 验证: 需求 2.5
- 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
- 7.5 编写属性测试：鉴权失败原因分类
  - Property 20: 鉴权失败原因分类
  - 模拟各类鉴权失败场景，验证 AUTH span 的 failure_reason 正确分类
  - 验证: 需求 12.4
8. 数据库连接包装与生命周期追踪
- 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
- 8.2 修改 apps/backend/app/database.py
  - 在 get_connection() 中集成 trace db_wrapper（仅 trace 启用时包装）
  - 不影响现有数据库连接逻辑
  - Requirements: 2.3, 16.1
- 8.3 编写属性测试：数据库连接生命周期配对
  - Property 21: 数据库连接生命周期配对
  - 验证每个 DB_CONN span 都有对应的 DB_CONN_RELEASE span
  - 验证: 需求 16.3
9. 异常/错误全链路追踪
- 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
- 9.2 修改 apps/backend/app/middleware/response_wrapper.py
  - 在异常处理器中调用 trace error_handler 记录 ERROR span
  - 不影响现有异常处理逻辑和响应格式
  - Requirements: 12.1, 12.2
- 9.3 编写属性测试：异常时 Trace 完整性
  - Property 16: 异常时 Trace 完整性
  - 模拟各类异常（HTTPException、未捕获异常、数据库异常），验证 trace 包含 ERROR/DB_ERROR span 且 HTTP_OUT span 仍存在
  - 验证: 需求 12.1, 12.2, 12.3
10. xcx_* 路由与 Service 层装饰器集成
- 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
- 10.2 为关键 Service 层函数添加 @trace_service 装饰器
  - 优先覆盖联调涉及的 service：task_manager、note_service、performance_service、coach_service、customer_service、board_service、chat_service
  - Requirements: 2.2
11. 检查点 — 核心采集层验证
- 运行 cd C:\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

12. SSE 流式响应追踪
- 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
- 12.2 修改 apps/backend/app/routers/xcx_chat.py
  - 在 chat_stream() 端点中集成 SSE trace wrapper
  - 在 event_generator() 内部注入 trace context
  - 不影响现有 SSE 事件格式和错误处理逻辑
  - Requirements: 13.1, 13.2
- 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
13. WebSocket 连接追踪
- 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
- 13.2 修改 apps/backend/app/ws/logs.py
  - 在 ws_logs() 端点中集成 WS trace wrapper
  - 不影响现有 WebSocket 逻辑和 TaskExecutor 订阅机制
  - Requirements: 14.1
- 13.3 编写属性测试：WebSocket Trace 生命周期
  - Property 18: WebSocket Trace 生命周期
  - 验证 WS trace 包含 WS_CONNECT 和 WS_DISCONNECT span，消息数一致
  - 验证: 需求 14.1, 14.2
14. 后台 Job 执行追踪
- 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
- 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
- 14.3 编写属性测试：后台 Job Trace 完整性
  - Property 19: 后台 Job Trace 完整性
  - 验证 job trace 包含 JOB_START 和 JOB_END/JOB_ERROR span，内部 span 关联同一 request_id
  - 验证: 需求 15.1, 15.2
15. 检查点 — 扩展采集层验证
- 运行 cd C:\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 + 前端页面

16. 后端 API 路由
- 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
- 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
- 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
17. 检查点 — 后端 API 验证
- 运行 cd C:\NeoZQYY && pytest tests/ -v 确保属性测试通过
- 运行 cd apps/backend && pytest tests/ -v 确保后端测试通过
- 确保 6 个 API 端点均可正常响应，权限校验生效
- ask the user if questions arise.
18. 前端 API 层与类型定义
- 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
- 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
19. 开发测试日志页面
- 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
- 19.2 在 apps/admin-web/src/App.tsx 中注册 DevTrace 页面路由和侧边栏菜单项
  - Requirements: 9.1
20. 设置面板
- 20.1 在 DevTrace 页面中实现设置面板（Drawer 或 Modal）
  - 日志开关（Switch，调用 settings API 即时生效）
  - 保留天数配置（InputNumber + 保存按钮）
  - SQL 记录开关、参数记录开关
  - 手动清理（DateRangePicker + 清理按钮，展示清理结果）
  - 磁盘占用统计展示
  - 覆盖率扫描间隔配置（InputNumber，单位分钟，默认 60）
  - Requirements: 10.1, 10.2, 10.3, 10.4, 18.8
21. 检查点 — 前端页面验证
- 确保所有前端组件渲染正常，API 调用层工作正确
- 确保筛选、列表、span 树、设置面板交互流畅
- ask the user if questions arise.

阶段五：收尾

22. 前后端联调与集成验证
- 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
- 22.2 前端联调验证
  - 确认 DevTrace 页面能正确调用 API 并渲染请求列表和 span 链路树
  - 验证按 trace_type 筛选（HTTP/SSE/WS/Job）工作正常
  - 验证设置面板开关即时生效
  - 验证空数据/降级场景下前端不崩溃
  - Requirements: 9.2, 9.3, 10.2
23. 文档同步更新
- 23.1 更新后端 API 参考文档
  - 在 apps/backend/docs/API-REFERENCE.md 新增 admin_dev_trace 路由模块文档（6 个端点）
  - 更新 apps/backend/README.md 路由模块摘要（新增 trace 模块说明）
  - Requirements: 6.1
- 23.2 更新架构文档
  - 在 docs/architecture/backend-architecture.md 新增 trace 模块架构说明
- 23.3 更新文档地图
  - 在 docs/DOCUMENTATION-MAP.md 新增本次模块条目
  - 规范: doc-map.md
- 23.4 更新部署文档
  - 在 docs/deployment/EXPORT-PATHS.md 新增 DEV_TRACE_LOG_DIR 路径说明
  - 规范: export-paths.md
24. 最终检查点 — 全量验证
- 运行 Monorepo 属性测试：cd C:\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.
25. 服务清理
- 25.1 关闭浏览器、停止后端和前端服务、清理资源
  - 停止 uvicorn 后端进程（controlPwshProcess stop）
  - 停止前端开发服务器（controlPwshProcess stop）

备注

标记 * 的子任务为可选（属性测试），可跳过以加速 MVP
每个任务引用了具体的需求编号以确保可追溯性
属性测试验证通用正确性属性（Property 1-22），单元测试验证具体边界条件
检查点任务确保增量验证，避免问题累积
全链路覆盖范围：HTTP 请求 + SSE 流式 + WebSocket + 后台 Job + 异常/错误 + DB 连接生命周期 + 中间件层
本 spec 为全栈类，收尾遵循 spec-closing-checklist.md

24 KiB Raw Blame History Unescape Escape