flowchart TB
    subgraph External["外部依赖"]
        Redis[(Redis<br/>缓存集群)]
        Nacos[Nacos<br/>配置中心]
        PG[(PostgreSQL)]
    end

    subgraph SharedComponents["共享组件层 (pkg/)"]
        Auth[Auth 组件<br/>JWT + RBAC]
        Cache[Cache 组件<br/>Redis 抽象]
        Config[Config 组件<br/>配置管理]
    end

    subgraph Services["业务服务层"]
        Identity[Identity Service<br/>身份服务]
        Conversation[Conversation Service<br/>对话服务]
        ModelRouter[Model Router<br/>模型路由]
        Analytics[Analytics Service<br/>分析服务]
        Notification[Notification Service<br/>通知服务]
        Knowledge[Knowledge Service<br/>知识服务]
    end

    subgraph Middleware["中间件层"]
        AuthMW[Auth Middleware<br/>认证中间件]
        PermMW[Permission Middleware<br/>权限中间件]
    end

    Client[客户端请求] --> AuthMW
    AuthMW --> Identity
    AuthMW --> Conversation
    AuthMW --> Knowledge

    AuthMW -.验证 Token.-> Auth
    PermMW -.检查权限.-> Auth

    Identity -.生成 Token.-> Auth
    Identity -.黑名单.-> Cache

    Conversation -.鉴权.-> Auth
    Conversation -.上下文缓存.-> Cache

    ModelRouter -.AB 测试缓存.-> Cache
    Analytics -.指标缓存.-> Cache
    Notification -.实时通知.-> Cache
    Knowledge -.查询缓存.-> Cache

    Config -.加载配置.-> Nacos

    Auth --> PG
    Cache --> Redis

    Identity --> Config
    Conversation --> Config
    ModelRouter --> Config
    Analytics --> Config
    Notification --> Config
    Knowledge --> Config

    style Auth fill:#e1f5ff
    style Cache fill:#fff4e1
    style Config fill:#e8f5e9
    style SharedComponents fill:#f5f5f5

flowchart LR
    subgraph Auth["Auth 组件"]
        JWT[JWT Manager<br/>令牌管理]
        RBAC[RBAC Manager<br/>权限管理]
        Claims[Claims<br/>用户声明]
    end

    subgraph Middleware["中间件"]
        AuthMW[Auth Middleware]
        PermMW[Permission Middleware]
        RoleMW[Role Middleware]
    end

    Request[HTTP 请求] --> AuthMW
    AuthMW --> JWT
    JWT --> Claims

    AuthMW --> PermMW
    PermMW --> RBAC

    AuthMW --> RoleMW
    RoleMW --> RBAC

    RBAC --> Handler[业务 Handler]

    style JWT fill:#e3f2fd
    style RBAC fill:#fff3e0
    style Claims fill:#f3e5f5

