---
name: 按层区分 DAO span 命名
overview: 将 mysqldao 的 span 名由 dao.X 改为 mysqldao.X、redisdao 的改为 redisdao.X，共 140 处，解决两层 span 名无法区分的问题。
todos:
  - id: rename-mysqldao
    content: 批量替换 internal/mysqldao 下 109 处 span 前缀为 mysqldao.
    status: completed
  - id: rename-redisdao
    content: 批量替换 internal/redisdao 下 31 处 span 前缀为 redisdao.
    status: completed
  - id: verify-rename
    content: 用 [subagent:code-explorer] 复核前缀计数与无残留无错改
    status: completed
    dependencies:
      - rename-mysqldao
      - rename-redisdao
  - id: sync-readme
    content: 在 README 目录说明中补充 span 命名约定
    status: completed
    dependencies:
      - verify-rename
  - id: build-verify
    content: 执行 go build ./... 与 go vet ./... 验证
    status: completed
    dependencies:
      - verify-rename
      - sync-readme
---

## 产品概述

统一调整 OTel span 命名前缀：数据访问层的 span 名由通用的 `dao.XXX` 改为可区分来源的 `mysqldao.XXX` 与 `redisdao.XXX`，解决 MySQL 与 Redis 两层调用在链路追踪中无法区分的问题。

## 核心功能

- **MySQL 层改名**：`internal/mysqldao/` 下全部 109 处 span 名前缀 `dao.` 改为 `mysqldao.`
- **Redis 层改名**：`internal/redisdao/` 下全部 31 处 span 名前缀 `dao.` 改为 `redisdao.`
- **命名一致性保持**：仅改前缀，方法名（如 `UserInfoSet`）、业务逻辑、其他 span 属性均不变
- **不影响其他层**：`internal/service`（`service.`）、`pkg/upload`（`upload.`）、`pkg/tokenhub`（`scheduler.`）保持原样
- **可维护性**：README 目录说明补一句 span 命名约定，避免后续新增代码再用回 `dao.`

## 技术栈

- Go 1.27，模块 `git.lzcwy.cn/zhengchiliu/zt-closet-backend`
- OpenTelemetry Trace（`global.Tracer`，OTLP gRPC 上报）
- span 创建统一写法：`ctx, span := global.Tracer.Start(ctx, "<前缀>.<方法名>")`

## 实现方案

采用**目录限定的批量字符串替换**：把 `global.Tracer.Start(ctx, "dao.` 中的前缀分别替换为 `mysqldao.` / `redisdao.`，替换范围严格限定在 `internal/mysqldao/` 与 `internal/redisdao/` 两个目录。

关键决策与取舍：

1. **前缀命名用 `mysqldao.` / `redisdao.` 而非 `mysql.` / `redis.`**：与包名（`package mysqldao` / `package redisdao`）完全一致，Go 项目中 span 名即包名+方法名，排查时可从 span 名直接定位到文件与包，无需映射记忆。
2. **批量 sed 而非逐处手改**：140 处手工改必漏；用 `sed -i 's/Tracer\.Start(ctx, "dao\./Tracer.Start(ctx, "mysqldao./g'` 这类按目录执行的命令可保证一致性与完整性，且模式串锚定了 `Tracer.Start(ctx, "dao.` 全串，不会误伤字符串变量、注释或日志中的 `dao.`。
3. **只改前缀，不改方法名**：方法名与所在函数名一一对应，改名会造成与函数名不一致的二次困惑；同时避免破坏任何按名称检索的既有习惯。
4. **不引入常量**：项目其余前缀（`service.`、`upload.`、`scheduler.`）均为字面量，沿用字面量保持风格统一，不引入新的抽象层（YAGNI）。
5. **不改动 service / upload / tokenhub**：这些层前缀本身已能区分，不属于本次「分不清」的范围，缩小改动面。

性能与可靠性：

