datai-vue/docs/api-docs/2026-01-26-002-03-api.md

# API 文档：前端国际化-动态资源

## 元数据
- **需求编号**：2026-01-26-002-03
- **需求名称**：前端国际化-动态资源
- **创建时间**：2026-01-26
- **创建人**：SSOT 架构师
- **状态**：已完成

## API 概述
本文档描述了前端国际化-动态资源功能涉及的 API 接口，包括查询语言列表、获取当前语言偏好、更新用户语言偏好、查询国际化资源列表等接口。这些接口用于实现前端与后端国际化接口的深度对接，包括动态获取系统支持的语言列表、登录后自动同步并应用用户的语言偏好、实现远程翻译资源的加载、合并与缓存策略，以及实现动态菜单国际化。

## 接口列表

### 接口 1：查询语言列表

#### 功能描述
查询系统支持的语言列表，用于动态生成语言选择器的下拉选项。

#### 请求方式
GET

#### 请求路径
`/system/language/list`

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| pageNum | Number | 否 | 页码，默认 1 |
| pageSize | Number | 否 | 每页条数，默认 10 |
| langCode | String | 否 | 语言代码（后端格式，如 zh_CN） |
| langName | String | 否 | 语言名称（如 简体中文） |
| status | String | 否 | 状态（0 正常，1 停用） |

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Number | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| rows | Array | 语言列表数据 |
| rows[].id | Number | 语言 ID |
| rows[].langCode | String | 语言代码（后端格式，如 zh_CN） |
| rows[].langName | String | 语言名称（如 简体中文） |
| rows[].status | String | 状态（0 正常，1 停用） |
| rows[].createTime | String | 创建时间 |
| rows[].updateTime | String | 更新时间 |
| total | Number | 总记录数 |

#### 成功示例

```json
{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": 1,
      "langCode": "zh_CN",
      "langName": "简体中文",
      "status": "0",
      "createTime": "2026-01-26 10:00:00",
      "updateTime": "2026-01-26 10:00:00"
    },
    {
      "id": 2,
      "langCode": "en_US",
      "langName": "English",
      "status": "0",
      "createTime": "2026-01-26 10:00:00",
      "updateTime": "2026-01-26 10:00:00"
    }
  ],
  "total": 2
}
```

#### 失败示例

```json
{
  "code": 500,
  "msg": "查询失败"
}
```

#### 错误码

| 错误码 | 说明 |
|--------|------|
| 500 | 查询失败 |

---

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

#### 功能描述
获取当前登录用户的语言偏好，用于登录后自动同步并应用用户的语言偏好。

#### 请求方式
GET

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

#### 请求参数
无

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Number | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 语言偏好数据 |
| data.langCode | String | 语言代码（后端格式，如 zh_CN） |

#### 成功示例

```json
{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "langCode": "zh_CN"
  }
}
```

#### 失败示例

```json
{
  "code": 500,
  "msg": "查询失败"
}
```

#### 错误码

| 错误码 | 说明 |
|--------|------|
| 401 | 用户未登录 |
| 500 | 查询失败 |

---

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

#### 功能描述
更新当前登录用户的语言偏好，用于用户切换语言时同步到后端。

#### 请求方式
PUT

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

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| langCode | String | 是 | 语言代码（后端格式，如 zh_CN） |

#### 请求示例

```json
{
  "langCode": "zh_CN"
}
```

#### 响应参数

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

#### 成功示例

```json
{
  "code": 200,
  "msg": "更新成功"
}
```

#### 失败示例

```json
{
  "code": 500,
  "msg": "更新失败"
}
```

#### 错误码

| 错误码 | 说明 |
|--------|------|
| 401 | 用户未登录 |
| 500 | 更新失败 |

---

### 接口 4：查询国际化资源列表

#### 功能描述
查询指定语言的国际化资源列表，用于远程加载翻译资源。

#### 请求方式
GET

#### 请求路径
`/system/i18nresource/list`

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| pageNum | Number | 否 | 页码，默认 1 |
| pageSize | Number | 否 | 每页条数，默认 10 |
| langCode | String | 否 | 语言代码（后端格式，如 zh_CN） |
| moduleName | String | 否 | 模块名称（如 common、layout、login） |
| resourceKey | String | 否 | 资源键（如 login.button.login） |
| resourceValue | String | 否 | 资源值（如 登录） |

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Number | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| rows | Array | 国际化资源列表数据 |
| rows[].id | Number | 资源 ID |
| rows[].langCode | String | 语言代码（后端格式，如 zh_CN） |
| rows[].moduleName | String | 模块名称（如 common、layout、login） |
| rows[].resourceKey | String | 资源键（如 login.button.login） |
| rows[].resourceValue | String | 资源值（如 登录） |
| rows[].createTime | String | 创建时间 |
| rows[].updateTime | String | 更新时间 |
| total | Number | 总记录数 |

