datai-vue/docs/api-docs/system/2026-01-21-002-02-api-后端国际化.md

# API 文档：后端国际化接口

## 元数据
- **需求编号**：2026-01-21-002-02
- **创建时间**：2026-01-26
- **创建人**：SSOT 架构师
- **父需求**：2026-01-21-002-项目国际化需求

## API 概述
后端国际化接口提供了国际化资源管理、语言偏好管理等功能，支持错误消息、日志消息、验证消息、通知消息的国际化。系统支持中文和英文两种语言，可根据用户语言偏好返回对应语言的消息。

## 接口列表

---

### 接口 1：刷新国际化资源

#### 功能描述
刷新系统内的国际化资源缓存（MessageSource），使最新的资源变更立即生效，无需重启应用。该接口主要用于在修改国际化资源文件后，使变更立即生效。

#### 请求方式
POST

#### 请求路径
`/system/i18n/refresh`

#### 权限要求
- `system:i18n:refresh`

#### 请求参数
无

#### 请求示例
```bash
curl -X POST 'http://localhost:8080/system/i18n/refresh' \
  -H 'Authorization: Bearer {token}'
```

#### 响应数据结构
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，500 失败） |
| msg | String | 提示信息 |
| data | Object | 数据对象（通常为 null） |

#### 响应示例

**成功响应：**
```json
{
  "code": 200,
  "msg": "国际化资源刷新成功",
  "data": null
}
```

**失败响应：**
```json
{
  "code": 500,
  "msg": "国际化资源刷新失败",
  "data": null
}
```

**不支持动态刷新：**
```json
{
  "code": 500,
  "msg": "当前 MessageSource 不支持动态刷新",
  "data": null
}
```

#### 错误码说明
| 错误码 | 说明 |
|--------|------|
| 200 | 刷新成功 |
| 500 | 刷新失败或 MessageSource 不支持动态刷新 |

---

### 接口 2：获取当前语言偏好

#### 功能描述
获取当前登录用户的语言偏好信息，包括语言代码、语言名称和国家名称。该接口用于前端初始化时获取用户的语言设置。

#### 请求方式
GET

#### 请求路径
`/system/i18n/currentLocale`

#### 权限要求
- `system:i18n:query`

#### 请求参数
无

#### 请求示例
```bash
curl -X GET 'http://localhost:8080/system/i18n/currentLocale' \
  -H 'Authorization: Bearer {token}'
```

#### 响应数据结构
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，500 失败） |
| msg | String | 提示信息 |
| data | Object | 语言偏好信息 |
| data.langCode | String | 语言代码（如 zh_CN、en_US） |
| data.language | String | 语言名称（如 中文、English） |
| data.country | String | 国家名称（如 中国、United States） |

#### 响应示例

**成功响应（中文）：**
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "langCode": "zh_CN",
    "language": "中文",
    "country": "中国"
  }
}
```

**成功响应（英文）：**
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "langCode": "en_US",
    "language": "English",
    "country": "United States"
  }
}
```

**失败响应：**
```json
{
  "code": 500,
  "msg": "未找到用户信息",
  "data": null
}
```

#### 错误码说明
| 错误码 | 说明 |
|--------|------|
| 200 | 获取成功 |
| 500 | 获取失败或未找到用户信息 |

---

### 接口 3：更新用户语言偏好

#### 功能描述
更新当前登录用户的语言偏好设置，将语言偏好持久化到数据库（sys_user 表的 lang_code 字段）。更新后，系统将根据新的语言偏好返回对应语言的消息。

#### 请求方式
PUT

#### 请求路径
`/system/i18n/updateLocale`

#### 权限要求
- `system:i18n:update`

#### 请求参数
| 参数名 | 类型 | 必选 | 说明 |
|--------|------|------|------|
| langCode | String | 是 | 目标语言代码（支持 zh_CN、en_US） |

#### 请求示例
```bash
curl -X PUT 'http://localhost:8080/system/i18n/updateLocale' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "langCode": "en_US"
  }'
```

#### 响应数据结构
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，400/500 失败） |
| msg | String | 提示信息 |
| data | Object | 数据对象（通常为 null） |

#### 响应示例

**成功响应：**
```json
{
  "code": 200,
  "msg": "语言偏好更新成功",
  "data": null
}
```

**失败响应（不支持的语言代码）：**
```json
{
  "code": 400,
  "msg": "不支持的语言代码",
  "data": null
}
```

**失败响应（未找到用户信息）：**
```json
{
  "code": 500,
  "msg": "未找到用户信息",
  "data": null
}
```

#### 错误码说明
| 错误码 | 说明 |
|--------|------|
| 200 | 更新成功 |
| 400 | 不支持的语言代码 |
| 500 | 更新失败或未找到用户信息 |

