# JWT Claims 定义

---
DDS-Section: 3. 认证与登录设计 - 3.3 JWT 中间件行为
DDS-Lines: L193-L197
---

## Claims 结构

```go
type JWTClaims struct {
    UserID      int64  `json:"user_id"`
    Username    string `json:"username"`
    EnglishName string `json:"english_name"`
    Phone       string `json:"phone"`
    GroupName   string `json:"group_name"`
    Role        string `json:"role"`
    DevRole     string `json:"dev_role"`
    Status      string `json:"status"`
    jwt.RegisteredClaims
}
```

## Claims 字段说明

| 字段 | 类型 | 必填 | 来源 | 用途 |
|:---|:---|:---|:---|:---|
| `user_id` | int64 | ✅ | users.id | 唯一用户标识 |
| `username` | string | ✅ | users.username | 中文真实姓名 |
| `english_name` | string | ❌ | users.english_username | 英文昵称 |
| `phone` | string | ❌ | users.phone | 手机号 |
| `group_name` | string | ❌ | users.group_name | 所属小组 |
| `role` | string | ✅ | users.role | 系统角色 |
| `dev_role` | string | ❌ | users.dev_role | 开发角色 |
| `status` | string | ✅ | users.status | 账户状态 |

## JWT 配置

| 配置项 | 值 | 说明 |
|:---|:---|:---|
| 签名算法 | HS256 | HMAC SHA-256 |
| 有效期 | 4 小时 | `exp` claim |
| 签发者 | (空) | `iss` claim 未使用 |
| 秘钥来源 | 环境变量/配置 | `JWT_SECRET` |

## 下游模块使用

其他模块从 Gin Context 中提取用户信息：

```go
// 获取用户ID
userID := ctx.GetInt64("user_id")

// 获取角色
role := ctx.GetString("role")

// 判断是否管理员
isAdmin := role == "superadmin" || role == "admin"
```

## 兼容性要求

⚠️ **重要**：修改 Claims 字段时必须：

1. 确认所有下游模块解析逻辑兼容
2. 新增字段需提供默认值
3. 不可删除或重命名现有必填字段
4. 更新本文档与 Context 注入键列表