sequenceDiagram
    autonumber
    participant Client as 客户端
    participant Gateway as API 网关
    participant AuthMW as Auth Middleware
    participant JWT as JWT Manager
    participant RBAC as RBAC Manager
    participant Handler as 业务 Handler
    participant Cache as Redis Cache
    participant DB as PostgreSQL

    Note over Client,DB: 场景1：用户登录获取 Token
    Client->>Gateway: POST /api/v1/auth/login<br/>{username, password}
    Gateway->>Handler: 路由到 Identity Service
    Handler->>DB: 验证用户凭证
    DB-->>Handler: 用户信息 + 角色
    Handler->>JWT: GenerateAccessToken(userID, roles)
    JWT->>JWT: 构造 Claims<br/>签名 Token (HS256)
    JWT-->>Handler: Access Token (1h)
    Handler->>JWT: GenerateRefreshToken(userID)
    JWT-->>Handler: Refresh Token (7d)
    Handler-->>Client: 200 OK<br/>{access_token, refresh_token}

    Note over Client,DB: 场景2：携带 Token 访问受保护资源
    Client->>Gateway: GET /api/v1/conversations<br/>Header: Authorization: Bearer {token}
    Gateway->>AuthMW: 拦截请求
    AuthMW->>AuthMW: 提取 Token<br/>（从 Authorization Header）

    AuthMW->>Cache: 检查 Token 黑名单
    Cache-->>AuthMW: 不在黑名单

    AuthMW->>JWT: ValidateToken(tokenString)
    JWT->>JWT: 验证签名<br/>检查过期时间
    JWT-->>AuthMW: Claims {userID, roles}

    AuthMW->>AuthMW: 将 Claims 存入 Context
    AuthMW->>Handler: 继续请求处理
    Handler-->>Client: 200 OK + 数据

    Note over Client,DB: 场景3：权限检查
    Client->>Gateway: POST /api/v1/knowledge/documents<br/>Header: Authorization: Bearer {token}
    Gateway->>AuthMW: 认证检查
    AuthMW->>JWT: ValidateToken(token)
    JWT-->>AuthMW: Claims {roles: ["user"]}

    AuthMW->>PermMW: 权限中间件检查
    PermMW->>PermMW: 从 Context 提取 roles
    PermMW->>RBAC: CheckUserPermission(roles, "kg:write")
    RBAC->>RBAC: 遍历用户角色<br/>查找权限映射
    RBAC-->>PermMW: false (user 无 kg:write 权限)
    PermMW-->>Client: 403 Forbidden<br/>{"error": "Insufficient permissions"}

    Note over Client,DB: 场景4：Token 刷新
    Client->>Gateway: POST /api/v1/auth/refresh<br/>{refresh_token}
    Gateway->>Handler: 路由到 Identity Service
    Handler->>DB: 查询用户最新信息
    DB-->>Handler: 用户信息 + 角色
    Handler->>JWT: RefreshAccessToken(refresh_token, username, email, roles)
    JWT->>JWT: 验证 Refresh Token
    JWT->>JWT: 生成新 Access Token
    JWT-->>Handler: 新 Access Token
    Handler-->>Client: 200 OK<br/>{access_token}

    Note over Client,DB: 场景5：Token 撤销（登出）
    Client->>Gateway: POST /api/v1/auth/logout<br/>{token}
    Gateway->>Handler: 路由到 Identity Service
    Handler->>JWT: ValidateToken(token)
    JWT-->>Handler: Claims
    Handler->>Cache: 将 Token 加入黑名单<br/>TTL = Token 剩余有效期
    Cache-->>Handler: OK
    Handler-->>Client: 200 OK

type JWTManager struct {
    secretKey     string
    accessExpiry  time.Duration  // Access Token过期时间（1小时）
    refreshExpiry time.Duration  // Refresh Token过期时间（7天）
}

type Claims struct {
    UserID   string   `json:"user_id"`
    Username string   `json:"username"`
    Email    string   `json:"email"`
    Roles    []string `json:"roles"`
    jwt.RegisteredClaims
}

// 生成 Access Token
func (m *JWTManager) GenerateAccessToken(
    userID, username, email string,
    roles []string
) (string, error) {
    claims := Claims{
        UserID:   userID,
        Username: username,
        Email:    email,
        Roles:    roles,
        RegisteredClaims: jwt.RegisteredClaims{
            ExpiresAt: jwt.NewNumericDate(time.Now().Add(m.accessExpiry)),
            IssuedAt:  jwt.NewNumericDate(time.Now()),
            Issuer:    "voice-assistant",
            Subject:   userID,
        },
    }

    token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
    return token.SignedString([]byte(m.secretKey))
}

// 验证 Token
func (m *JWTManager) ValidateToken(tokenString string) (*Claims, error) {
    token, err := jwt.ParseWithClaims(
        tokenString,
        &Claims{},
        func(token *jwt.Token) (interface{}, error) {
            return []byte(m.secretKey), nil
        },
    )

    if err != nil {
        return nil, ErrInvalidToken
    }

    if claims, ok := token.Claims.(*Claims); ok && token.Valid {
        return claims, nil
    }

    return nil, ErrInvalidToken
}

