Neo-ZQYY/docs/audit/changes/2026-03-22__dev-trace-log-fullstack-feature.md

变更审计记录：dev-trace-log 全栈开发调试全链路日志系统

字段	值
日期	2026-03-22 21:03:24
Prompt-ID	P20260322-205347
Session-ID	93568fb4
Session 路径	docs/audit/session_logs/2026-03/22/66_5460a155_203419

操作摘要

执行 .kiro/specs/dev-trace-log/ 全部 25 个任务，实现开发调试全链路日志系统（dev-trace-log）。这是一个全栈 feature，覆盖：

• 后端 trace 采集层：HTTP 请求（ASGI 中间件）、SSE 流式响应、WebSocket 连接、后台 Job 执行
• JSON Lines 日志写入器（按日期/小时分文件，10MB 轮转，自动清理）
• 8 个 admin API 端点（含覆盖率扫描、运行时开关）
• admin-web 前端 DevTrace 页面（覆盖率条、过滤器、请求表格、Span 树、设置抽屉）
• 40 个属性测试全部通过（19.69s）

风险评估：低。trace 模块通过 DEV_TRACE_ENABLED 开关控制，关闭时零开销。所有采集逻辑 try/except 包裹，不影响正常请求处理。无 DB schema 变更。

本次对话文件变更

新增文件（Session 日志 + Prompt 日志）

• docs/audit/prompt_logs/prompt_log_20260322_205347.md
• docs/audit/session_logs/2026-03/22/66_5460a155_203419/main_01_93568fb4.md
• docs/audit/session_logs/2026-03/22/66_5460a155_203419/sub_01_93568fb4.md
• docs/audit/session_logs/2026-03/22/66_5460a155_203419/sub_02_93568fb4.md
• docs/audit/session_logs/2026-03/22/67_f11b5687_205015/main_01_761a13a1.md
• docs/audit/session_logs/2026-03/22/67_f11b5687_205015/sub_01_93568fb4.md
• docs/audit/session_logs/2026-03/22/68_a233cc02_205218/main_01_c0515e2b.md

改动注解

后端 trace 模块（新建）

apps/backend/app/trace/__init__.py

• 变更类型：新增
• 原始原因：dev-trace-log spec Task 1，建立 trace 模块入口
• 思路分析：模块入口文件，导出核心组件供外部使用
• 修改结果：trace 模块可通过 from app.trace import ... 引用

apps/backend/app/trace/config.py

• 变更类型：新增
• 原始原因：Task 1，集中管理 trace 配置（环境变量 + 运行时开关）
• 思路分析：TraceConfig 数据类，从环境变量读取 DEV_TRACE_ENABLED、DEV_TRACE_LOG_DIR、DEV_TRACE_RETENTION_DAYS 等，支持运行时动态开关
• 修改结果：所有 trace 组件统一从 TraceConfig 读取配置，关闭时零开销

apps/backend/app/trace/context.py

• 变更类型：新增
• 原始原因：Task 2，定义 TraceContext 和 TraceSpan 数据模型
• 思路分析：使用 Python contextvars 实现请求级隔离，TraceContext 持有 trace_id + span 列表，TraceSpan 记录单个操作的耗时和元数据
• 修改结果：所有采集点通过 contextvars 自动关联到当前请求的 trace

apps/backend/app/trace/writer.py

• 变更类型：新增
• 原始原因：Task 3，JSON Lines 日志写入器
• 思路分析：按日期/小时分文件写入，单文件 10MB 轮转，异步写入不阻塞请求。提供 _sync_write() 供同步上下文（WS/Job wrapper）调用
• 修改结果：trace 数据持久化到 DEV_TRACE_LOG_DIR 目录

apps/backend/app/trace/cleanup.py

• 变更类型：新增
• 原始原因：Task 4，日志自动清理
• 思路分析：按 DEV_TRACE_RETENTION_DAYS 配置删除过期日志文件
• 修改结果：防止日志无限增长占满磁盘

apps/backend/app/trace/middleware.py

• 变更类型：新增
• 原始原因：Task 6，ASGI 中间件拦截 HTTP 请求
• 思路分析：TraceMiddleware 拦截 xcx_* 路由的请求，创建 TraceContext，记录请求/响应元数据，请求结束时写入 trace
• 修改结果：所有小程序 API 请求自动被 trace 采集

apps/backend/app/trace/decorators.py

• 变更类型：新增
• 原始原因：Task 7，@trace_service 装饰器
• 思路分析：装饰器自动为 service 函数创建 span，记录入参摘要、返回值类型、异常信息
• 修改结果：service 层函数加一行装饰器即可接入 trace

apps/backend/app/trace/db_wrapper.py

• 变更类型：新增
• 原始原因：Task 8，数据库连接生命周期追踪
• 思路分析：包装数据库连接获取/释放，记录连接耗时和 SQL 执行信息
• 修改结果：数据库操作在 trace 中可见

apps/backend/app/trace/error_handler.py

• 变更类型：新增
• 原始原因：Task 9，异常/错误全链路追踪
• 思路分析：捕获未处理异常，在当前 trace 中记录错误堆栈和上下文
• 修改结果：错误信息自动关联到触发请求的 trace

apps/backend/app/trace/sse_wrapper.py

• 变更类型：新增
• 原始原因：Task 12，SSE 流式响应追踪
• 思路分析：包装 SSE 事件生成器，记录每个事件的发送时间和数据摘要
• 修改结果：AI 聊天等 SSE 接口的流式响应过程可追踪

apps/backend/app/trace/ws_wrapper.py

