111 lines
2.9 KiB
Markdown
111 lines
2.9 KiB
Markdown
|
# API 文档：新增语言接口
|
|||
|
|
|
|||
|
|
## 元数据
|
|||
|
|
- **需求编号**：2026-01-26-002-08-03
|
|||
|
|
- **创建时间**：2026-01-26
|
|||
|
|
- **创建人**：SSOT 架构师
|
|||
|
|
- **父需求**：2026-01-26-002-08-语言管理功能
|
|||
|
|
- **状态**：已完成
|
|||
|
|
|
|||
|
|
## 功能概述
|
|||
|
|
新增一种系统支持的语言。
|
|||
|
|
|
|||
|
|
## 接口信息
|
|||
|
|
|
|||
|
|
### 基本信息
|
|||
|
|
- **接口名称**：新增语言
|
|||
|
|
- **接口功能**：添加新的语言到系统
|
|||
|
|
- **请求方式**：POST
|
|||
|
|
- **请求路径**：`/system/language`
|
|||
|
|
- **权限要求**：`system:language:add`
|
|||
|
|
|
|||
|
|
### 请求参数
|
|||
|
|
|
|||
|
|
| 参数名 | 类型 | 必选 | 说明 | 示例值 |
|
|||
|
|
|--------|------|------|------|--------|
|
|||
|
|
| langCode | String | 是 | 语言代码（如 zh-CN） | ja-JP |
|
|||
|
|
| langName | String | 是 | 语言名称 | 日语 |
|
|||
|
|
| langNameEn | String | 是 | 语言英文名称 | Japanese |
|
|||
|
|
| sortOrder | Integer | 否 | 排序 | 3 |
|
|||
|
|
| status | String | 否 | 状态（0正常 1停用） | 0 |
|
|||
|
|
|
|||
|
|
### 响应参数
|
|||
|
|
|
|||
|
|
| 参数名 | 类型 | 说明 |
|
|||
|
|
|--------|------|------|
|
|||
|
|
| code | Integer | 状态码（200 成功） |
|
|||
|
|
| msg | String | 提示信息 |
|
|||
|
|
|
|||
|
|
### 请求示例
|
|||
|
|
|
|||
|
|
```http
|
|||
|
|
POST /system/language
|
|||
|
|
Content-Type: application/json
|
|||
|
|
|
|||
|
|
{
|
|||
|
|
"langCode": "ja-JP",
|
|||
|
|
"langName": "日语",
|
|||
|
|
"langNameEn": "Japanese",
|
|||
|
|
"sortOrder": 3,
|
|||
|
|
"status": "0"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 响应示例
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"msg": "新增成功"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 错误码
|
|||
|
|
|
|||
|
|
| 错误码 | 说明 | 处理建议 |
|
|||
|
|
|--------|------|----------|
|
|||
|
|
| 400 | 请求参数错误 | 检查请求参数是否正确 |
|
|||
|
|
| 401 | 未登录或登录已过期 | 重新登录 |
|
|||
|
|
| 403 | 无权限访问 | 联系管理员分配权限 |
|
|||
|
|
| 409 | 语言代码已存在 | 使用不同的语言代码 |
|
|||
|
|
| 500 | 服务器内部错误 | 联系技术支持 |
|
|||
|
|
|
|||
|
|
## 业务规则
|
|||
|
|
|
|||
|
|
1. **唯一性规则**：
|
|||
|
|
- 语言代码（langCode）必须唯一
|
|||
|
|
- 不能添加已存在的语言代码
|
|||
|
|
|
|||
|
|
2. **必填规则**：
|
|||
|
|
- 语言代码（langCode）为必填项
|
|||
|
|
- 语言名称（langName）为必填项
|
|||
|
|
- 语言英文名称（langNameEn）为必填项
|
|||
|
|
|
|||
|
|
3. **默认值规则**：
|
|||
|
|
- 排序字段（sortOrder）默认为 0
|
|||
|
|
- 状态（status）默认为 0（正常）
|
|||
|
|
|
|||
|
|
4. **数据权限**：
|
|||
|
|
- 需要登录用户
|
|||
|
|
- 需要具备 `system:language:add` 权限
|
|||
|
|
|
|||
|
|
5. **新增后处理**：
|
|||
|
|
- 清除语言列表缓存
|
|||
|
|
- 清除语言详情缓存
|
|||
|
|
- 记录操作日志
|
|||
|
|
|
|||
|
|
## 缓存策略
|
|||
|
|
|
|||
|
|
- **缓存类型**：Redis
|
|||
|
|
- **缓存更新**：
|
|||
|
|
- 新增语言后清除所有语言相关的缓存
|
|||
|
|
- 清除缓存键模式：`system:language:*`
|
|||
|
|
|
|||
|
|
## 注意事项
|
|||
|
|
|
|||
|
|
1. 语言代码建议使用标准的 IETF BCP 47 格式（如 zh-CN、en-US、ja-JP）
|
|||
|
|
2. 新增的语言默认状态为正常（0），可在新增后通过修改状态接口停用
|
|||
|
|
3. 新增的语言不会自动成为默认语言，需要通过设置默认语言接口手动设置
|
|||
|
|
4. 新增语言后，需要为该语言准备对应的国际化资源文件
|
|||
|
|
5. 建议在新增语言前确认系统是否已准备好该语言的翻译资源
|