// 初始化
jwtManager := auth.NewJWTManager(
    "your-secret-key",
    1*time.Hour,      // Access Token 1小时
    7*24*time.Hour,   // Refresh Token 7天
)

// 生成Token
accessToken, err := jwtManager.GenerateAccessToken(
    "user_123",
    "zhangsan",
    "zhangsan@example.com",
    []string{"user", "admin"},
)

// 验证Token
claims, err := jwtManager.ValidateToken(accessToken)

type RBACManager struct {
    mu              sync.RWMutex
    rolePermissions map[Role][]Permission
}

type Role string
const (
    RoleAdmin     Role = "admin"
    RoleUser      Role = "user"
    RoleDeveloper Role = "developer"
    RoleGuest     Role = "guest"
)

type Permission string
const (
    // 用户权限
    PermissionReadUser   Permission = "user:read"
    PermissionWriteUser  Permission = "user:write"
    PermissionDeleteUser Permission = "user:delete"

    // 对话权限
    PermissionChat        Permission = "chat:use"
    PermissionChatHistory Permission = "chat:history"

    // 知识图谱权限
    PermissionReadKG   Permission = "kg:read"
    PermissionWriteKG  Permission = "kg:write"
    PermissionDeleteKG Permission = "kg:delete"

    // RAG 权限
    PermissionUseRAG    Permission = "rag:use"
    PermissionManageRAG Permission = "rag:manage"

    // Agent 权限
    PermissionUseAgent    Permission = "agent:use"
    PermissionManageAgent Permission = "agent:manage"

    // 系统权限
    PermissionReadMetrics  Permission = "system:metrics"
    PermissionManageSystem Permission = "system:manage"
)

func (m *RBACManager) initializeDefaultRoles() {
    // Admin - 完全访问权限
    m.rolePermissions[RoleAdmin] = []Permission{
        PermissionReadUser, PermissionWriteUser, PermissionDeleteUser,
        PermissionChat, PermissionChatHistory,
        PermissionReadKG, PermissionWriteKG, PermissionDeleteKG,
        PermissionUseRAG, PermissionManageRAG,
        PermissionUseAgent, PermissionManageAgent,
        PermissionReadMetrics, PermissionManageSystem,
    }

    // Developer - 开发者权限（读写、无删除）
    m.rolePermissions[RoleDeveloper] = []Permission{
        PermissionReadUser,
        PermissionChat, PermissionChatHistory,
        PermissionReadKG, PermissionWriteKG,
        PermissionUseRAG, PermissionManageRAG,
        PermissionUseAgent, PermissionManageAgent,
        PermissionReadMetrics,
    }

    // User - 标准用户权限（仅使用功能）
    m.rolePermissions[RoleUser] = []Permission{
        PermissionReadUser,
        PermissionChat, PermissionChatHistory,
        PermissionReadKG,
        PermissionUseRAG,
        PermissionUseAgent,
    }

    // Guest - 受限访问（仅读）
    m.rolePermissions[RoleGuest] = []Permission{
        PermissionChat,
        PermissionReadKG,
    }
}

// 检查用户（多角色）是否拥有权限
func (m *RBACManager) CheckUserPermission(roles []string, permission Permission) bool {
    m.mu.RLock()
    defer m.mu.RUnlock()

    // 遍历用户所有角色，任一角色有权限即通过
    for _, roleStr := range roles {
        role := Role(roleStr)
        if permissions, exists := m.rolePermissions[role]; exists {
            for _, p := range permissions {
                if p == permission {
                    return true
                }
            }
        }
    }
    return false
}

