chore(git): 更新.gitignore以忽略新的本地文件

.qoder/repowiki/zh/content/外部集成/Redis缓存集成.md

@@ -0,0 +1,220 @@
+# Redis缓存集成
+
+<cite>
+**本文档引用的文件**   
+- [redis.go](file://pkg/redis/redis.go)
+- [manager.go](file://pkg/redis/manager.go)
+- [config.go](file://pkg/config/config.go)
+- [jwt.go](file://pkg/auth/jwt.go)
+- [captcha_service.go](file://internal/service/captcha_service.go)
+- [verification_service.go](file://internal/service/verification_service.go)
+</cite>
+
+## 目录
+1. [项目结构](#项目结构)
+2. [Redis客户端封装设计](#redis客户端封装设计)
+3. [连接池与健康检查机制](#连接池与健康检查机制)
+4. [缓存操作实现原理](#缓存操作实现原理)
+5. [JWT令牌存储应用](#jwt令牌存储应用)
+6. [会话管理与验证码应用](#会话管理与验证码应用)
+7. [限流控制实现](#限流控制实现)
+8. [缓存问题预防策略](#缓存问题预防策略)
+9. [高可用架构支持](#高可用架构支持)
+
+## 项目结构
+
+```mermaid
+graph TB
+subgraph "pkg"
+Redis[redis]
+Config[config]
+Auth[auth]
+end
+subgraph "internal"
+Service[service]
+Repository[repository]
+end
+Redis --> Service
+Config --> Redis
+Auth --> Service
+Service --> Repository
+```
+
+**图示来源**
+- [redis.go](file://pkg/redis/redis.go#L1-L175)
+- [config.go](file://pkg/config/config.go#L1-L305)
+- [captcha_service.go](file://internal/service/captcha_service.go#L1-L166)
+
+## Redis客户端封装设计
+
+CarrotSkin项目中的Redis客户端封装采用分层设计模式，通过`Client`结构体对`github.com/redis/go-redis/v9`库进行包装，提供更简洁的API接口。`Client`结构体包含`*redis.Client`指针和`*zap.Logger`日志记录器，实现了日志记录和错误处理的统一管理。
+
+封装设计遵循单一职责原则，将Redis连接管理、操作执行和日志记录分离。通过`New`函数创建客户端实例时，会根据配置参数初始化连接，并执行连接测试，确保连接的可用性。这种设计模式提高了代码的可维护性和可测试性。
+
+**本节来源**
+- [redis.go](file://pkg/redis/redis.go#L15-L52)
+- [manager.go](file://pkg/redis/manager.go#L11-L18)
+
+## 连接池与健康检查机制
+
+Redis连接池配置在`RedisConfig`结构体中定义，包含`Host`、`Port`、`Password`、`Database`和`PoolSize`等关键参数。连接池大小通过`PoolSize`字段配置，默认值为10，可根据实际负载情况进行调整。
+
+健康检查机制在客户端初始化时实现，通过`Ping`命令测试连接可用性。使用`context.WithTimeout`设置5秒超时，防止连接测试阻塞主线程。连接成功后会记录包含主机、端口和数据库信息的日志，便于监控和故障排查。
+
+```mermaid
+sequenceDiagram
+participant App as 应用程序
+participant Manager as Redis管理器
+participant Client as Redis客户端
+participant Redis as Redis服务器
+App->>Manager : Init(cfg, logger)
+Manager->>Client : New(cfg, logger)
+Client->>Redis : Ping()
+Redis-->>Client : PONG
+Client-->>Manager : 返回客户端实例
+Manager-->>App : 初始化完成
+```
+
+**图示来源**
+- [redis.go](file://pkg/redis/redis.go#L22-L47)
+- [config.go](file://pkg/config/config.go#L49-L56)
+
+**本节来源**
+- [redis.go](file://pkg/redis/redis.go#L22-L47)
+- [config.go](file://pkg/config/config.go#L49-L56)
+
+## 缓存操作实现原理
+
+缓存操作通过`Client`结构体的方法实现，包括`Set`、`Get`、`Del`、`Exists`、`Expire`等基本操作。这些方法直接代理到底层`redis.Client`的对应方法，保持了与原生API的一致性。
+
+`Set`方法接受`context.Context`、键、值和过期时间参数，支持设置键值对及其过期时间。`Get`方法返回字符串值和错误，通过`Nil`方法可以判断键不存在的情况。`Expire`方法用于修改现有键的过期时间，支持动态调整缓存策略。
+
+```mermaid
+classDiagram
+class Client {
++*redis.Client
++*zap.Logger
++Set(ctx, key, value, expiration) error
++Get(ctx, key) (string, error)
++Del(ctx, keys) error
++Exists(ctx, keys) (int64, error)
++Expire(ctx, key, expiration) error
++Nil(err) bool
+}
+class RedisConfig {
++Host string
++Port int
++Password string
++Database int
++PoolSize int
+}
+Client --> RedisConfig : 使用
+```
+
+**图示来源**
+- [redis.go](file://pkg/redis/redis.go#L60-L83)
+- [config.go](file://pkg/config/config.go#L49-L56)
+
+**本节来源**
+- [redis.go](file://pkg/redis/redis.go#L60-L83)
+
+## JWT令牌存储应用
+
+JWT令牌存储利用Redis作为临时存储介质，通过`Set`方法将令牌与用户信息关联存储。令牌的过期时间与JWT的有效期保持一致，确保令牌在Redis中的生命周期与JWT一致。
+
+在`jwt.go`中，JWT服务生成令牌后，可以通过Redis存储令牌的元数据，如用户ID、角色等信息。这种设计实现了无状态认证与有状态缓存的结合，既保持了JWT的无状态特性，又可以通过Redis快速验证令牌的有效性。
+
+```mermaid
+sequenceDiagram
+participant User as 用户
+participant Auth as 认证服务
+participant Redis as Redis缓存
+User->>Auth : 登录请求
+Auth->>Auth : 生成JWT令牌
+Auth->>Redis : Set(token, userInfo, expireTime)
+Redis-->>Auth : 存储成功
+Auth-->>User : 返回JWT令牌
+User->>Auth : 带JWT的请求
+Auth->>Redis : Get(token)
+Redis-->>Auth : 返回用户信息
+Auth-->>User : 处理请求
+```
+
+**图示来源**
+- [jwt.go](file://pkg/auth/jwt.go#L32-L52)
+- [redis.go](file://pkg/redis/redis.go#L60-L63)
+
+**本节来源**
+- [jwt.go](file://pkg/auth/jwt.go#L32-L52)
+- [redis.go](file://pkg/redis/redis.go#L60-L63)
+
+## 会话管理与验证码应用
+
+会话管理通过Redis存储会话数据，每个会话以唯一ID作为键，会话数据作为值进行存储。验证码应用在`captcha_service.go`中实现，使用`redisKeyPrefix = "captcha:"`作为键前缀，确保验证码数据的隔离性。
+
+验证码生成时，将滑块的目标坐标等验证信息序列化后存储到Redis，设置300秒过期时间。验证时从Redis获取原始数据，与用户输入进行比对，验证成功后立即删除Redis记录，防止重复使用。
+
+```mermaid
+flowchart TD
+Start([生成验证码]) --> Generate["生成滑块坐标(Tx,Ty)"]
+Generate --> Serialize["序列化为JSON"]
+Serialize --> Store["Set(captcha:id, json, 300s)"]
+Store --> Return["返回验证码数据"]
+Verify([验证验证码]) --> Get["Get(captcha:id)"]
+Get --> Check{"是否存在?"}
+Check --> |否| Expired["返回: 验证码已过期"]
+Check --> |是| Parse["解析JSON数据"]
+Parse --> Validate["验证用户输入"]
+Validate --> Delete["Del(captcha:id)"]
+Delete --> Result["返回验证结果"]
+```
+
+**图示来源**
+- [captcha_service.go](file://internal/service/captcha_service.go#L75-L135)
+- [redis.go](file://pkg/redis/redis.go#L60-L63)
+
+**本节来源**
+- [captcha_service.go](file://internal/service/captcha_service.go#L75-L135)
+- [redis.go](file://pkg/redis/redis.go#L144-L146)
+
+## 限流控制实现
+
+限流控制在`verification_service.go`中实现，通过Redis的`Set`命令设置频率限制。使用`codeType`和`email`组合生成限流键，值设为"1"，过期时间由`CodeRateLimit`常量定义。
+
+当用户请求发送验证码时，先检查限流键是否存在，若存在则拒绝请求，防止频繁发送。这种基于Redis的限流机制简单高效，能够有效防止恶意刷屏攻击，保护系统资源。
+
+```mermaid
+flowchart LR
+Request[发送验证码请求] --> Check["Exists(verification:rate:email)"]
+Check --> |存在| Reject[拒绝请求]
+Check --> |不存在| Send[发送验证码]
+Send --> Set["Set(verification:rate:email, 1, 60s)"]
+Set --> Response[返回响应]
+```
+
+**图示来源**
+- [verification_service.go](file://internal/service/verification_service.go#L58-L67)
+- [redis.go](file://pkg/redis/redis.go#L75-L78)
+
+**本节来源**
+- [verification_service.go](file://internal/service/verification_service.go#L58-L67)
+
+## 缓存问题预防策略
+
+针对缓存穿透、雪崩、击穿问题，CarrotSkin采用多种预防策略。对于缓存穿透，使用`Nil`方法识别空值情况，避免频繁查询数据库。对于缓存雪崩，建议在配置中设置随机的过期时间偏移，避免大量缓存同时失效。
+
+缓存击穿问题通过互斥锁或逻辑过期策略解决。当热点数据失效时，只允许一个请求加载数据，其他请求等待并使用旧数据，直到新数据加载完成。这种策略既保证了数据的一致性，又避免了数据库的瞬时压力。
+
+**本节来源**
+- [redis.go](file://pkg/redis/redis.go#L160-L162)
+- [captcha_service.go](file://internal/service/captcha_service.go#L144-L145)
+
+## 高可用架构支持
+
+Redis高可用架构支持通过配置文件中的连接参数实现。虽然当前代码主要针对单机模式，但`github.com/redis/go-redis/v9`库原生支持哨兵模式和集群模式。通过修改配置，可以无缝切换到高可用架构。
+
+连接故障恢复机制内置于客户端库中，自动处理网络抖动和临时故障。建议在生产环境中配置合理的超时时间和重试策略，确保系统的稳定性和可靠性。监控连接状态和性能指标，及时发现和解决潜在问题。
+
+**本节来源**
+- [redis.go](file://pkg/redis/redis.go#L24-L32)
+- [config.go](file://pkg/config/config.go#L49-L56)

.qoder/repowiki/zh/content/外部集成/外部集成.md

@@ -0,0 +1,314 @@
+# 外部集成
+
+<cite>
+**本文档引用的文件**
+- [email.go](file://pkg/email/email.go)
+- [manager.go](file://pkg/email/manager.go)
+- [minio.go](file://pkg/storage/minio.go)
+- [storage_manager.go](file://pkg/storage/manager.go)
+- [redis.go](file://pkg/redis/redis.go)
+- [redis_manager.go](file://pkg/redis/manager.go)
+- [config.go](file://pkg/config/config.go)
+- [manager.go](file://pkg/config/manager.go)
+- [verification_service.go](file://internal/service/verification_service.go)
+- [upload_service.go](file://internal/service/upload_service.go)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [邮件服务集成](#邮件服务集成)
+3. [对象存储集成](#对象存储集成)
+4. [缓存系统集成](#缓存系统集成)
+5. [集成初始化流程](#集成初始化流程)
+6. [故障排除与性能调优](#故障排除与性能调优)
+7. [总结](#总结)
+
+## 简介
+CarrotSkin项目通过集成第三方服务来实现关键功能，包括邮件服务（SMTP）、对象存储（MinIO/RustFS）和缓存系统（Redis）。这些集成分别用于发送验证邮件、存储用户上传的皮肤文件以及缓存会话数据和验证码。本文档详细说明这些外部服务的配置、初始化和使用方式，为初学者提供配置示例，同时为经验丰富的开发者提供故障排除和性能调优的高级技巧。
+
+## 邮件服务集成
+
+邮件服务用于向用户发送验证码邮件，包括注册验证、密码重置和更换邮箱等场景。该服务通过SMTP协议与邮件服务器通信，支持SSL/TLS加密。
+
+### 配置与初始化
+邮件服务的配置通过环境变量进行管理，主要配置项包括SMTP主机、端口、用户名、密码和发件人名称。服务采用单例模式初始化，确保线程安全。
+
+```mermaid
+classDiagram
+class EmailConfig {
++bool Enabled
++string SMTPHost
++int SMTPPort
++string Username
++string Password
++string FromName
+}
+class Service {
+-EmailConfig cfg
+-*zap.Logger logger
++SendVerificationCode(to, code, purpose) error
++SendResetPassword(to, code) error
++SendEmailVerification(to, code) error
++SendChangeEmail(to, code) error
+}
+class Manager {
++Init(cfg EmailConfig, logger *zap.Logger) error
++GetService() (*Service, error)
++MustGetService() *Service
+}
+EmailConfig --> Service : "配置"
+Service --> Manager : "实现"
+```
+
+**Diagram sources**
+- [config.go](file://pkg/config/config.go#L98-L106)
+- [email.go](file://pkg/email/email.go#L16-L19)
+- [manager.go](file://pkg/email/manager.go#L11-L18)
+
+**Section sources**
+- [config.go](file://pkg/config/config.go#L98-L106)
+- [email.go](file://pkg/email/email.go#L16-L19)
+- [manager.go](file://pkg/email/manager.go#L11-L18)
+
+### 使用方式
+邮件服务提供了多种发送验证码的方法，根据不同的业务场景调用相应的函数。例如，`SendEmailVerification`用于发送邮箱验证邮件，`SendResetPassword`用于发送密码重置邮件。
+
+```mermaid
+sequenceDiagram
+participant Handler as "Handler"
+participant Service as "VerificationService"
+participant EmailService as "EmailService"
+Handler->>Service : SendVerificationCode()
+Service->>Service : GenerateVerificationCode()
+Service->>Service : 存储验证码到Redis
+Service->>EmailService : SendEmailVerification()
+EmailService->>EmailService : 构建邮件内容
+EmailService->>SMTP : 发送邮件
+SMTP-->>EmailService : 发送结果
+EmailService-->>Service : 发送结果
+Service-->>Handler : 结果
+```
+
+**Diagram sources**
+- [verification_service.go](file://internal/service/verification_service.go#L40-L76)
+- [email.go](file://pkg/email/email.go#L29-L55)
+
+**Section sources**
+- [verification_service.go](file://internal/service/verification_service.go#L40-L76)
+- [email.go](file://pkg/email/email.go#L29-L55)
+
+## 对象存储集成
+
+对象存储服务用于存储用户上传的皮肤文件和头像，支持S3兼容的存储系统，如MinIO和RustFS。该服务提供预签名URL功能，允许客户端直接上传文件到存储服务器。
+
+### 配置与初始化
+对象存储的配置包括端点地址、访问密钥、密钥和是否使用SSL。存储桶名称通过环境变量配置，支持多个存储桶。服务同样采用单例模式初始化。
+
+```mermaid
+classDiagram
+class RustFSConfig {
++string Endpoint
++string AccessKey
++string SecretKey
++bool UseSSL
++map[string]string Buckets
+}
+class StorageClient {
+-*minio.Client client
+-map[string]string buckets
++GetBucket(name) (string, error)
++GeneratePresignedURL(ctx, bucket, object, expires) (string, error)
++GeneratePresignedPostURL(ctx, bucket, object, minSize, maxSize, expires, useSSL, endpoint) (*PresignedPostPolicyResult, error)
+}
+class Manager {
++Init(cfg RustFSConfig) error
++GetClient() (*StorageClient, error)
++MustGetClient() *StorageClient
+}
+RustFSConfig --> StorageClient : "配置"
+StorageClient --> Manager : "实现"
+```
+
+**Diagram sources**
+- [config.go](file://pkg/config/config.go#L58-L64)
+- [minio.go](file://pkg/storage/minio.go#L15-L18)
+- [manager.go](file://pkg/storage/manager.go#L9-L16)
+
+**Section sources**
+- [config.go](file://pkg/config/config.go#L58-L64)
+- [minio.go](file://pkg/storage/minio.go#L15-L18)
+- [manager.go](file://pkg/storage/manager.go#L9-L16)
+
+### 使用方式
+对象存储服务通过生成预签名URL来实现文件上传。客户端获取URL后，可以直接上传文件，无需经过应用服务器。这提高了上传效率并减少了服务器负载。
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant Handler as "Handler"
+participant Service as "UploadService"
+participant Storage as "StorageClient"
+Client->>Handler : 请求上传URL
+Handler->>Service : GenerateAvatarUploadURL()
+Service->>Storage : GeneratePresignedPostURL()
+Storage-->>Service : 预签名URL和表单数据
+Service-->>Handler : 上传配置
+Handler-->>Client : 上传配置
+Client->>Storage : 使用预签名URL上传文件
+Storage-->>Client : 上传结果
+```
+
+**Diagram sources**
+- [upload_service.go](file://internal/service/upload_service.go#L78-L115)
+- [minio.go](file://pkg/storage/minio.go#L82-L120)
+
+**Section sources**
+- [upload_service.go](file://internal/service/upload_service.go#L78-L115)
+- [minio.go](file://pkg/storage/minio.go#L82-L120)
+
+## 缓存系统集成
+
+缓存系统使用Redis来存储临时数据，如验证码、会话信息和频率限制。Redis提供了高性能的键值存储，支持多种数据结构。
+
+### 配置与初始化
+Redis的配置包括主机地址、端口、密码、数据库编号和连接池大小。服务采用单例模式初始化，确保线程安全。
+
+```mermaid
+classDiagram
+class RedisConfig {
++string Host
++int Port
++string Password
++int Database
++int PoolSize
+}
+class Client {
+-*redis.Client Client
+-*zap.Logger logger
++Set(ctx, key, value, expiration) error
++Get(ctx, key) (string, error)
++Del(ctx, keys) error
++Exists(ctx, keys) (int64, error)
++Expire(ctx, key, expiration) error
++Incr(ctx, key) (int64, error)
++Decr(ctx, key) (int64, error)
++HSet(ctx, key, values) error
++HGet(ctx, key, field) (string, error)
++HGetAll(ctx, key) (map[string]string, error)
++HDel(ctx, key, fields) error
++SAdd(ctx, key, members) error
++SMembers(ctx, key) ([]string, error)
++SRem(ctx, key, members) error
++SIsMember(ctx, key, member) (bool, error)
++ZAdd(ctx, key, members) error
++ZRange(ctx, key, start, stop) ([]string, error)
++ZRem(ctx, key, members) error
++Pipeline() redis.Pipeliner
++TxPipeline() redis.Pipeliner
++Nil(err) bool
++GetBytes(ctx, key) ([]byte, error)
+}
+class Manager {
++Init(cfg RedisConfig, logger *zap.Logger) error
++GetClient() (*Client, error)
++MustGetClient() *Client
+}
+RedisConfig --> Client : "配置"
+Client --> Manager : "实现"
+```
+
+**Diagram sources**
+- [config.go](file://pkg/config/config.go#L49-L56)
+- [redis.go](file://pkg/redis/redis.go#L16-L19)
+- [manager.go](file://pkg/redis/manager.go#L11-L18)
+
+**Section sources**
+- [config.go](file://pkg/config/config.go#L49-L56)
+- [redis.go](file://pkg/redis/redis.go#L16-L19)
+- [manager.go](file://pkg/redis/manager.go#L11-L18)
+
+### 使用方式
+缓存系统主要用于存储验证码和频率限制。当用户请求发送验证码时，系统会先检查频率限制，然后生成验证码并存储到Redis中，最后发送邮件。
+
+```mermaid
+sequenceDiagram
+participant Handler as "Handler"
+participant Service as "VerificationService"
+participant Redis as "RedisClient"
+Handler->>Service : SendVerificationCode()
+Service->>Redis : Exists(verification : rate_limit : *)
+Redis-->>Service : 结果
+alt 频率限制未超
+Service->>Service : GenerateVerificationCode()
+Service->>Redis : Set(verification : code : *, code, expiration)
+Service->>Redis : Set(verification : rate_limit : *, 1, rateLimit)
+Service->>EmailService : SendEmailVerification()
+EmailService-->>Service : 发送结果
+Service-->>Handler : 结果
+else 频率限制已超
+Service-->>Handler : 错误
+end
+```
+
+**Diagram sources**
+- [verification_service.go](file://internal/service/verification_service.go#L40-L76)
+- [redis.go](file://pkg/redis/redis.go#L60-L67)
+
+**Section sources**
+- [verification_service.go](file://internal/service/verification_service.go#L40-L76)
+- [redis.go](file://pkg/redis/redis.go#L60-L67)
+
+## 集成初始化流程
+
+所有外部集成服务的初始化都在应用启动时完成，通过配置管理器加载配置并初始化各个服务。初始化流程确保了服务的线程安全和单例模式。
+
+```mermaid
+flowchart TD
+Start([应用启动]) --> LoadConfig["加载配置 (config.Load)"]
+LoadConfig --> InitEmail["初始化邮件服务 (email.Init)"]
+LoadConfig --> InitStorage["初始化存储服务 (storage.Init)"]
+LoadConfig --> InitRedis["初始化Redis服务 (redis.Init)"]
+InitEmail --> CheckEmail["检查邮件服务是否启用"]
+InitStorage --> TestStorage["测试存储连接"]
+InitRedis --> TestRedis["测试Redis连接"]
+CheckEmail --> End1([邮件服务就绪])
+TestStorage --> End2([存储服务就绪])
+TestRedis --> End3([Redis服务就绪])
+```
+
+**Diagram sources**
+- [config.go](file://pkg/config/config.go#L109-L133)
+- [manager.go](file://pkg/email/manager.go#L20-L26)
+- [manager.go](file://pkg/storage/manager.go#L19-L26)
+- [manager.go](file://pkg/redis/manager.go#L21-L28)
+
+**Section sources**
+- [config.go](file://pkg/config/config.go#L109-L133)
+- [manager.go](file://pkg/email/manager.go#L20-L26)
+- [manager.go](file://pkg/storage/manager.go#L19-L26)
+- [manager.go](file://pkg/redis/manager.go#L21-L28)
+
+## 故障排除与性能调优
+
+### 邮件服务
+- **常见问题**：SMTP连接失败、认证失败、邮件发送超时。
+- **解决方案**：检查SMTP主机和端口配置，确保SSL/TLS设置正确，验证用户名和密码。
+- **性能调优**：使用连接池减少连接开销，批量发送邮件以减少网络延迟。
+
+### 对象存储
+- **常见问题**：预签名URL无效、上传失败、存储桶不存在。
+- **解决方案**：检查存储桶名称和权限，确保预签名URL的过期时间合理，验证访问密钥和密钥。
+- **性能调优**：使用分块上传大文件，启用CDN加速文件访问。
+
+### 缓存系统
+- **常见问题**：Redis连接失败、内存不足、键过期。
+- **解决方案**：检查Redis主机和端口配置，优化键的过期时间，监控内存使用情况。
+- **性能调优**：使用管道减少网络往返，合理设置连接池大小，定期清理过期键。
+
+**Section sources**
+- [email.go](file://pkg/email/email.go#L66-L86)
+- [minio.go](file://pkg/storage/minio.go#L33-L42)
+- [redis.go](file://pkg/redis/redis.go#L34-L40)
+
+## 总结
+CarrotSkin项目通过集成邮件服务、对象存储和缓存系统，实现了高效、可靠的用户验证和文件存储功能。这些集成通过统一的配置管理和初始化流程，确保了服务的稳定性和可维护性。开发者可以根据本文档的指导，轻松配置和使用这些外部服务，并通过故障排除和性能调优技巧，进一步提升系统的性能和可靠性。

.qoder/repowiki/zh/content/外部集成/对象存储集成.md

@@ -0,0 +1,345 @@
+# 对象存储集成
+
+<cite>
+**本文引用的文件**
+- [minio.go](file://pkg/storage/minio.go)
+- [manager.go](file://pkg/storage/manager.go)
+- [config.go](file://pkg/config/config.go)
+- [upload_service.go](file://internal/service/upload_service.go)
+- [texture_handler.go](file://internal/handler/texture_handler.go)
+- [texture_service.go](file://internal/service/texture_service.go)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件面向CarrotSkin后端的对象存储集成，聚焦于如何通过MinIO客户端与S3兼容存储系统交互。文档围绕以下目标展开：
+- 解析minio.go中初始化客户端的流程，包括访问密钥、端点配置和TLS设置
+- 说明manager.go中Upload、Download、GeneratePresignedURL等关键方法的实现细节与调用方式
+- 提供皮肤/披风文件上传、私有资源临时链接生成等典型用例的代码示例路径
+- 解释分片上传、断点续传等高级功能的支持情况
+- 为运维人员提供性能调优建议（并发控制、连接复用）和故障排查指南（签名错误、网络超时）
+
+## 项目结构
+对象存储相关代码集中在pkg/storage目录，配置在pkg/config，业务侧在internal/service与internal/handler中调用。
+
+```mermaid
+graph TB
+subgraph "配置层"
+CFG["pkg/config/config.go<br/>RustFSConfig"]
+end
+subgraph "存储客户端"
+MINIO["pkg/storage/minio.go<br/>StorageClient<br/>NewStorage/GeneratePresignedURL/GeneratePresignedPostURL"]
+MGR["pkg/storage/manager.go<br/>Init/GetClient/MustGetClient"]
+end
+subgraph "业务服务"
+SVC_UPLOAD["internal/service/upload_service.go<br/>GenerateAvatarUploadURL/GenerateTextureUploadURL"]
+SVC_TEX["internal/service/texture_service.go<br/>CreateTexture/RecordTextureDownload 等"]
+end
+subgraph "接口层"
+HANDLER_TEX["internal/handler/texture_handler.go<br/>GenerateTextureUploadURL 接口"]
+end
+CFG --> MINIO
+MINIO --> MGR
+MGR --> HANDLER_TEX
+HANDLER_TEX --> SVC_UPLOAD
+SVC_UPLOAD --> MINIO
+SVC_TEX --> MINIO
+```
+
+图表来源
+- [minio.go](file://pkg/storage/minio.go#L1-L120)
+- [manager.go](file://pkg/storage/manager.go#L1-L49)
+- [config.go](file://pkg/config/config.go#L58-L66)
+- [upload_service.go](file://internal/service/upload_service.go#L78-L160)
+- [texture_handler.go](file://internal/handler/texture_handler.go#L18-L83)
+- [texture_service.go](file://internal/service/texture_service.go#L12-L64)
+
+章节来源
+- [minio.go](file://pkg/storage/minio.go#L1-L120)
+- [manager.go](file://pkg/storage/manager.go#L1-L49)
+- [config.go](file://pkg/config/config.go#L58-L66)
+- [upload_service.go](file://internal/service/upload_service.go#L78-L160)
+- [texture_handler.go](file://internal/handler/texture_handler.go#L18-L83)
+- [texture_service.go](file://internal/service/texture_service.go#L12-L64)
+
+## 核心组件
+- StorageClient：封装minio-go客户端，提供桶名解析、预签名URL生成等能力
+- manager：提供全局单例的存储客户端初始化与获取
+- RustFSConfig：承载S3兼容存储的端点、凭据与桶映射
+- upload_service：面向业务的上传URL生成工具，按头像与材质类型分别组织对象路径
+- texture_handler：对外暴露生成上传URL的HTTP接口
+- texture_service：材质实体的增删改查与下载计数等业务逻辑
+
+章节来源
+- [minio.go](file://pkg/storage/minio.go#L14-L120)
+- [manager.go](file://pkg/storage/manager.go#L9-L44)
+- [config.go](file://pkg/config/config.go#L58-L66)
+- [upload_service.go](file://internal/service/upload_service.go#L13-L57)
+- [texture_handler.go](file://internal/handler/texture_handler.go#L18-L83)
+- [texture_service.go](file://internal/service/texture_service.go#L12-L64)
+
+## 架构总览
+下图展示从接口到存储的调用链路与职责划分。
+
+```mermaid
+sequenceDiagram
+participant C as "客户端"
+participant H as "TextureHandler"
+participant S as "UploadService"
+participant M as "StorageManager"
+participant SC as "StorageClient"
+participant O as "对象存储(兼容S3)"
+C->>H : "POST /api/v1/texture/upload-url"
+H->>M : "MustGetClient()"
+M-->>H : "*StorageClient"
+H->>S : "GenerateTextureUploadURL(ctx, client, cfg, userID, fileName, type)"
+S->>SC : "GetBucket(\"textures\")"
+S->>SC : "GeneratePresignedPostURL(bucket, objectName, limits, expires, useSSL, endpoint)"
+SC->>O : "PresignedPostPolicy(policy)"
+O-->>SC : "postURL + formData"
+SC-->>S : "PresignedPostPolicyResult"
+S-->>H : "PresignedPostPolicyResult"
+H-->>C : "返回postURL、formData、文件最终URL、过期秒数"
+```
+
+图表来源
+- [texture_handler.go](file://internal/handler/texture_handler.go#L18-L83)
+- [upload_service.go](file://internal/service/upload_service.go#L117-L160)
+- [manager.go](file://pkg/storage/manager.go#L30-L44)
+- [minio.go](file://pkg/storage/minio.go#L57-L120)
+
+## 详细组件分析
+
+### StorageClient与初始化流程（minio.go）
+- 客户端初始化
+  - 通过端点、凭据与TLS标志创建minio-go客户端
+  - 若提供了访问密钥与密钥，则进行连接测试（带超时）
+  - 绑定桶映射，便于按“类型”解析真实桶名
+- 关键方法
+  - GetClient：返回底层minio.Client
+  - GetBucket：按名称解析桶名，不存在时报错
+  - GeneratePresignedURL：生成预签名PUT URL（支持上传）
+  - GeneratePresignedPostURL：生成预签名POST策略URL（支持表单直传），并构造最终访问URL
+
+```mermaid
+classDiagram
+class StorageClient {
+-client : "minio.Client"
+-buckets : "map[string]string"
++GetClient() "*minio.Client"
++GetBucket(name) "(string, error)"
++GeneratePresignedURL(ctx, bucketName, objectName, expires) "(string, error)"
++GeneratePresignedPostURL(ctx, bucketName, objectName, minSize, maxSize, expires, useSSL, endpoint) "(*PresignedPostPolicyResult, error)"
+}
+class PresignedPostPolicyResult {
++PostURL : "string"
++FormData : "map[string]string"
++FileURL : "string"
+}
+StorageClient --> PresignedPostPolicyResult : "返回"
+```
+
+图表来源
+- [minio.go](file://pkg/storage/minio.go#L14-L120)
+
+章节来源
+- [minio.go](file://pkg/storage/minio.go#L20-L49)
+- [minio.go](file://pkg/storage/minio.go#L52-L64)
+- [minio.go](file://pkg/storage/minio.go#L66-L73)
+- [minio.go](file://pkg/storage/minio.go#L82-L120)
+
+### 存储客户端管理器（manager.go）
+- Init(cfg)：线程安全初始化，仅执行一次
+- GetClient()：获取全局实例，未初始化时报错
+- MustGetClient()：获取全局实例，未初始化时panic
+
+```mermaid
+flowchart TD
+Start(["调用 Init(cfg)"]) --> Once["sync.Once 保证只执行一次"]
+Once --> NewStorage["NewStorage(cfg) 创建 StorageClient"]
+NewStorage --> Bind["绑定 clientInstance"]
+Bind --> Done(["初始化完成"])
+GetClient["GetClient()"] --> Check{"clientInstance 是否存在？"}
+Check --> |否| Err["返回错误：未初始化"]
+Check --> |是| Return["返回 clientInstance"]
+MustGetClient["MustGetClient()"] --> GetClient
+GetClient --> Panic{"err 是否非空？"}
+Panic --> |是| PanicCall["panic(err)"]
+Panic --> |否| Return
+```
+
+图表来源
+- [manager.go](file://pkg/storage/manager.go#L9-L44)
+
+章节来源
+- [manager.go](file://pkg/storage/manager.go#L18-L27)
+- [manager.go](file://pkg/storage/manager.go#L29-L35)
+- [manager.go](file://pkg/storage/manager.go#L37-L44)
+
+### 配置结构（config.go）
+- RustFSConfig包含端点、访问密钥、密钥、TLS开关与桶映射
+- 环境变量映射与默认值设置，支持通过环境变量覆盖
+
+章节来源
+- [config.go](file://pkg/config/config.go#L58-L66)
+- [config.go](file://pkg/config/config.go#L190-L236)
+- [config.go](file://pkg/config/config.go#L238-L305)
+
+### 上传服务与典型用例（upload_service.go）
+- 文件类型与上传配置
+  - FileTypeAvatar/FileTypeTexture两类
+  - 各自的允许扩展名、最小/最大尺寸、过期时间
+- 生成上传URL
+  - GenerateAvatarUploadURL：按用户ID与时间戳生成对象路径，调用StorageClient.GeneratePresignedPostURL
+  - GenerateTextureUploadURL：支持SKIN/CAPE两种材质类型，生成对应路径，调用StorageClient.GeneratePresignedPostURL
+- 下载与公开资源
+  - 当前代码未直接暴露Download方法；公开资源可通过最终访问URL直接访问
+  - 私有资源可通过GeneratePresignedURL生成临时下载链接
+
+```mermaid
+sequenceDiagram
+participant Svc as "UploadService"
+participant SC as "StorageClient"
+participant O as "对象存储"
+Svc->>Svc : "ValidateFileName(fileName, type)"
+Svc->>SC : "GetBucket(\"avatars\" 或 \"textures\")"
+Svc->>SC : "GeneratePresignedPostURL(bucket, objectName, minSize, maxSize, expires, useSSL, endpoint)"
+SC->>O : "PresignedPostPolicy(policy)"
+O-->>SC : "postURL + formData"
+SC-->>Svc : "PresignedPostPolicyResult"
+Svc-->>Svc : "返回结果"
+```
+
+图表来源
+- [upload_service.go](file://internal/service/upload_service.go#L78-L160)
+- [minio.go](file://pkg/storage/minio.go#L82-L120)
+
+章节来源
+- [upload_service.go](file://internal/service/upload_service.go#L13-L57)
+- [upload_service.go](file://internal/service/upload_service.go#L78-L115)
+- [upload_service.go](file://internal/service/upload_service.go#L117-L160)
+
+### 接口层调用（texture_handler.go）
+- GenerateTextureUploadURL接口：接收请求体，调用UploadService生成预签名POST URL，返回postURL、formData与最终文件URL
+- CreateTexture接口：文件上传完成后，创建材质记录到数据库
+
+章节来源
+- [texture_handler.go](file://internal/handler/texture_handler.go#L18-L83)
+- [texture_handler.go](file://internal/handler/texture_handler.go#L85-L172)
+
+### 材质服务（texture_service.go）
+- CreateTexture：校验用户存在、去重校验哈希、转换材质类型、创建记录
+- RecordTextureDownload：增加下载计数并记录日志
+- 其他查询与权限控制方法
+
+章节来源
+- [texture_service.go](file://internal/service/texture_service.go#L12-L64)
+- [texture_service.go](file://internal/service/texture_service.go#L162-L187)
+
+## 依赖关系分析
+- 配置到客户端：RustFSConfig -> NewStorage -> StorageClient
+- 客户端到管理器：StorageClient -> Manager（Init/GetClient/MustGetClient）
+- 业务到客户端：UploadService/TextureService -> StorageClient
+- 接口到业务：TextureHandler -> UploadService -> StorageClient
+
+```mermaid
+graph LR
+CFG["RustFSConfig"] --> NS["NewStorage(cfg)"]
+NS --> SC["StorageClient"]
+SC --> M["Manager.Init/GetClient/MustGetClient"]
+M --> H["TextureHandler"]
+H --> US["UploadService"]
+US --> SC
+TS["TextureService"] --> SC
+```
+
+图表来源
+- [config.go](file://pkg/config/config.go#L58-L66)
+- [minio.go](file://pkg/storage/minio.go#L20-L49)
+- [manager.go](file://pkg/storage/manager.go#L18-L44)
+- [upload_service.go](file://internal/service/upload_service.go#L78-L160)
+- [texture_handler.go](file://internal/handler/texture_handler.go#L18-L83)
+- [texture_service.go](file://internal/service/texture_service.go#L12-L64)
+
+## 性能考虑
+- 并发控制
+  - 上传直传采用预签名POST策略，客户端直接向对象存储发起请求，避免服务端转发带来的CPU与内存压力
+  - 服务端仅负责生成策略与返回表单数据，适合高并发场景
+- 连接复用
+  - minio-go客户端内部维护连接池与HTTP复用；建议在生产环境中保持长连接，避免频繁重建
+- 超时与重试
+  - 初始化阶段对ListBuckets设置了超时，防止阻塞启动
+  - 业务侧建议在调用方为上传/下载操作设置合理超时与指数退避重试
+- 缓存与预热
+  - 对频繁使用的桶名解析与策略生成可做缓存（需注意策略过期时间）
+- 资源限制
+  - 通过上传配置限制文件大小与扩展名，降低存储与带宽压力
+
+[本节为通用指导，无需特定文件引用]
+
+## 故障排查指南
+- 签名错误
+  - 现象：表单上传返回签名错误
+  - 排查要点：确认formData中多余字段被移除；确保file字段位于表单末尾；检查endpoint与useSSL一致性
+  - 参考实现位置：[minio.go](file://pkg/storage/minio.go#L82-L120)
+- 网络超时
+  - 现象：初始化或ListBuckets超时
+  - 排查要点：检查endpoint连通性、防火墙、TLS证书；适当增大超时时间
+  - 参考实现位置：[minio.go](file://pkg/storage/minio.go#L33-L42)
+- 凭据错误
+  - 现象：连接测试失败或策略生成失败
+  - 排查要点：核对AccessKey/SecretKey；确认桶映射正确；检查对象存储端策略与权限
+  - 参考实现位置：[minio.go](file://pkg/storage/minio.go#L20-L49)
+- 桶不存在
+  - 现象：GetBucket返回错误
+  - 排查要点：确认RustFSConfig.Buckets中包含所需桶名；核对环境变量覆盖逻辑
+  - 参考实现位置：[minio.go](file://pkg/storage/minio.go#L57-L64)，[config.go](file://pkg/config/config.go#L238-L253)
+- 接口调用失败
+  - 现象：接口返回400/500
+  - 排查要点：检查鉴权中间件、请求体绑定、日志输出；确认MustGetClient/MustGetRustFSConfig已调用
+  - 参考实现位置：[texture_handler.go](file://internal/handler/texture_handler.go#L18-L83)，[manager.go](file://pkg/storage/manager.go#L37-L44)，[config.go](file://pkg/config/config.go#L190-L236)
+
+章节来源
+- [minio.go](file://pkg/storage/minio.go#L20-L49)
+- [minio.go](file://pkg/storage/minio.go#L57-L64)
+- [minio.go](file://pkg/storage/minio.go#L82-L120)
+- [texture_handler.go](file://internal/handler/texture_handler.go#L18-L83)
+- [manager.go](file://pkg/storage/manager.go#L37-L44)
+- [config.go](file://pkg/config/config.go#L238-L253)
+
+## 结论
+- CarrotSkin通过StorageClient与minio-go实现了对S3兼容存储的完整封装，重点支持预签名POST直传与PUT上传
+- 上传流程清晰：接口层生成策略，前端直传对象存储，服务端仅负责策略与元数据登记
+- 分片上传与断点续传当前未在代码中直接体现；如需支持，可在客户端侧采用分片上传策略，并在服务端补充断点续传与合并逻辑
+- 建议结合业务需求完善下载与公开/私有资源的访问策略，并持续优化并发与连接复用
+
+[本节为总结性内容，无需特定文件引用]
+
+## 附录
+
+### 典型用例示例（代码示例路径）
+- 皮肤/披风文件上传
+  - 生成预签名POST URL：[upload_service.go](file://internal/service/upload_service.go#L117-L160)
+  - 接口调用入口：[texture_handler.go](file://internal/handler/texture_handler.go#L18-L83)
+- 私有资源临时链接生成（PUT）
+  - 生成预签名PUT URL：[minio.go](file://pkg/storage/minio.go#L66-L73)
+  - 业务侧调用：[upload_service.go](file://internal/service/upload_service.go#L78-L115)
+
+### 高级功能支持现状
+- 分片上传/断点续传
+  - 当前未在代码中直接实现；如需支持，可在客户端侧引入分片上传策略，并在服务端补充断点续传与合并逻辑
+- 下载
+  - 当前未直接暴露Download方法；可通过最终访问URL或GeneratePresignedURL生成临时下载链接
+
+[本节为概念性说明，无需特定文件引用]

.qoder/repowiki/zh/content/外部集成/邮件服务集成.md

@@ -0,0 +1,361 @@
+# 邮件服务集成
+
+<cite>
+**本文引用的文件列表**
+- [email.go](file://pkg/email/email.go)
+- [manager.go](file://pkg/email/manager.go)
+- [config.go](file://pkg/config/config.go)
+- [verification_service.go](file://internal/service/verification_service.go)
+- [auth_handler.go](file://internal/handler/auth_handler.go)
+- [redis.go](file://pkg/redis/redis.go)
+- [manager.go](file://pkg/redis/manager.go)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能与可靠性](#性能与可靠性)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件面向CarrotSkin项目的开发者与运维人员，系统性介绍基于SMTP的邮件服务实现与集成方式。重点覆盖以下内容：
+- 邮件服务核心结构体与方法（如Service、SendVerificationCode等）的实现逻辑
+- SMTP服务器参数配置（主机、端口、认证信息）与客户端初始化流程
+- 注册验证、密码重置、更换邮箱等场景的邮件发送流程
+- 与用户认证流程的集成方式（验证码生成、有效期管理、频率限制与安全考虑）
+- 初学者本地测试配置建议（如使用MailHog）
+- 高级用户可扩展的方向（错误重试机制、连接池优化、监控指标）
+
+## 项目结构
+邮件服务位于独立的pkg模块中，并与配置、Redis缓存、业务服务层以及HTTP处理器协同工作。整体组织如下：
+- 配置层：集中定义EmailConfig并通过环境变量加载
+- 邮件服务层：封装SMTP发送、主题与HTML正文构建
+- 缓存层：使用Redis存储验证码与频率限制
+- 业务服务层：生成验证码、校验验证码、根据类型路由到具体邮件方法
+- HTTP处理器：对外暴露发送验证码接口，调用业务服务层
+
+```mermaid
+graph TB
+subgraph "配置层"
+CFG["EmailConfig<br/>环境变量绑定"]
+end
+subgraph "邮件服务层"
+SVC["Service<br/>send()/Send* 方法"]
+MGR["manager.go<br/>Init/GetService/MustGetService"]
+end
+subgraph "缓存层"
+RCL["Redis Client<br/>Set/Get/Del/Exists"]
+end
+subgraph "业务服务层"
+VSRV["verification_service.go<br/>SendVerificationCode/VerifyCode"]
+end
+subgraph "HTTP处理器"
+AH["auth_handler.go<br/>SendVerificationCode 接口"]
+end
+CFG --> MGR
+MGR --> SVC
+SVC --> RCL
+AH --> VSRV
+VSRV --> SVC
+VSRV --> RCL
+```
+
+图表来源
+- [email.go](file://pkg/email/email.go#L1-L163)
+- [manager.go](file://pkg/email/manager.go#L1-L48)
+- [config.go](file://pkg/config/config.go#L98-L107)
+- [verification_service.go](file://internal/service/verification_service.go#L1-L119)
+- [auth_handler.go](file://internal/handler/auth_handler.go#L149-L192)
+- [redis.go](file://pkg/redis/redis.go#L1-L175)
+
+章节来源
+- [email.go](file://pkg/email/email.go#L1-L163)
+- [manager.go](file://pkg/email/manager.go#L1-L48)
+- [config.go](file://pkg/config/config.go#L98-L107)
+- [verification_service.go](file://internal/service/verification_service.go#L1-L119)
+- [auth_handler.go](file://internal/handler/auth_handler.go#L149-L192)
+- [redis.go](file://pkg/redis/redis.go#L1-L175)
+
+## 核心组件
+- Service（邮件服务）
+  - 职责：封装SMTP发送、主题与HTML正文构建、TLS/STARTTLS选择、日志记录
+  - 关键方法：SendVerificationCode、SendResetPassword、SendEmailVerification、SendChangeEmail、send
+- manager（邮件服务管理器）
+  - 职责：全局单例初始化、线程安全获取实例、未初始化保护
+  - 关键方法：Init、GetService、MustGetService
+- 配置（EmailConfig）
+  - 字段：Enabled、SMTPHost、SMTPPort、Username、Password、FromName
+  - 来源：环境变量绑定与默认值设置
+- 验证码服务（verification_service）
+  - 职责：生成6位数字验证码、存储到Redis、设置频率限制、按类型路由到具体邮件方法
+- Redis客户端（redis）
+  - 职责：连接管理、基础KV与集合操作、连接健康检查
+- HTTP处理器（auth_handler）
+  - 职责：对外暴露发送验证码接口，调用业务服务层
+
+章节来源
+- [email.go](file://pkg/email/email.go#L1-L163)
+- [manager.go](file://pkg/email/manager.go#L1-L48)
+- [config.go](file://pkg/config/config.go#L98-L107)
+- [verification_service.go](file://internal/service/verification_service.go#L1-L119)
+- [auth_handler.go](file://internal/handler/auth_handler.go#L149-L192)
+- [redis.go](file://pkg/redis/redis.go#L1-L175)
+
+## 架构总览
+下图展示从HTTP请求到邮件发送的完整链路，包括验证码生成、存储、频率限制与邮件发送。
+
+```mermaid
+sequenceDiagram
+participant C as "客户端"
+participant H as "auth_handler.SendVerificationCode"
+participant VS as "verification_service.SendVerificationCode"
+participant RS as "Redis Client"
+participant ES as "email.Service"
+participant SMTP as "SMTP服务器"
+C->>H : "POST /api/v1/auth/send-code"
+H->>VS : "调用发送验证码(类型, 邮箱)"
+VS->>RS : "检查频率限制(键 : rate_limit)"
+RS-->>VS : "存在/不存在"
+VS->>VS : "生成6位数字验证码"
+VS->>RS : "写入验证码(键 : code)"
+VS->>RS : "设置频率限制(键 : rate_limit)"
+VS->>ES : "根据类型调用具体发送方法"
+ES->>SMTP : "SMTP发送(465隐式TLS/587 STARTTLS)"
+SMTP-->>ES : "结果"
+ES-->>VS : "结果"
+VS-->>H : "结果"
+H-->>C : "发送成功响应"
+```
+
+图表来源
+- [auth_handler.go](file://internal/handler/auth_handler.go#L149-L192)
+- [verification_service.go](file://internal/service/verification_service.go#L40-L118)
+- [email.go](file://pkg/email/email.go#L57-L105)
+- [redis.go](file://pkg/redis/redis.go#L60-L78)
+
+## 详细组件分析
+
+### Service（邮件服务）类图
+Service负责SMTP发送、主题与HTML正文构建、TLS/STARTTLS选择与日志记录。
+
+```mermaid
+classDiagram
+class Service {
+-cfg : EmailConfig
+-logger : Logger
++SendVerificationCode(to, code, purpose) error
++SendResetPassword(to, code) error
++SendEmailVerification(to, code) error
++SendChangeEmail(to, code) error
+-send(to, subject, body) error
+-getSubject(purpose) string
+-getBody(code, purpose) string
+}
+```
+
+图表来源
+- [email.go](file://pkg/email/email.go#L1-L163)
+
+章节来源
+- [email.go](file://pkg/email/email.go#L1-L163)
+
+### 发送流程与TLS策略
+- 主题与正文
+  - 主题根据用途动态选择（邮箱验证、重置密码、更换邮箱）
+  - 正文为HTML模板，包含验证码展示与有效期提示
+- SMTP连接策略
+  - 465端口：使用隐式TLS（SendWithTLS）
+  - 587端口：使用STARTTLS（Send）
+- 认证方式
+  - 使用PlainAuth进行SMTP认证
+- 错误处理
+  - 失败时记录详细上下文（收件人、主题、SMTP主机与端口）
+  - 成功时记录成功日志
+
+```mermaid
+flowchart TD
+Start(["进入 send 方法"]) --> Build["构建邮件对象<br/>From/To/Subject/HTML/Headers"]
+Build --> Auth["构造SMTP认证信息"]
+Auth --> Addr["拼接地址 host:port"]
+Addr --> PortCheck{"端口为465?"}
+PortCheck --> |是| TLS["配置TLS(隐式)<br/>SendWithTLS"]
+PortCheck --> |否| StartTLS["Send(显式STARTTLS)"]
+TLS --> Result{"发送成功?"}
+StartTLS --> Result
+Result --> |否| LogErr["记录错误日志并返回错误"]
+Result --> |是| LogOK["记录成功日志并返回nil"]
+```
+
+图表来源
+- [email.go](file://pkg/email/email.go#L57-L105)
+
+章节来源
+- [email.go](file://pkg/email/email.go#L57-L105)
+
+### 验证码生成与存储（verification_service）
+- 验证码生成
+  - 6位纯数字随机验证码
+- 存储与有效期
+  - Redis键命名规范：verification:code:{type}:{email}，有效期10分钟
+- 频率限制
+  - Redis键：verification:rate_limit:{type}:{email}，限制1分钟内仅允许一次
+- 类型路由
+  - register -> SendEmailVerification
+  - reset_password -> SendResetPassword
+  - change_email -> SendChangeEmail
+  - 其他 -> SendVerificationCode
+
+```mermaid
+flowchart TD
+Enter(["进入 SendVerificationCode"]) --> RL["检查频率限制键是否存在"]
+RL --> |存在| RateErr["返回发送过于频繁错误"]
+RL --> |不存在| Gen["生成6位验证码"]
+Gen --> Store["写入Redis: code键 + 过期10分钟"]
+Store --> Limit["写入Redis: rate_limit键 + 过期1分钟"]
+Limit --> Route{"根据类型路由"}
+Route --> |register| SendEV["SendEmailVerification"]
+Route --> |reset_password| SendRP["SendResetPassword"]
+Route --> |change_email| SendCE["SendChangeEmail"]
+Route --> |其他| SendVC["SendVerificationCode"]
+SendEV --> Done(["返回成功"])
+SendRP --> Done
+SendCE --> Done
+SendVC --> Done
+```
+
+图表来源
+- [verification_service.go](file://internal/service/verification_service.go#L40-L118)
+
+章节来源
+- [verification_service.go](file://internal/service/verification_service.go#L1-L119)
+
+### HTTP处理器集成（auth_handler）
+- 发送验证码接口
+  - 解析请求、调用业务服务层、记录日志、返回响应
+- 注册流程中的验证码校验
+  - 在注册接口中调用VerifyCode校验验证码，失败即拒绝注册
+
+章节来源
+- [auth_handler.go](file://internal/handler/auth_handler.go#L149-L192)
+- [verification_service.go](file://internal/service/verification_service.go#L79-L98)
+
+## 依赖关系分析
+- 组件耦合
+  - Service依赖EmailConfig与Zap日志
+  - verification_service依赖Redis Client与email.Service
+  - auth_handler依赖verification_service与日志、Redis
+- 外部依赖
+  - SMTP客户端库用于发送邮件
+  - Redis客户端库用于KV与限流
+- 可能的循环依赖
+  - 当前结构清晰，未见循环依赖迹象
+
+```mermaid
+graph LR
+CFG["EmailConfig"] --> MGR["manager.Init/GetService"]
+MGR --> SVC["Service"]
+SVC --> SMTP["SMTP服务器"]
+VS["verification_service"] --> SVC
+VS --> RCL["Redis Client"]
+AH["auth_handler"] --> VS
+```
+
+图表来源
+- [email.go](file://pkg/email/email.go#L1-L163)
+- [manager.go](file://pkg/email/manager.go#L1-L48)
+- [config.go](file://pkg/config/config.go#L98-L107)
+- [verification_service.go](file://internal/service/verification_service.go#L1-L119)
+- [auth_handler.go](file://internal/handler/auth_handler.go#L149-L192)
+- [redis.go](file://pkg/redis/redis.go#L1-L175)
+
+章节来源
+- [email.go](file://pkg/email/email.go#L1-L163)
+- [manager.go](file://pkg/email/manager.go#L1-L48)
+- [config.go](file://pkg/config/config.go#L98-L107)
+- [verification_service.go](file://internal/service/verification_service.go#L1-L119)
+- [auth_handler.go](file://internal/handler/auth_handler.go#L149-L192)
+- [redis.go](file://pkg/redis/redis.go#L1-L175)
+
+## 性能与可靠性
+- 连接池与并发
+  - Redis客户端内置连接池（PoolSize），建议结合业务规模调整
+  - 邮件发送为短连接，建议避免在同一请求中频繁发送
+- 错误重试
+  - 当前实现未内置自动重试；可在业务层增加指数退避重试策略
+- 监控指标
+  - 建议采集：邮件发送成功率、耗时、失败原因分布、Redis读写延迟
+- 安全与合规
+  - 生产环境TLS校验建议开启（InsecureSkipVerify=false）
+  - 密码等敏感信息仅在内存中传输，避免落盘
+
+[本节为通用建议，无需列出章节来源]
+
+## 故障排查指南
+- 常见问题定位
+  - 邮件服务未启用：检查EmailConfig.Enabled与环境变量
+  - SMTP认证失败：核对Username/Password与SMTPHost/SMTPPort
+  - TLS握手失败：确认端口与TLS策略匹配（465隐式TLS vs 587 STARTTLS）
+  - Redis连接失败：检查Redis配置与网络连通性
+- 日志与告警
+  - 发送失败会记录详细上下文，优先查看日志中的错误堆栈
+  - 建议在网关或进程外添加告警规则（如连续失败阈值）
+- 本地测试
+  - 使用MailHog作为本地SMTP代理，便于调试与演示
+
+章节来源
+- [email.go](file://pkg/email/email.go#L57-L105)
+- [config.go](file://pkg/config/config.go#L229-L236)
+- [redis.go](file://pkg/redis/redis.go#L22-L52)
+
+## 结论
+CarrotSkin的邮件服务以简洁、可测试的方式实现了基于SMTP的验证码邮件发送，配合Redis完成验证码生成、存储与频率控制。通过HTTP处理器与业务服务层的清晰分层，系统具备良好的可维护性与扩展性。建议在生产环境中完善错误重试、连接池优化与监控指标，以进一步提升稳定性与可观测性。
+
+[本节为总结性内容，无需列出章节来源]
+
+## 附录
+
+### SMTP配置与初始化
+- 配置项（EmailConfig）
+  - Enabled：是否启用邮件功能
+  - SMTPHost：SMTP服务器主机
+  - SMTPPort：SMTP服务器端口（常用465或587）
+  - Username/Password：SMTP认证凭据
+  - FromName：发件人显示名称
+- 环境变量绑定
+  - EMAIL_ENABLED、EMAIL_SMTP_HOST、EMAIL_SMTP_PORT、EMAIL_USERNAME、EMAIL_PASSWORD、EMAIL_FROM_NAME
+- 初始化步骤
+  - 通过manager.Init传入EmailConfig与Logger，随后通过MustGetService获取实例
+  - 在应用启动阶段完成初始化，确保后续调用可用
+
+章节来源
+- [config.go](file://pkg/config/config.go#L98-L107)
+- [config.go](file://pkg/config/config.go#L229-L236)
+- [manager.go](file://pkg/email/manager.go#L20-L43)
+
+### 场景化使用路径
+- 注册验证
+  - HTTP接口：auth_handler.SendVerificationCode
+  - 业务流程：verification_service.SendVerificationCode -> email.Service.SendEmailVerification
+- 密码重置
+  - 业务流程：verification_service.SendVerificationCode -> email.Service.SendResetPassword
+- 更换邮箱
+  - 业务流程：verification_service.SendVerificationCode -> email.Service.SendChangeEmail
+
+章节来源
+- [auth_handler.go](file://internal/handler/auth_handler.go#L149-L192)
+- [verification_service.go](file://internal/service/verification_service.go#L40-L118)
+- [email.go](file://pkg/email/email.go#L42-L55)
+
+### 本地测试建议（MailHog）
+- 启动MailHog作为本地SMTP代理
+- 将EmailConfig配置指向MailHog的SMTP地址与端口
+- 通过auth_handler的发送验证码接口验证端到端流程
+- 在MailHog Web界面查看邮件内容与收件人信息
+
+[本节为通用建议，无需列出章节来源]