104 lines
7.3 KiB
Markdown
104 lines
7.3 KiB
Markdown
---
|
|
name: 日志打点全量评估报告
|
|
overview: 全量审计 zt-closet-backend 项目中所有 slog 日志打点,从覆盖度(关键路径遗漏)、级别合理性、字段完整性、敏感信息、规范一致性等维度评估,在 docs/ 下产出一份日志专项评估报告(不改代码)。
|
|
todos:
|
|
- id: inventory-logging
|
|
content: 用 [subagent:code-explorer] 全量盘点所有 slog 打点明细及日志基础设施实现
|
|
status: completed
|
|
- id: audit-coverage
|
|
content: 用 [subagent:code-explorer] 对照业务主线、后台任务与资损路径审计日志覆盖遗漏点
|
|
status: completed
|
|
dependencies:
|
|
- inventory-logging
|
|
- id: audit-quality
|
|
content: 审计日志级别、字段完整性、敏感信息与规范一致性问题并分级
|
|
status: completed
|
|
dependencies:
|
|
- inventory-logging
|
|
- id: write-report
|
|
content: 撰写 docs/日志专项评估报告-2026-09-15.md(问题清单+覆盖矩阵+结论)
|
|
status: completed
|
|
dependencies:
|
|
- audit-coverage
|
|
- audit-quality
|
|
- id: verify-report
|
|
content: 抽查报告中文件行号引用与结论准确性,修正偏差并定稿
|
|
status: completed
|
|
dependencies:
|
|
- write-report
|
|
---
|
|
|
|
## User Requirements
|
|
|
|
对 zt-closet-backend 后端项目**代码中的日志打点**进行一次全量分析评估,核心问题:「是否存在遗漏与不足」。
|
|
|
|
- **遗漏评估**:关键业务路径(登录、上传、支付、退款、额度、AI 推荐、分享、通知等)、错误分支、后台任务失败分支、中间件异常分支是否存在日志缺失。
|
|
- **不足评估**:日志级别是否合理(Error/Warn/Info/Debug 误用)、关键字段是否完整、是否使用 Context 版本 API 以关联 trace_id/span_id、是否泄露敏感信息、字段命名与 msg 风格是否一致。
|
|
- **交付物**:在 docs/ 下新增一份日志专项评估报告,列出遗漏点与改进建议。
|
|
- **明确约束**:仅输出评估报告,**不修改任何代码**。
|
|
|
|
## Product Overview
|
|
|
|
产出一份中文 Markdown《日志专项评估报告》,面向开发/运维人员,作为后续日志优化工作的依据。报告需结论明确、可直接执行:每个问题带精确定位(文件:行号)、问题描述、影响说明与改进建议,并按严重度分级排序,便于后续按优先级逐项处理。
|
|
|
|
## Core Features
|
|
|
|
1. **日志基础设施盘点**:输出通道(文件+stdout+OTel 桥接)、滚动策略、级别配置映射、query 脱敏、trace_id/span_id 注入机制现状。
|
|
2. **全量打点清单与覆盖度对照矩阵**:覆盖全部 slog 调用点;对照 7 条业务主线、6 个后台任务、资损敏感路径(支付/退款回调、权益发放回收、额度扣减回退、鉴权降级)逐项标注有/无日志。
|
|
3. **多维度质量审计**:级别合理性、字段完整性(实体 ID)、敏感信息风险(openid/手机号/token/回调报文)、规范一致性(msg 风格、user_id/userID 命名、ctx 版本使用率)。
|
|
4. **结构化问题清单**:编号 + 严重度 + 位置 + 问题 + 影响 + 改进建议,风格对齐 docs/ 既有审查报告。
|
|
5. **总体结论**:遗漏与不足的总体判断及改进优先级建议。
|
|
|
|
## 审计方法(Implementation Approach)
|
|
|
|
采用**静态代码审计**方式,不运行服务、不依赖运行环境:
|
|
|
|
1. **盘点阶段**:全量收集所有 slog 调用点(文件、行号、级别、msg、字段、是否 `XxxContext` 版本),同步梳理日志基础设施实现:`main.go`(setupSlogLogger)、`pkg/tracing/fanout.go`、`pkg/tracing/otel.go`、`internal/middleware/logger.go`、配置项 `Log.LogLevel`。
|
|
2. **覆盖度审计**:以 README 的 7 条业务主线、6 个后台任务、历史审查报告标注的资损敏感路径为对照基准,逐个关键函数(handler → service → 错误/失败分支)标注日志有无,形成覆盖矩阵并识别遗漏。
|
|
3. **质量审计**:对每条打点按 6 个维度逐条检查:级别合理性、字段完整性、敏感信息、trace 关联、命名一致性、基础设施配置。
|
|
4. **撰写报告**:对齐 `docs/` 既有审查报告风格(中文、编号+严重度+位置+问题+影响+建议、修复状态可标注)。
|
|
5. **校验阶段**:抽查报告中 `文件:行号` 引用与结论准确性,修正偏差后定稿。
|
|
|
|
## 已知事实基准(用于对照)
|
|
|
|
- 打点总量约 200 处(非测试约 190+),分布:service 层约 110+、tokenhub/scheduler.go 16、main.go 13、middleware 3 处。
|
|
- **0 打点区域**:`internal/routers/`(15 文件)、`internal/mysqldao/`(19 文件)、`internal/redisdao/`(12 文件)、`pkg/` 除 tokenhub/tracing 外全部包;`internal/service/` 中 adreward.go、goods.go、horoscope.go 无打点。
|
|
- 基础设施:JSON 日志(lumberjack 滚动压缩 + stdout)+ otelslog 桥接;`OtelContextHandler` 仅在 `slog.XxxContext(ctx)` 调用时才注入 trace_id/span_id;`GinSlogMiddleware` 对 query 中 token/code/secret/password 等脱敏,但请求体不记录。
|
|
- 其他输出:main.go:320、pkg/tracing/provider.go:114 用 fmt.Printf(logger 未就绪场景);cmd/migrate 用 fmt.Println(CLI,不纳入问题清单)。
|
|
|
|
## 评估维度框架(6 项)
|
|
|
|
1. 覆盖度/遗漏;2. 级别合理性;3. 字段完整性;4. 敏感信息;5. 规范一致性;6. 基础设施配置(如 LogLevel=Info 时 Debug 打点在生产的有效性)。
|
|
|
|
## 报告结构设计
|
|
|
|
1. 审计范围与方法说明(含局限:未连接运行环境、以当前工作区代码为准);
|
|
2. 日志基础设施现状;
|
|
3. 问题清单(按 高/中/低 分级,每条含位置+问题+影响+建议);
|
|
4. 关键路径日志覆盖度对照矩阵;
|
|
5. 总体结论与改进优先级建议。
|
|
|
|
## Implementation Notes(执行要点)
|
|
|
|
- 所有问题必须带 `文件:行号` 引用,行号以**当前工作区**文件为准(工作区存在未提交改动,不得依据历史报告行号)。
|
|
- 严重度分级原则:资损/安全相关遗漏(如支付校验失败静默、权益回收无日志)为高;排查困难类(无实体 ID、缺 ctx 关联)为中;规范统一类(命名/风格)为低。
|
|
- 报告中描述敏感字段时仅引用字段名,不复制任何真实敏感值;不打印任何配置密钥内容。
|
|
- 结论表述为建议(如"建议补充……"),不包含代码修改动作;不再引入与日志无关的审查项(如业务逻辑缺陷),聚焦日志主题。
|
|
|
|
## Directory Structure
|
|
|
|
本次仅新增 1 个文件,不修改任何代码:
|
|
|
|
```
|
|
zt-closet-backend/
|
|
└── docs/
|
|
└── 日志专项评估报告-2026-09-15.md # [NEW] 日志专项评估报告。内容:审计范围与方法说明、日志基础设施现状盘点、按严重度分级的问题清单(编号+位置+问题+影响+改进建议,覆盖遗漏与不足两类)、关键业务路径日志覆盖度对照矩阵、总体结论与改进优先级建议。需对齐 docs/ 既有审查报告的中文风格与"文件:行号"引用规范,所有结论须经代码抽查验证。
|
|
```
|
|
|
|
## Agent Extensions
|
|
|
|
### SubAgent
|
|
|
|
- **code-explorer**
|
|
- Purpose: 承担跨目录的大规模代码探索:全量收集所有 slog 调用点清单(位置/级别/字段/上下文版本)与日志基础设施实现细节;并对照业务主线逐个关键路径函数核实日志覆盖情况。
|
|
- Expected outcome: 产出结构化的打点明细清单与关键路径覆盖情况数据,作为评估报告"问题清单"与"覆盖度对照矩阵"的可靠事实依据,确保报告中所有定位与结论准确可核验。 |