// 动态添加权限到角色
func (m *RBACManager) AddPermissionToRole(role Role, permission Permission) {
    m.mu.Lock()
    defer m.mu.Unlock()

    if permissions, exists := m.rolePermissions[role]; exists {
        // 检查权限是否已存在
        for _, p := range permissions {
            if p == permission {
                return
            }
        }
        m.rolePermissions[role] = append(permissions, permission)
    } else {
        m.rolePermissions[role] = []Permission{permission}
    }
}

func AuthMiddleware(jwtManager *auth.JWTManager) gin.HandlerFunc {
    return func(c *gin.Context) {
        // 1. 提取 Authorization Header
        authHeader := c.GetHeader("Authorization")
        if authHeader == "" {
            c.JSON(http.StatusUnauthorized, gin.H{"error": "Authorization header required"})
            c.Abort()
            return
        }

        // 2. 检查 Bearer Scheme
        parts := strings.SplitN(authHeader, " ", 2)
        if len(parts) != 2 || parts[0] != "Bearer" {
            c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid authorization header format"})
            c.Abort()
            return
        }

        tokenString := parts[1]

        // 3. 验证 Token
        claims, err := jwtManager.ValidateToken(tokenString)
        if err != nil {
            if err == auth.ErrExpiredToken {
                c.JSON(http.StatusUnauthorized, gin.H{"error": "Token expired"})
            } else {
                c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid token"})
            }
            c.Abort()
            return
        }

        // 4. 将用户信息存入 Context
        c.Set("user_id", claims.UserID)
        c.Set("username", claims.Username)
        c.Set("email", claims.Email)
        c.Set("roles", claims.Roles)
        c.Set("claims", claims)

        c.Next()
    }
}

// 权限检查中间件
func RequirePermission(rbacManager *auth.RBACManager, permission auth.Permission) gin.HandlerFunc {
    return func(c *gin.Context) {
        // 从 Context 获取角色
        rolesInterface, exists := c.Get("roles")
        if !exists {
            c.JSON(http.StatusForbidden, gin.H{"error": "No roles found in context"})
            c.Abort()
            return
        }

        roles, ok := rolesInterface.([]string)
        if !ok {
            c.JSON(http.StatusForbidden, gin.H{"error": "Invalid roles format"})
            c.Abort()
            return
        }

        // 检查权限
        if !rbacManager.CheckUserPermission(roles, permission) {
            c.JSON(http.StatusForbidden, gin.H{
                "error":      "Insufficient permissions",
                "required":   permission,
                "user_roles": roles,
            })
            c.Abort()
            return
        }

        c.Next()
    }
}

flowchart TB
    subgraph CacheLayer["Cache 组件层"]
        Interface[Cache Interface<br/>统一接口]
        Redis[Redis Cache<br/>实现类]
        Serializer[Serializer<br/>序列化器]
        Options[Cache Options<br/>配置选项]
    end

    subgraph UseCases["使用场景"]
        Session[会话缓存<br/>Token黑名单]
        Context[上下文缓存<br/>对话历史]
        ABTest[AB测试缓存<br/>变体分配]
        Metrics[指标缓存<br/>实时统计]
        Query[查询缓存<br/>知识检索]
    end

    subgraph RedisOps["Redis 操作"]
        String[String<br/>GET/SET]
        Hash[Hash<br/>HGET/HSET]
        List[List<br/>LPUSH/RPOP]
        ZSet[Sorted Set<br/>ZADD/ZRANGE]
        Expire[TTL<br/>过期管理]
    end

    Interface --> Redis
    Redis --> Serializer
    Redis --> Options

    Session --> Interface
    Context --> Interface
    ABTest --> Interface
    Metrics --> Interface
    Query --> Interface

    Redis --> String
    Redis --> Hash
    Redis --> List
    Redis --> ZSet
    Redis --> Expire

    Redis -.连接.-> RedisServer[(Redis Server)]

    style Redis fill:#fff4e1
    style Interface fill:#e8f5e9
    style RedisServer fill:#ffebee

