Neo
14a12342b5
这些审计记录原本堆积在 docs/audit/changes/changes/ 嵌套误产物目录下（由开发机迁移
79d3c2e 前后的不明批量操作产生）。由于同期 .gitignore 屏蔽了 docs/audit/ 全目录，
它们从未入过 git 任何分支 history。删除即永久丢失。
按 docs/specs/audit-gap-recovery/tasks.md 阶段 1 执行，将全部 96 份 D 类孤本
（主目录无同名、git history 亦无记录）复制到 docs/audit/changes/ 主目录入仓。
涵盖主题: P1-P18 全栈集成 / 多模块累积变更 / ETL bug 修复 / 业务日切 /
召回与任务引擎改造 / 租户管理与审批 / 董事会财务 / 客户与助教详情 /
DDL 基线合并 / Kiro 到 Claude Code 迁移
阶段 2（B 类内容漂移 1 份）和阶段 4（嵌套目录删除）独立推进。
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
199 lines
10 KiB
Markdown
199 lines
10 KiB
Markdown
# 变更审计记录：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 模块通过开关控制，关闭时零开销
|