---
name: service-span-and-async-trace
overview: 给 service 层所有对外入口方法补埋 span（svc.Xxx），并修复 clothes 上传异步 goroutine 的 trace 断链，使调用链可读、异步链路可关联。
todos:
  - id: clothes-spans
    content: 为 clothes.go 的 6 个入口方法（Upload、ProcessStatusGetByUUID、GetByUUID、UpdateByUUID、DeleteByUUID、List）补埋 svc span
    status: completed
  - id: clothes-async-trace
    content: 修复 clothes.go 异步断链：改造 processImageAsync 签名与 ctx 派生、补 svc.ProcessImageAsync span、更新调用点、新增 otel/trace import
    status: completed
    dependencies:
      - clothes-spans
  - id: outfit-closet-collect-like-spans
    content: 为 outfit.go、closet.go、collect.go、like.go 的入口方法补埋 svc span 并新增 global import
    status: completed
  - id: notification-quota-user-goods-horoscope-spans
    content: 为 notification.go、quota.go、user.go、goods.go、horoscope.go 的入口方法补埋 svc span 并补充所需 import
    status: completed
  - id: order-airecommend-spans
    content: 为 order.go、airecommend.go 的入口方法补埋 svc span 并新增 global import
    status: completed
  - id: build-vet-verify
    content: 运行 go build ./... 与 go vet ./... 验证编译与静态检查通过
    status: completed
    dependencies:
      - clothes-spans
      - clothes-async-trace
      - outfit-closet-collect-like-spans
      - notification-quota-user-goods-horoscope-spans
      - order-airecommend-spans
---

## 用户需求

1. 在 service 层对外入口方法补埋 OpenTelemetry span，使 trace 调用链可读。
2. 修复衣物上传异步 goroutine 的 trace 断链，使抠图、COS 上传、分类、回填等异步 DAO span 能关联回原请求。

## 功能内容

- 为 12 个 service 文件、共 41 个对外入口方法（首字母大写的导出方法）统一补埋 `svc.Xxx` span，命名与现有 `dao.Xxx`、`upload.Xxx` 前缀保持一致。
- 私有辅助方法不埋点，避免产生过深的 span 森林。
- 修复 `processImageAsync` 使用 `context.Background()` 导致异步链路丢失父 trace 的问题，通过 `trace.ContextWithSpanContext` 继承 trace 信息、同时切断取消信号。
- 异步分支补一个 `svc.ProcessImageAsync` span，将异步处理在 trace 中聚合成一个独立分组。

## 视觉/可观测效果

- 在 trace 平台中，每个 HTTP 请求下能看到 `svc.Xxx` 容器 span，其下嵌套对应业务调用的 `dao.Xxx`、`upload.Xxx` span，调用层次清晰。
- 衣物上传后，后台异步处理（抠图、COS、分类、回填）不再生成孤立 trace，而是挂在原请求（或 `svc.ProcessImageAsync`）之下，便于端到端排查。

## Tech Stack

- 语言：Go 1.27
- 可观测：OpenTelemetry Trace（已接入，`global.Tracer`）
- Web 框架：Gin（API 层已由 `otelgin.Middleware` 自动埋 server span，本次不涉及）

## Implementation Approach

采用「只补边界、不埋全程」的埋点策略：

1. service 入口方法方法体开头统一插入：

```
ctx, span := global.Tracer.Start(ctx, "svc.Xxx")
defer span.End()
```

span 名 = `svc.` + 方法名。通过覆盖入口方法，使 DAO/upload 子 span 在 trace 中正确归属到业务动作。

2. 修复异步断链：将 `processImageAsync` 签名改为接收 `parentCtx context.Context`，内部用：

```
ctx, cancel := context.WithTimeout(trace.ContextWithSpanContext(context.Background(), trace.SpanContextFromContext(parentCtx)), 3*time.Minute)
```

继承父 trace 的 span context，但用 `context.Background()` 切断请求 ctx 的取消信号（保证请求结束后 goroutine 仍能运行），再补 `svc.ProcessImageAsync` span 聚合异步分支。

## Implementation Notes

- service 层 span 只做 start/end，不调用 `span.RecordError`：service 方法返回 `*errcode.Error` 且在多个 return 点返回，若记录错误需改成具名返回值，侵入过大；本次目标为调用链可读，span 嵌套与耗时已满足需求。
- 需新增 `global` import 的文件：order.go、goods.go、outfit.go、horoscope.go、collect.go、closet.go、like.go、notification.go；airecommend.go、clothes.go、user.go、quota.go 已导入 `global`。
- clothes.go 需新增 `go.opentelemetry.io/otel/trace` import（go.mod 已包含该依赖）。
- 保持与现有 DAO 埋点风格一致：span 名用 `dao.Xxx`/`upload.Xxx` 相同的大写方法名风格，不引入新的埋点封装或 helper，避免与现有约定不一致。

## Directory Structure

```
internal/service/
├── clothes.go       # [MODIFY] 6 个入口方法补 span；processImageAsync 签名改造、trace 传播修复、新增 svc.ProcessImageAsync span、更新调用点、新增 otel/trace import
├── outfit.go        # [MODIFY] Create/GetByUUID/UpdateByUUID/List/Delete/Public 补 span；新增 global import
├── closet.go        # [MODIFY] Create/Detail/List/Cancel 补 span；新增 global import
├── collect.go       # [MODIFY] Collect/List 补 span；新增 global import
├── like.go          # [MODIFY] LikeCreate/GetByTargetID 补 span；新增 global import
├── notification.go  # [MODIFY] List/GetByUUID/Read/Unread 补 span；新增 global import
├── quota.go         # [MODIFY] InfoGetBySelf/FlowList 补 span（global 已导入）
├── user.go          # [MODIFY] WxLogin/InfoGetBySelf/ProfileUpdate/RefreshToken 补 span（global 已导入）
├── goods.go         # [MODIFY] GetByCode/List 补 span；新增 global import
├── horoscope.go     # [MODIFY] GetToday 补 span；新增 global import
├── order.go         # [MODIFY] Create/PayNotify/Cancel/List/RefundApply/RefundNotify 补 span；新增 global import
└── airecommend.go   # [MODIFY] Create/Save 补 span（global 已导入）
```