sequenceDiagram
    autonumber
    participant Client as 客户端
    participant Handler as 业务 Handler
    participant Cache as Cache Client
    participant Redis as Redis Server
    participant DB as 数据库

    Note over Client,DB: 场景1：缓存穿透（Cache-Aside 模式）
    Client->>Handler: 请求数据（如用户信息）
    Handler->>Cache: Get(key)
    Cache->>Redis: GET key
    Redis-->>Cache: nil (缓存未命中)
    Cache-->>Handler: ErrCacheMiss

    Handler->>DB: 查询数据库
    DB-->>Handler: 用户数据

    Handler->>Cache: Set(key, data, TTL)
    Cache->>Redis: SET key value EX ttl
    Redis-->>Cache: OK

    Handler-->>Client: 返回数据

    Note over Client,DB: 场景2：缓存命中
    Client->>Handler: 请求相同数据
    Handler->>Cache: Get(key)
    Cache->>Redis: GET key
    Redis-->>Cache: 缓存数据
    Cache-->>Handler: 反序列化数据
    Handler-->>Client: 返回数据（无需查库）

    Note over Client,DB: 场景3：AB测试变体缓存
    Client->>Handler: 请求模型路由
    Handler->>Cache: GetObject("ab_test:user:123:variant")
    Cache->>Redis: GET ab_test:user:123:variant
    Redis-->>Cache: nil
    Cache-->>Handler: ErrCacheMiss

    Handler->>Handler: 执行变体选择算法
    Handler->>Cache: SetObject(key, variant, TTL)
    Cache->>Cache: JSON 序列化 variant
    Cache->>Redis: SET key json_data EX ttl
    Redis-->>Cache: OK
    Handler-->>Client: 返回选中变体

    Note over Client,DB: 场景4：实时指标缓存（原子计数）
    Client->>Handler: 发起对话请求
    Handler->>Cache: Incr("metrics:requests:today")
    Cache->>Redis: INCR metrics:requests:today
    Redis-->>Cache: 1234（递增后的值）
    Cache-->>Handler: 1234

    Handler->>Cache: Incr("metrics:tokens:today")
    Cache->>Redis: INCRBY metrics:tokens:today 500
    Redis-->>Cache: 123456

    Handler-->>Client: 处理完成

    Note over Client,DB: 场景5：会话上下文缓存（带过期）
    Client->>Handler: 获取对话上下文
    Handler->>Cache: GetObject("context:conv_123")
    Cache->>Redis: GET context:conv_123
    Redis-->>Cache: JSON 数据
    Cache->>Cache: 反序列化为 Context 对象
    Cache-->>Handler: Context 对象

    Handler->>Handler: 追加新消息
    Handler->>Cache: SetObject("context:conv_123", context, 5min)
    Cache->>Cache: JSON 序列化
    Cache->>Redis: SET context:conv_123 data EX 300
    Redis-->>Cache: OK
    Handler-->>Client: 返回上下文

    Note over Client,DB: 场景6：通知推送（Sorted Set）
    Client->>Handler: 发送通知
    Handler->>Cache: (使用 Redis ZADD)
    Cache->>Redis: ZADD notification:user:123 timestamp json_data
    Redis-->>Cache: OK

    Handler->>Cache: (删除旧通知)
    Cache->>Redis: ZREMRANGEBYRANK notification:user:123 0 -101
    Redis-->>Cache: OK

    Handler->>Cache: (设置过期)
    Cache->>Redis: EXPIRE notification:user:123 2592000
    Redis-->>Cache: OK
    Handler-->>Client: 通知发送成功

type RedisCache struct {
    client *redis.Client
    prefix string
}

func NewRedisCache(
    addr, password string,
    db int,
    prefix string
) *RedisCache {
    client := redis.NewClient(&redis.Options{
        Addr:     addr,
        Password: password,
        DB:       db,
    })

    return &RedisCache{
        client: client,
        prefix: prefix,
    }
}