• 变更类型：新增
• 原始原因：Task 13，WebSocket 连接追踪
• 思路分析：包装 WS 连接的 accept/send/receive/close，使用 _sync_write() 避免异步上下文问题
• 修改结果：WebSocket 日志推送连接的生命周期可追踪

apps/backend/app/trace/job_wrapper.py

• 变更类型：新增
• 原始原因：Task 14，后台 Job 执行追踪
• 思路分析：包装后台任务执行函数，记录 job 名称、耗时、成功/失败状态。同样使用 _sync_write() 处理同步上下文
• 修改结果：后台定时任务和一次性 job 的执行过程可追踪

apps/backend/app/trace/coverage.py

• 变更类型：新增
• 原始原因：Task 16.2，覆盖率扫描器
• 思路分析：grep 方式扫描代码库，统计已接入 trace 的路由/service/WS 端点占比
• 修改结果：admin API 可查询当前 trace 覆盖率

后端 API（新建）

apps/backend/app/routers/admin_dev_trace.py

• 变更类型：新增
• 原始原因：Task 16.1，admin API 端点
• 思路分析：8 个端点：查询 trace 列表、trace 详情、覆盖率、运行时开关、清理日志等。所有端点需 admin 鉴权
• 修改结果：管理后台可通过 API 查看和管理 trace 数据

前端（新建）

apps/admin-web/src/types/devTrace.ts

• 变更类型：新增
• 原始原因：Task 18.2，TypeScript 类型定义
• 思路分析：定义 TraceRecord、TraceSpan、CoverageReport 等接口类型，与后端 API 响应对齐
• 修改结果：前端类型安全

apps/admin-web/src/api/devTrace.ts

• 变更类型：新增
• 原始原因：Task 18.1，API 调用层
• 思路分析：8 个 API 函数对应 8 个后端端点，使用 apiClient 统一处理鉴权和错误
• 修改结果：前端页面可调用 trace API

apps/admin-web/src/pages/DevTrace.tsx

• 变更类型：新增
• 原始原因：Task 19-20，DevTrace 页面 + 设置抽屉
• 思路分析：完整页面包含覆盖率进度条、时间/路由/状态过滤器、请求列表表格、Span 树展开、SettingsDrawer 运行时配置面板
• 修改结果：管理后台新增 DevTrace 功能页面

测试文件（新建）

tests/test_trace_*.py（10 个文件）

• 变更类型：新增
• 原始原因：Task 5/11/15 各阶段 checkpoint 要求的属性测试
• 思路分析：使用 hypothesis 框架，覆盖 TraceContext 创建/嵌套、Writer 写入/轮转、Cleanup 过期删除、Middleware 路由匹配、Decorator 异常处理、DB/SSE/WS/Job wrapper 等 40 个属性
• 修改结果：40/40 属性测试通过，验证 trace 模块核心逻辑正确性

已有文件修改（简要注解）

• apps/backend/app/main.py — 注册 TraceMiddleware、job trace wrappers、admin_dev_trace router
• apps/backend/app/database.py — 集成 trace db_wrapper
• apps/backend/app/auth/dependencies.py — 添加 AUTH span 记录
• apps/backend/app/middleware/response_wrapper.py — 集成 error_handler 调用
• apps/backend/app/routers/xcx_chat.py — SSE trace 集成
• apps/backend/app/routers/xcx_auth.py — 添加 @trace_service
• apps/backend/app/routers/xcx_tasks.py — 添加 @trace_service
• apps/backend/app/routers/xcx_notes.py — 添加 @trace_service
• apps/backend/app/routers/xcx_performance.py — 添加 @trace_service
• apps/backend/app/routers/xcx_ai_cache.py — 添加 @trace_service
• apps/backend/app/routers/xcx_customers.py — 添加 @trace_service
• apps/backend/app/routers/xcx_coaches.py — 添加 @trace_service
• apps/backend/app/routers/xcx_board.py — 添加 @trace_service
• apps/backend/app/routers/xcx_config.py — 添加 @trace_service
• apps/backend/app/services/task_manager.py — 添加 @trace_service
• apps/backend/app/services/note_service.py — 添加 @trace_service
• apps/backend/app/services/performance_service.py — 添加 @trace_service
• apps/backend/app/services/coach_service.py — 添加 @trace_service
• apps/backend/app/services/customer_service.py — 添加 @trace_service
• apps/backend/app/services/board_service.py — 添加 @trace_service
• apps/backend/app/services/chat_service.py — 添加 @trace_service
• apps/backend/app/ws/logs.py — WS trace 集成
• apps/admin-web/src/App.tsx — DevTrace 路由 + 菜单项
• .env — 添加 trace 环境变量（DEV_TRACE_ENABLED 等）
• .env.template — 添加 trace 环境变量模板
• apps/backend/docs/API-REFERENCE.md — admin_dev_trace 路由文档
• apps/backend/README.md — trace 模块说明
• docs/architecture/backend-architecture.md — trace 模块架构
• docs/DOCUMENTATION-MAP.md — 新增 trace 相关条目
• docs/deployment/EXPORT-PATHS.md — DEV_TRACE_LOG_DIR

合规检查

检查项	状态
文档同步	✅ 无缺失（code_without_docs 为空）
新增迁移 SQL	✅ 无（纯应用层，无 DB 变更）
DDL 基线	⚠️ has_ddl_baseline=false，但本次无新增迁移，不影响
OpenAPI spec	✅ 无需同步（api_changed=false）
BD 手册	✅ 无需更新（无 DB schema 变更）

验证结果

• 40 个属性测试全部通过（19.69s）
• 无 DB 变更
• 无安全风险（admin 鉴权保护所有 trace API）
• trace 模块通过开关控制，关闭时零开销