# API 文档：数据库国际化功能

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

## API 概述
数据库国际化功能 API 提供了语言切换、语言偏好管理、国际化资源刷新等功能，支持用户在运行时动态切换语言，并自动刷新相关缓存。API 遵循 RESTful 规范，使用标准的 HTTP 方法（GET、POST、PUT）进行数据交互。

## 接口列表

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

#### 功能描述
刷新国际化资源，清除 MessageSource 的缓存，强制重新加载国际化资源文件。

#### 请求方式
POST

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

#### 权限要求
- `system:i18n:refresh` - 国际化资源刷新权限

#### 请求参数
无

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "国际化资源刷新成功"
}
```

#### 失败示例
```json
{
  "code": 500,
  "msg": "当前 MessageSource 不支持动态刷新"
}
```

```json
{
  "code": 500,
  "msg": "国际化资源刷新失败"
}
```

---

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

#### 功能描述
获取当前用户的语言偏好，包括语言代码、语言名称、国家名称等信息。

#### 请求方式
GET

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

#### 权限要求
- `system:i18n:query` - 国际化查询权限

#### 请求参数
无

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| 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": "未找到用户信息"
}
```

---

### 接口 3：切换语言

#### 功能描述
切换当前用户的语言偏好，更新用户的 lang_code 字段，刷新 Token，清除用户缓存，强制重新加载数据。

#### 请求方式
POST

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

#### 权限要求
- `system:i18n:switch` - 语言切换权限

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| langCode | String | 是 | 语言代码，支持 zh_CN 或 en_US |

#### 请求示例
```json
{
  "langCode": "en_US"
}
```

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "语言切换成功"
}
```

#### 失败示例
```json
{
  "code": 500,
  "msg": "不支持的语言代码"
}
```

```json
{
  "code": 500,
  "msg": "未找到用户信息"
}
```

```json
{
  "code": 500,
  "msg": "语言切换失败"
}
```

---

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

#### 功能描述
更新当前用户的语言偏好，更新用户的 lang_code 字段，但不刷新 Token 和清除缓存。

#### 请求方式
PUT

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

#### 权限要求
- `system:i18n:update` - 语言偏好更新权限

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| langCode | String | 是 | 语言代码，支持 zh_CN 或 en_US |

#### 请求示例
```json
{
  "langCode": "en_US"
}
```

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "语言偏好更新成功"
}
```

#### 失败示例
```json
{
  "code": 500,
  "msg": "不支持的语言代码"
}
```

```json
{
  "code": 500,
  "msg": "未找到用户信息"
}
```

```json
{
  "code": 500,
  "msg": "更新语言偏好失败"
}
```

---

## 错误码

| 错误码 | 说明 | 处理建议 |
|--------|------|---------|
| 200 | 操作成功 | 无 |
| 400 | 请求参数错误 | 检查请求参数是否符合要求 |
| 401 | 未授权 | 检查用户是否已登录 |
| 403 | 无权限 | 检查用户是否有相应的权限 |
| 500 | 不支持的语言代码 | 检查 langCode 是否为 zh_CN 或 en_US |
| 501 | 未找到用户信息 | 检查用户是否已登录 |
| 502 | 当前 MessageSource 不支持动态刷新 | 检查 MessageSource 配置 |
| 503 | 国际化资源刷新失败 | 检查国际化资源文件是否存在 |
| 504 | 语言切换失败 | 检查用户信息和数据库连接 |
| 505 | 更新语言偏好失败 | 检查用户信息和数据库连接 |

## 相关文档
- [需求文档](../requirements/2026-01-21-002-03-数据库国际化需求.md)
- [设计文档](../design/2026-01-21-002-03-数据库国际化设计.md)
- [架构决策记录](../decisions/adr/2026-01-25-002-03-ADR-数据库国际化架构决策.md)
- [参考代码文档](../reference-code/2026-01-25-002-03-code-数据库国际化功能.md)
- [实施方案文档](../implementation/2026-01-25-002-03-implementation-数据库国际化功能.md)
- [复盘文档](../retros/2026-01-25-002-03-retro.md)
- [变更日志](../changelog/2026-01-25-002-03-changelog.md)