- span 名为启动期/调用期构造的字符串常量，改为更长前缀无运行时开销（无额外分配语义变化）。
- 风险点仅为「替换不完整」或「误伤其他目录」，通过目录限定 + 替换后计数校验（mysqldao 109 / redisdao 31 / 残留 `dao.` 为 0）来兜底。

## 实现要点（防回归）

- 替换模式必须锚定完整串 `global.Tracer.Start(ctx, "dao.`，避免误改 `mysqldao.`/`redisdao.` 之外的其它 `dao` 文本（如注释、错误信息）。
- 严格限定目录：`internal/mysqldao/*.go` 与 `internal/redisdao/*.go`，**不要**对仓库根或 `internal/` 整体执行替换（会误伤 `internal/service` 中可能存在的同名串）。
- 替换后必须核验：`internal/mysqldao` 与 `internal/redisdao` 中 `"dao.` 残留为 0；`"mysqldao.` 计数 109、`"redisdao.` 计数 31（与替换前一致）。
- 未发现任何测试或断言依赖 span 名字符串，改名不会破坏断言；仍以 `go build ./...` + `go vet ./...` 作为回归基线。
- 不改动 `configs/config.yaml`（第 2 行 `Domain: *` 为非法 YAML，属用户本地配置，本次不处理）。

## 架构设计

调用链与 span 命名分层（本次改动仅涉及最下两层的命名）：

```mermaid
flowchart TD
    A["routers/api/v1 handler<br/>Gin 中间件 server span"] --> B["internal/service<br/>span: service.Xxx"]
    B --> C["internal/mysqldao<br/>span: mysqldao.Xxx（本次由 dao. 改名）"]
    B --> D["internal/redisdao<br/>span: redisdao.Xxx（本次由 dao. 改名）"]
    C --> E[("MySQL")]
    D --> F[("Redis")]
```

## 目录结构

```
internal/mysqldao/
├── quota.go                  # [MODIFY] 18 处 span 前缀 dao. → mysqldao.
├── outfit.go                 # [MODIFY] 13 处
├── order.go                  # [MODIFY] 12 处
├── clothes.go                # [MODIFY] 9 处
├── closet.go                 # [MODIFY] 8 处
├── user.go                   # [MODIFY] 7 处
├── horoscope.go              # [MODIFY] 7 处
├── benefit_grant_task.go     # [MODIFY] 7 处
├── collect.go                # [MODIFY] 6 处
├── like.go                   # [MODIFY] 6 处
├── notification.go           # [MODIFY] 6 处
├── auditlog.go               # [MODIFY] 4 处
├── goods.go                  # [MODIFY] 3 处
└── vipflowlog.go             # [MODIFY] 3 处
internal/redisdao/
├── quota.go                  # [MODIFY] 6 处 span 前缀 dao. → redisdao.
├── collect.go                # [MODIFY] 4 处
├── like.go                   # [MODIFY] 4 处
├── auth.go                   # [MODIFY] 4 处
├── notification.go           # [MODIFY] 4 处
├── user.go                   # [MODIFY] 3 处
├── horoscope.go              # [MODIFY] 2 处
├── lock.go                   # [MODIFY] 2 处
├── outfit.go                 # [MODIFY] 1 处
└── closet.go                 # [MODIFY] 1 处
README.md                     # [MODIFY] 可选：目录树中 mysqldao/redisdao 说明补 span 命名约定（mysqldao.* / redisdao.*）
```

## Agent Extensions

### SubAgent

- **code-explorer**
- Purpose：替换完成后复核两个 DAO 目录的 span 命名：确认 `internal/mysqldao` 全部为 `mysqldao.` 前缀、`internal/redisdao` 全部为 `redisdao.` 前缀、无 `"dao.` 残留，且 `internal/service`、`pkg/upload`、`pkg/tokenhub` 的 span 名未被误改
- Expected outcome：输出各目录前缀计数与残留清单，确保 140 处全部正确改名、零误伤