#### 成功示例

```json
{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": 1,
      "langCode": "zh_CN",
      "moduleName": "common",
      "resourceKey": "common.ok",
      "resourceValue": "确定",
      "createTime": "2026-01-26 10:00:00",
      "updateTime": "2026-01-26 10:00:00"
    },
    {
      "id": 2,
      "langCode": "zh_CN",
      "moduleName": "login",
      "resourceKey": "login.button.login",
      "resourceValue": "登录",
      "createTime": "2026-01-26 10:00:00",
      "updateTime": "2026-01-26 10:00:00"
    }
  ],
  "total": 2
}
```

#### 失败示例

```json
{
  "code": 500,
  "msg": "查询失败"
}
```

#### 错误码

| 错误码 | 说明 |
|--------|------|
| 500 | 查询失败 |

---

## 错误码汇总

| 错误码 | 说明 | 处理建议 |
|--------|------|----------|
| 200 | 操作成功 | 无 |
| 401 | 用户未登录 | 跳转到登录页面 |
| 500 | 操作失败 | 显示错误提示，联系管理员 |

## 使用示例

### 示例 1：动态获取语言列表

```javascript
import { listLanguage } from '@/api/system/language'

async function loadLanguageList() {
  try {
    const response = await listLanguage({ status: '0' })
    const languageOptions = response.rows
      .filter(item => item.status === '0')
      .map(item => ({
        label: item.langName,
        value: item.langCode.replace('_', '-')
      }))
    console.log('语言列表：', languageOptions)
  } catch (error) {
    console.error('加载语言列表失败：', error)
  }
}
```

### 示例 2：获取用户语言偏好

```javascript
import { getCurrentLocale } from '@/api/system/language'
import { toFrontend } from '@/utils/langFormat'

async function syncUserLanguagePreference() {
  try {
    const response = await getCurrentLocale()
    const remoteLang = toFrontend(response.data.langCode)
    console.log('用户语言偏好：', remoteLang)
    // 应用用户语言偏好
    appStore.setLanguage(remoteLang)
  } catch (error) {
    console.error('获取用户语言偏好失败：', error)
  }
}
```

### 示例 3：更新用户语言偏好

```javascript
import { updateLocale } from '@/api/system/language'
import { toBackend } from '@/utils/langFormat'

async function updateUserLanguagePreference(lang) {
  try {
    await updateLocale({ langCode: toBackend(lang) })
    console.log('更新用户语言偏好成功')
  } catch (error) {
    console.error('更新用户语言偏好失败：', error)
  }
}
```

### 示例 4：加载远程翻译资源

```javascript
import { listI18nResource } from '@/api/system/language'

async function loadRemoteMessages(lang) {
  try {
    const response = await listI18nResource({
      pageNum: 1,
      pageSize: 9999,
      langCode: lang
    })
    const messages = transformToNestedObject(response.rows)
    console.log('远程翻译资源：', messages)
    return messages
  } catch (error) {
    console.error('加载远程翻译资源失败：', error)
    return {}
  }
}

function transformToNestedObject(rows) {
  const result = {}
  rows.forEach(row => {
    const keys = row.resourceKey.split('.')
    let current = result
    keys.forEach((key, index) => {
      if (index === keys.length - 1) {
        current[key] = row.resourceValue
      } else {
        if (!current[key]) {
          current[key] = {}
        }
        current = current[key]
      }
    })
  })
  return result
}
```

## 相关文档
- [需求文档](../requirements/2026-01-26-002-03-前端国际化-动态资源.md)
- [设计文档](../design/2026-01-26-002-03-前端国际化-动态资源-设计.md)
- [决策记录](../decisions/2026-01-26-002-03-ADR-前端国际化-动态资源实现策略决策.md)
- [提示词文档](../prompts/2026-01-26-002-03-prompt-前端国际化-动态资源.md)
- [变更日志](../changelog/2026-01-26-002-03-changelog.md)
- [复盘文档](../retros/2026-01-26-002-03-retro.md)