# 邮箱变更

<cite>
**本文引用的文件**
- [user_handler.go](file://internal/handler/user_handler.go)
- [routes.go](file://internal/handler/routes.go)
- [auth.go](file://internal/middleware/auth.go)
- [verification_service.go](file://internal/service/verification_service.go)
- [user_service.go](file://internal/service/user_service.go)
- [user_repository.go](file://internal/repository/user_repository.go)
- [common.go](file://internal/types/common.go)
- [response.go](file://internal/model/response.go)
- [redis.go](file://pkg/redis/redis.go)
- [email.go](file://pkg/email/email.go)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能与可靠性](#性能与可靠性)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)

## 简介
本文档围绕“POST /api/v1/user/change-email”端点，系统化阐述邮箱变更的完整流程与技术实现细节。该接口要求用户提供新邮箱地址与验证码，后端通过验证服务核验Redis中存储的验证码，随后由用户服务层执行数据库更新，确保邮箱唯一性与安全性。文档还解释了请求体结构、验证码生成与存储机制、错误处理策略，并给出成功与失败场景的响应示例，强调该操作需要有效的JWT认证。

## 项目结构
- 路由与鉴权
  - 路由在 v1 组下，用户相关接口均受JWT中间件保护。
  - 邮箱变更接口位于 /api/v1/user/change-email，采用POST方法。
- 控制器层
  - 用户控制器负责接收请求、参数校验、调用服务层、组装响应。
- 服务层
  - 验证服务：生成、发送、校验验证码；验证码以特定键规则存入Redis。
  - 用户服务：执行邮箱唯一性检查与数据库更新。
- 数据访问层
  - 用户仓库封装GORM操作，提供按邮箱查询与字段更新能力。
- 基础设施
  - Redis客户端：提供键值存取、过期控制、删除等操作。
  - 邮件服务：根据类型发送不同主题的验证码邮件。

```mermaid
graph TB
Client["客户端"] --> Routes["路由: /api/v1/user/change-email"]
Routes --> AuthMW["JWT中间件"]
AuthMW --> Handler["用户处理器: ChangeEmail"]
Handler --> VerifySvc["验证服务: VerifyCode"]
Handler --> UserSvc["用户服务: ChangeUserEmail"]
VerifySvc --> Redis["Redis: 验证码存储"]
UserSvc --> Repo["用户仓库: UpdateUserFields"]
Repo --> DB["数据库: user 表"]
VerifySvc --> Email["邮件服务: SendChangeEmail"]
```

图表来源
- [routes.go](file://internal/handler/routes.go#L1-L120)
- [auth.go](file://internal/middleware/auth.go#L1-L79)
- [user_handler.go](file://internal/handler/user_handler.go#L328-L416)
- [verification_service.go](file://internal/service/verification_service.go#L1-L119)
- [user_service.go](file://internal/service/user_service.go#L186-L201)
- [user_repository.go](file://internal/repository/user_repository.go#L65-L69)
- [redis.go](file://pkg/redis/redis.go#L60-L83)
- [email.go](file://pkg/email/email.go#L47-L55)

章节来源
- [routes.go](file://internal/handler/routes.go#L1-L120)
- [auth.go](file://internal/middleware/auth.go#L1-L79)

## 核心组件
- 请求体结构
  - ChangeEmailRequest.new_email：新邮箱地址，必填且符合邮箱格式。
  - ChangeEmailRequest.verification_code：验证码，必填且长度为6。
- 鉴权要求
  - 所有用户相关接口均需携带有效的Bearer JWT。
- 验证码机制
  - 验证码类型常量包含“change_email”，用于区分不同用途。
  - 验证码长度为6，有效期10分钟，发送频率限制1分钟。
  - 验证通过后，Redis中的验证码键会被删除。
- 邮箱唯一性校验
  - 在更新邮箱前，查询数据库确认新邮箱未被其他用户占用；若被占用则拒绝。
- 错误处理
  - 参数错误、未授权、验证码错误、邮箱已被使用、服务器内部错误等均有明确响应码与消息。

章节来源
- [common.go](file://internal/types/common.go#L62-L66)
- [verification_service.go](file://internal/service/verification_service.go#L14-L24)
- [verification_service.go](file://internal/service/verification_service.go#L79-L98)
- [user_service.go](file://internal/service/user_service.go#L186-L201)
- [response.go](file://internal/model/response.go#L27-L53)

## 架构总览
POST /api/v1/user/change-email 的端到端流程如下：
1. 客户端携带JWT向 /api/v1/user/change-email 发起POST请求，请求体包含 new_email 与 verification_code。
2. 路由匹配到用户组，JWT中间件校验通过后进入用户处理器。
3. 处理器解析请求体并调用验证服务，验证Redis中对应类型的验证码是否匹配。
4. 验证通过后，处理器调用用户服务更新数据库中的邮箱字段。
5. 更新完成后，重新查询用户信息并返回成功响应。

```mermaid
sequenceDiagram
participant C as "客户端"
participant R as "路由"
participant M as "JWT中间件"
participant H as "用户处理器"
participant VS as "验证服务"
participant RS as "Redis"
participant US as "用户服务"
participant UR as "用户仓库"
participant DB as "数据库"
C->>R : "POST /api/v1/user/change-email"
R->>M : "鉴权"
M-->>R : "通过"
R->>H : "进入ChangeEmail"
H->>VS : "VerifyCode(email, code, type=change_email)"
VS->>RS : "Get(verification : code : change_email : new_email)"
RS-->>VS : "验证码"
VS-->>H : "验证通过"
H->>US : "ChangeUserEmail(userID, new_email)"
US->>UR : "FindUserByEmail(new_email)"
UR-->>US : "查询结果"
US->>UR : "UpdateUserFields(userID, {email : new_email})"
UR->>DB : "更新"
DB-->>UR : "成功"
UR-->>US : "成功"
US-->>H : "成功"
H-->>C : "返回用户信息"
```

图表来源
- [routes.go](file://internal/handler/routes.go#L27-L41)
- [auth.go](file://internal/middleware/auth.go#L12-L56)
- [user_handler.go](file://internal/handler/user_handler.go#L328-L416)
- [verification_service.go](file://internal/service/verification_service.go#L79-L98)
- [redis.go](file://pkg/redis/redis.go#L60-L83)
- [user_service.go](file://internal/service/user_service.go#L186-L201)
- [user_repository.go](file://internal/repository/user_repository.go#L65-L69)

## 详细组件分析

### 控制器：ChangeEmail 端点
- 功能职责
  - 从上下文提取用户ID（JWT中间件注入）。
  - 解析请求体为 ChangeEmailRequest。
  - 调用验证服务核验验证码（类型为 change_email）。
  - 调用用户服务更新邮箱。
  - 重新查询用户信息并返回成功响应。
- 错误处理
  - 缺少Authorization头或无效token：返回401。
  - 请求体绑定失败：返回400。
  - 验证码错误或过期：返回400。
  - 邮箱已被占用：返回400。
  - 用户不存在：返回404。
  - 其他异常：返回500。

```mermaid
flowchart TD
Start(["进入ChangeEmail"]) --> GetCtx["获取user_id"]
GetCtx --> CheckAuth{"user_id存在?"}
CheckAuth -- 否 --> Resp401["返回401未授权"]
CheckAuth -- 是 --> BindReq["绑定ChangeEmailRequest"]
BindReq --> BindOK{"绑定成功?"}
BindOK -- 否 --> Resp400["返回400参数错误"]
BindOK -- 是 --> Verify["调用VerifyCode(type=change_email)"]
Verify --> VerifyOK{"验证通过?"}
VerifyOK -- 否 --> Resp400V["返回400验证码错误/过期"]
VerifyOK -- 是 --> Update["调用ChangeUserEmail"]
Update --> UpdateOK{"更新成功?"}
UpdateOK -- 否 --> Resp400E["返回400邮箱已被使用/其他错误"]
UpdateOK -- 是 --> Reload["重新查询用户信息"]
Reload --> Resp200["返回200成功"]
```

图表来源
- [user_handler.go](file://internal/handler/user_handler.go#L328-L416)
- [auth.go](file://internal/middleware/auth.go#L12-L56)
- [response.go](file://internal/model/response.go#L27-L53)

章节来源
- [user_handler.go](file://internal/handler/user_handler.go#L328-L416)
- [auth.go](file://internal/middleware/auth.go#L12-L56)
- [response.go](file://internal/model/response.go#L27-L53)

### 验证服务：验证码生成、发送与校验
- 生成与存储
  - 生成6位数字验证码。
  - 以键模式 verification:code:{type}:{email} 写入Redis，有效期10分钟。
  - 发送频率限制键 verification:rate_limit:{type}:{email} 设置1分钟。
- 校验逻辑
  - 读取Redis中的验证码并与请求一致进行比对。
  - 校验通过后删除该验证码键。
- 邮件发送
  - 根据类型选择不同主题与正文，发送更换邮箱验证码邮件。

```mermaid
flowchart TD
Gen["生成6位验证码"] --> Store["写入Redis: code键(10分钟)"]
Store --> Rate["设置rate_limit键(1分钟)"]
Rate --> Mail["发送邮件(ChangeEmail)"]
Mail --> Verify["VerifyCode: 读取code键"]
Verify --> Match{"是否匹配?"}
Match -- 否 --> Err["返回错误(验证码错误/过期)"]
Match -- 是 --> Del["删除code键"]
Del --> Ok["返回成功"]
```

图表来源
- [verification_service.go](file://internal/service/verification_service.go#L26-L77)
- [verification_service.go](file://internal/service/verification_service.go#L79-L98)
- [email.go](file://pkg/email/email.go#L47-L55)
- [redis.go](file://pkg/redis/redis.go#L60-L83)

章节来源
- [verification_service.go](file://internal/service/verification_service.go#L14-L24)
- [verification_service.go](file://internal/service/verification_service.go#L26-L77)
- [verification_service.go](file://internal/service/verification_service.go#L79-L98)
- [email.go](file://pkg/email/email.go#L47-L55)
- [redis.go](file://pkg/redis/redis.go#L60-L83)

### 用户服务：邮箱唯一性与更新
- 唯一性检查
  - 查询新邮箱是否已被其他用户占用；若存在且ID不同则报错。
- 更新逻辑
  - 使用UpdateUserFields更新邮箱字段。

```mermaid
flowchart TD
Check["FindUserByEmail(new_email)"] --> Found{"是否找到用户?"}
Found -- 是且ID!=userID --> Err["返回错误: 邮箱已被使用"]
Found -- 否或ID==userID --> Update["UpdateUserFields(userID, {email: new_email})"]
Update --> Done["返回成功"]
```

图表来源
- [user_service.go](file://internal/service/user_service.go#L186-L201)
- [user_repository.go](file://internal/repository/user_repository.go#L45-L57)
- [user_repository.go](file://internal/repository/user_repository.go#L65-L69)

章节来源
- [user_service.go](file://internal/service/user_service.go#L186-L201)
- [user_repository.go](file://internal/repository/user_repository.go#L45-L57)
- [user_repository.go](file://internal/repository/user_repository.go#L65-L69)

### 数据模型与响应
- 请求体
  - ChangeEmailRequest.new_email：新邮箱地址，必填且符合邮箱格式。
  - ChangeEmailRequest.verification_code：验证码，必填且长度为6。
- 成功响应
  - 返回通用响应结构，包含用户信息（含更新后的邮箱）。
- 错误响应
  - 400：请求参数错误、验证码错误/过期、邮箱已被使用。
  - 401：未授权。
  - 404：用户不存在。
  - 500：服务器内部错误。

章节来源
- [common.go](file://internal/types/common.go#L62-L66)
- [response.go](file://internal/model/response.go#L27-L53)
- [user_handler.go](file://internal/handler/user_handler.go#L328-L416)

## 依赖关系分析
- 控制器依赖
  - 路由与JWT中间件：保证接口受保护。
  - 验证服务：负责验证码核验。
  - 用户服务：负责邮箱更新与唯一性检查。
- 服务层依赖
  - Redis客户端：验证码存取与删除。
  - 邮件服务：发送验证码邮件。
  - 用户仓库：数据库读写。
- 数据库约束
  - 用户表的邮箱字段具备唯一索引，配合服务层检查可避免并发冲突。

```mermaid
graph LR
Handler["用户处理器"] --> VerifySvc["验证服务"]
Handler --> UserSvc["用户服务"]
VerifySvc --> Redis["Redis客户端"]
VerifySvc --> Email["邮件服务"]
UserSvc --> Repo["用户仓库"]
Repo --> DB["数据库"]
```

图表来源
- [user_handler.go](file://internal/handler/user_handler.go#L328-L416)
- [verification_service.go](file://internal/service/verification_service.go#L79-L98)
- [user_service.go](file://internal/service/user_service.go#L186-L201)
- [user_repository.go](file://internal/repository/user_repository.go#L65-L69)
- [redis.go](file://pkg/redis/redis.go#L60-L83)
- [email.go](file://pkg/email/email.go#L47-L55)

章节来源
- [user_handler.go](file://internal/handler/user_handler.go#L328-L416)
- [verification_service.go](file://internal/service/verification_service.go#L79-L98)
- [user_service.go](file://internal/service/user_service.go#L186-L201)
- [user_repository.go](file://internal/repository/user_repository.go#L65-L69)
- [redis.go](file://pkg/redis/redis.go#L60-L83)
- [email.go](file://pkg/email/email.go#L47-L55)

## 性能与可靠性
- 验证码缓存
  - Redis键过期时间10分钟，避免长期占用内存；rate_limit键1分钟，限制发送频率，降低滥用风险。
- 并发一致性
  - 服务层在更新前进行邮箱唯一性检查，结合数据库唯一索引，有效防止并发写入导致的重复。
- 日志与可观测性
  - 处理器与服务层在关键路径记录日志，便于定位问题。
- 错误传播
  - 明确的错误码与消息，便于前端统一处理。

[本节为通用指导，不直接分析具体文件]

## 故障排查指南
- 401 未授权
  - 检查请求头 Authorization 是否为 Bearer 令牌，且令牌有效。
- 400 请求参数错误
  - 确认请求体包含 new_email 与 verification_code，且格式正确。
- 400 验证码错误/过期
  - 检查Redis中 verification:code:change_email:{email} 是否存在且未过期；确认邮件是否送达。
- 400 邮箱已被使用
  - 确认新邮箱未被其他用户占用；若被占用请更换邮箱。
- 404 用户不存在
  - 检查用户是否被软删除或账户状态异常。
- 500 服务器内部错误
  - 查看服务日志，关注数据库更新与Redis存取异常。

章节来源
- [user_handler.go](file://internal/handler/user_handler.go#L328-L416)
- [verification_service.go](file://internal/service/verification_service.go#L79-L98)
- [user_service.go](file://internal/service/user_service.go#L186-L201)
- [redis.go](file://pkg/redis/redis.go#L60-L83)
- [response.go](file://internal/model/response.go#L27-L53)

## 结论
POST /api/v1/user/change-email 通过严格的JWT鉴权、Redis验证码校验与数据库唯一性检查，实现了安全可靠的邮箱变更流程。请求体简洁明确，错误处理清晰，适合在生产环境中稳定运行。建议在部署时确保Redis与邮件服务可用，并合理配置验证码有效期与发送频率限制，以兼顾用户体验与安全。