zt-closet-backend/.codebuddy/plans/日志打点全量评估报告_41e5bf30.md

name, overview, todos

name	overview	todos
日志打点全量评估报告	全量审计 zt-closet-backend 项目中所有 slog 日志打点,从覆盖度(关键路径遗漏)、级别合理性、字段完整性、敏感信息、规范一致性等维度评估,在 docs/ 下产出一份日志专项评估报告(不改代码)。	id content status inventory-logging 用 [subagent:code-explorer] 全量盘点所有 slog 打点明细及日志基础设施实现 completed id content status dependencies audit-coverage 用 [subagent:code-explorer] 对照业务主线、后台任务与资损路径审计日志覆盖遗漏点 completed inventory-logging id content status dependencies audit-quality 审计日志级别、字段完整性、敏感信息与规范一致性问题并分级 completed inventory-logging id content status dependencies write-report 撰写 docs/日志专项评估报告-2026-09-15.md(问题清单+覆盖矩阵+结论) completed audit-coverage audit-quality id content status dependencies verify-report 抽查报告中文件行号引用与结论准确性,修正偏差并定稿 completed 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: 产出结构化的打点明细清单与关键路径覆盖情况数据,作为评估报告"问题清单"与"覆盖度对照矩阵"的可靠事实依据,确保报告中所有定位与结论准确可核验。