#### 业务规则
1. 支持的语言代码：zh_CN（简体中文）、en_US（美式英语）
2. 语言代码不能为空
3. 更新后，用户需要重新登录或刷新页面才能看到语言切换效果
4. 语言偏好保存在 sys_user 表的 lang_code 字段

---

## 国际化资源说明

### 资源文件位置
国际化资源文件位于：`datai-admin/src/main/resources/i18n/`

### 资源文件列表
- `messages.properties` - 默认资源（中文）
- `messages_en_US.properties` - 英文资源

### 资源命名规范
- 错误消息：error.{module}.{specific}
- 验证消息：validation.{field}.{rule}
- 日志消息：log.{module}.{action}
- 通知消息：notification.{type}.{template}

### 资源示例

**错误消息（messages.properties）：**
```properties
error.user.not.found=用户不存在
error.user.password.incorrect=密码错误
error.user.permission.denied=权限不足
```

**错误消息（messages_en_US.properties）：**
```properties
error.user.not.found=User not found
error.user.password.incorrect=Incorrect password
error.user.permission.denied=Permission denied
```

**验证消息（messages.properties）：**
```properties
validation.username.required=用户名不能为空
validation.username.length=用户名长度必须在{min}到{max}之间
validation.email.format=邮箱格式不正确
```

**验证消息（messages_en_US.properties）：**
```properties
validation.username.required=Username is required
validation.username.length=Username length must be between {min} and {max}
validation.email.format=Invalid email format
```

**日志消息（messages.properties）：**
```properties
log.user.login.success=用户登录成功
log.user.logout.success=用户登出成功
log.user.update.success=用户信息更新成功
```

**日志消息（messages_en_US.properties）：**
```properties
log.user.login.success=User logged in successfully
log.user.logout.success=User logged out successfully
log.user.update.success=User information updated successfully
```

**通知消息（messages.properties）：**
```properties
notification.email.register.subject=注册成功
notification.email.register.content=欢迎注册{appName}，您的账号已创建成功
notification.sms.verify.code=您的验证码是{code}，有效期{minutes}分钟
notification.platform.system=系统通知
```

**通知消息（messages_en_US.properties）：**
```properties
notification.email.register.subject=Registration Successful
notification.email.register.content=Welcome to {appName}, your account has been created successfully
notification.sms.verify.code=Your verification code is {code}, valid for {minutes} minutes
notification.platform.system=System Notification
```

---

## 语言偏好优先级

系统按以下优先级获取语言偏好：
1. **用户登录信息**（sys_user.lang_code）- 最高优先级
2. **请求参数**（?lang=zh_CN）
3. **请求头**（Accept-Language: zh-CN）
4. **系统默认语言**（Constants.DEFAULT_LOCALE = Locale.SIMPLIFIED_CHINESE）- 最低优先级

---

## 国际化消息获取流程

### 错误消息国际化
```
1. 捕获异常（ServiceException、RuntimeException 等）
2. 获取错误码（ServiceException.code）
3. 根据错误码查找对应的国际化资源键（ErrorCode 枚举）
4. 使用 MessageUtils 获取对应语言的错误消息
5. 返回国际化的错误消息
```

### 日志消息国际化
```
1. 拦截方法调用（LogAspect）
2. 获取 @Log 注解的 title 属性
3. 判断 title 是否为国际化资源键（以 log. 开头）
4. 使用 MessageUtils 获取对应语言的日志消息
5. 记录国际化的日志消息
```

### 验证消息国际化
```
1. 执行参数校验（Spring Validation）
2. 捕获校验异常（MethodArgumentNotValidException 等）
3. 使用 MessageUtils 获取对应语言的验证消息
4. 返回国际化的验证消息
```

### 通知消息国际化
```
1. 准备发送通知
2. 获取接收者的语言偏好（从 sys_user 表）
3. 使用 MessageUtils 获取对应语言的通知消息
4. 发送国际化的通知消息
```

---

## 注意事项

1. **资源刷新**：修改国际化资源文件后，需要调用刷新接口使变更生效
2. **语言代码**：使用标准的语言代码格式（如 zh_CN、en_US）
3. **参数占位符**：资源消息支持参数占位符（如 {appName}、{code}），使用 MessageUtils 传入参数值
4. **资源缺失**：如果某个语言的资源缺失，系统会返回默认语言（中文）的资源
5. **缓存策略**：国际化资源默认缓存 3600 秒，可通过配置调整
6. **权限控制**：所有接口都需要相应的权限才能访问
7. **用户登录**：获取和更新语言偏好需要用户已登录

---

## 相关文档

- [需求文档](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/requirements/2026-01-21-002-02-后端国际化需求.md)
- [设计文档](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/design/2026-01-21-002-02-后端国际化设计.md)
- [实现文档](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/implementation/2026-01-25-002-02-implementation-后端国际化功能.md)
- [通用国际化接口](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/api-docs/common/2026-01-26-002-01-api-通用国际化.md)