// 设置缓存
func (c *RedisCache) Set(
    ctx context.Context,
    key string,
    value interface{},
    ttl time.Duration
) error {
    data, err := json.Marshal(value)
    if err != nil {
        return err
    }

    return c.client.Set(
        ctx,
        c.prefix+key,
        data,
        ttl,
    ).Err()
}

// 获取缓存
func (c *RedisCache) Get(
    ctx context.Context,
    key string,
    dest interface{}
) error {
    data, err := c.client.Get(ctx, c.prefix+key).Bytes()
    if err != nil {
        if err == redis.Nil {
            return ErrCacheMiss
        }
        return err
    }

    return json.Unmarshal(data, dest)
}

// 删除缓存
func (c *RedisCache) Delete(
    ctx context.Context,
    key string
) error {
    return c.client.Del(ctx, c.prefix+key).Err()
}

cache := cache.NewRedisCache(
    "localhost:6379",
    "",
    0,
    &cache.CacheOptions{
        KeyPrefix:  "voiceassistant:",
        DefaultTTL: 5 * time.Minute,
        Serializer: &cache.JSONSerializer{},
    },
)

// 设置缓存（自动序列化）
user := User{ID: "123", Name: "张三"}
err := cache.SetObject(ctx, "user:123", user, 1*time.Hour)

// 获取缓存（自动反序列化）
var cachedUser User
err = cache.GetObject(ctx, "user:123", &cachedUser)
if err == redis.Nil {
    // 缓存未命中，从数据库加载
    cachedUser = loadFromDB("123")
    cache.SetObject(ctx, "user:123", cachedUser, 1*time.Hour)
}

// 删除缓存
cache.Delete(ctx, "user:123")

// 原子计数
count, err := cache.Incr(ctx, "metrics:requests")

// 检查存在
exists, err := cache.Exists(ctx, "user:123")

flowchart TB
    subgraph ConfigLayer["Config 组件层"]
        Manager[Config Manager<br/>配置管理器]
        Viper[Viper<br/>配置解析]
        NacosClient[Nacos Client<br/>配置中心客户端]
    end

    subgraph Sources["配置源"]
        LocalFile[本地文件<br/>config.yaml]
        EnvVars[环境变量<br/>ENV Override]
        NacosServer[Nacos Server<br/>配置中心]
    end

    subgraph Modes["配置模式"]
        ModeLocal[Local Mode<br/>本地模式]
        ModeNacos[Nacos Mode<br/>配置中心模式]
    end

    subgraph Services["业务服务"]
        IdentitySvc[Identity Service]
        ConvSvc[Conversation Service]
        ModelRouter[Model Router]
        OtherSvc[其他服务...]
    end

    Manager --> Viper
    Manager --> NacosClient

    ModeLocal -.加载.-> LocalFile
    ModeLocal -.覆盖.-> EnvVars

    ModeNacos -.连接配置.-> LocalFile
    ModeNacos -.拉取配置.-> NacosServer
    ModeNacos -.监听变更.-> NacosServer

    Manager --> ModeLocal
    Manager --> ModeNacos

    IdentitySvc -.初始化.-> Manager
    ConvSvc -.初始化.-> Manager
    ModelRouter -.初始化.-> Manager
    OtherSvc -.初始化.-> Manager

    NacosServer -.推送变更.-> Manager
    Manager -.热加载.-> Services

    style Manager fill:#e8f5e9
    style NacosClient fill:#fff3e0
    style NacosServer fill:#ffebee

sequenceDiagram
    autonumber
    participant Service as 业务服务
    participant Manager as Config Manager
    participant Viper as Viper
    participant File as 本地文件
    participant Nacos as Nacos Server

    Note over Service,Nacos: 场景1：本地模式配置加载
    Service->>Manager: LoadConfig("config.yaml", "identity-service")
    Manager->>Manager: 检查 CONFIG_MODE 环境变量<br/>mode = "local"

    Manager->>Viper: SetConfigFile("config.yaml")
    Manager->>File: 读取配置文件
    File-->>Viper: YAML 内容
    Viper->>Viper: 解析 YAML
    Viper-->>Manager: 配置对象

    Manager-->>Service: 配置加载成功
    Service->>Manager: Unmarshal(&config)
    Manager->>Viper: Unmarshal(&config)
    Viper-->>Service: 配置结构体

    Note over Service,Nacos: 场景2：Nacos 模式配置加载
    Service->>Manager: LoadConfig("nacos.yaml", "conversation-service")
    Manager->>Manager: 检查 CONFIG_MODE 环境变量<br/>mode = "nacos"

    Manager->>File: 读取 Nacos 连接配置
    File-->>Manager: Nacos 地址、命名空间等

    Manager->>Manager: 环境变量覆盖<br/>NACOS_SERVER_ADDR, NACOS_NAMESPACE

    Manager->>Nacos: 创建 Nacos 客户端<br/>连接配置中心
    Nacos-->>Manager: 客户端连接成功

    Manager->>Nacos: GetConfig(dataId, group)
    Nacos-->>Manager: 配置内容（YAML 字符串）

    Manager->>Viper: ReadConfig(yamlString)
    Viper->>Viper: 解析 YAML
    Viper-->>Manager: 配置对象

    Manager->>Nacos: ListenConfig(dataId, group, onChange)
    Nacos-->>Manager: 监听已注册

    Manager-->>Service: 配置加载成功

    Service->>Manager: Unmarshal(&config)
    Manager->>Viper: Unmarshal(&config)
    Viper-->>Service: 配置结构体

    Note over Service,Nacos: 场景3：Nacos 配置热更新
    Nacos->>Manager: 推送配置变更通知<br/>onChange(namespace, group, dataId, newData)
    Manager->>Manager: 打印日志：Config changed

    Manager->>Viper: SetConfigType("yaml")
    Manager->>Viper: ReadConfig(newData)
    Viper->>Viper: 重新解析 YAML
    Viper-->>Manager: 新配置对象

    Manager->>Manager: 打印日志：Config reloaded successfully

    Note right of Manager: 服务可通过<br/>定时检查配置<br/>或回调机制<br/>应用新配置

    Note over Service,Nacos: 场景4：配置查询
    Service->>Manager: GetString("server.port")
    Manager->>Viper: GetString("server.port")
    Viper-->>Service: "8080"

    Service->>Manager: GetInt("database.max_connections")
    Manager->>Viper: GetInt("database.max_connections")
    Viper-->>Service: 100

    Service->>Manager: UnmarshalKey("redis", &redisConfig)
    Manager->>Viper: UnmarshalKey("redis", &redisConfig)
    Viper-->>Service: Redis 配置对象

    Note over Service,Nacos: 场景5：配置加载失败回退
    Service->>Manager: LoadConfig("config.yaml", "service")
    Manager->>Nacos: GetConfig(dataId, group)
    Nacos-->>Manager: 网络错误

    Manager->>Manager: 检查本地缓存<br/>/tmp/nacos/cache/
    Manager->>File: 读取缓存配置
    File-->>Manager: 缓存的配置内容

    Manager->>Viper: ReadConfig(cachedData)
    Viper-->>Manager: 配置对象

    Manager-->>Service: 使用缓存配置继续运行

    Manager->>Manager: 启动定时重试连接 Nacos

server:
  host: '0.0.0.0'
  port: 8080
  grpc_port: 9090

database:
  host: 'localhost'
  port: 5432
  max_connections: 100

redis:
  addr: 'localhost:6379'
  password: ''
  db: 0

type Config struct {
    Server   ServerConfig
    Database DatabaseConfig
    Redis    RedisConfig
    JWT      JWTConfig
}

type ServerConfig struct {
    Host     string
    Port     int
    GRPCPort int
    Workers  int
}

// 初始化配置管理器
manager := config.NewManager()

// 加载配置（根据 CONFIG_MODE 环境变量自动选择模式）
err := manager.LoadConfig("config.yaml", "identity-service")
if err != nil {
    log.Fatal(err)
}

// 解析配置到结构体
type AppConfig struct {
    Server   ServerConfig   `mapstructure:"server"`
    Database DatabaseConfig `mapstructure:"database"`
    Redis    RedisConfig    `mapstructure:"redis"`
}

var appConfig AppConfig
err = manager.Unmarshal(&appConfig)
if err != nil {
    log.Fatal(err)
}

// 查询单个配置项
port := manager.GetInt("server.port")
host := manager.GetString("server.host")

// 启动服务
server := gin.Default()
server.Run(fmt.Sprintf("%s:%d", host, port))

// 关闭时清理资源
defer manager.Close()

flowchart LR
    subgraph Init["服务启动初始化"]
        S1[1. 加载 Config]
        S2[2. 初始化 Cache<br/>连接 Redis]
        S3[3. 初始化 Auth<br/>JWT + RBAC]
        S4[4. 注册中间件]
        S5[5. 启动服务]
    end

    subgraph Runtime["运行时协作"]
        Request[HTTP 请求]
        AuthMW[Auth Middleware]
        Business[业务逻辑]
        CacheOp[缓存操作]
        ConfigQuery[配置查询]
    end

    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S5

    Request --> AuthMW
    AuthMW --> Business
    Business --> CacheOp
    Business --> ConfigQuery

    S1 -.提供配置.-> S2
    S1 -.提供配置.-> S3

    AuthMW -.Token验证.-> S3
    CacheOp -.黑名单/会话.-> S2
    ConfigQuery -.运行时参数.-> S1

    style S1 fill:#e8f5e9
    style S2 fill:#fff4e1
    style S3 fill:#e1f5ff

Client
  → API Gateway
    → Identity Service Handler
      ① Config.GetInt("jwt.access_expiry")  // 查询 Token 有效期配置
      ② Auth.GenerateAccessToken(...)        // 生成 Access Token
      ③ Auth.GenerateRefreshToken(...)       // 生成 Refresh Token
      ④ Cache.Delete("user:sessions:old")   // 清理旧会话
    ← 返回 {access_token, refresh_token}

Client
  → API Gateway
    → Auth Middleware
      ① Auth.ValidateToken(token)           // 验证 Token
      ② Cache.Exists("token:blacklist:xxx") // 检查黑名单
    → Conversation Service Handler
      ③ Cache.GetObject("context:conv_123") // 获取对话上下文
      ④ Config.GetInt("context.max_messages") // 获取上下文长度配置
      ⑤ [业务逻辑] 生成回复
      ⑥ Cache.SetObject("context:conv_123", context) // 更新上下文缓存
      ⑦ Cache.Incr("metrics:requests:today") // 增加请求计数
    ← 返回对话响应

Nacos Server
  → Config Manager
    ① 接收配置变更通知
    ② Viper.ReadConfig(newYAML)           // 解析新配置
    ③ 打印日志：Config reloaded
  → [应用服务自行处理]
    ④ 定时检查配置变化
    ⑤ 应用新配置（如更新限流阈值）

log.Info("Token generated", "user_id", userID, "roles", roles)
log.Warn("Token validation failed", "error", err, "ip", clientIP)
log.Error("RBAC check failed", "user_id", userID, "permission", permission)

log.Debug("Cache hit", "key", key, "ttl", ttl)
log.Warn("Cache miss", "key", key)
log.Error("Redis connection failed", "error", err, "addr", redisAddr)

log.Info("Config loaded", "mode", mode, "source", source)
log.Info("Config reloaded", "data_id", dataID, "group", group)
log.Error("Nacos connection failed", "error", err, "server", nacosAddr)