88 lines
2.3 KiB
Markdown
88 lines
2.3 KiB
Markdown
# API 文档：切换时区接口
|
||
|
||
## 元数据
|
||
- **需求编号**：2026-01-21-002-04-03
|
||
- **创建时间**：2026-01-26
|
||
- **创建人**：SSOT 架构师
|
||
- **父需求**：2026-01-21-002-04-时区国际化需求
|
||
|
||
## 接口概述
|
||
切换当前登录用户的时区偏好，更新用户时区设置，清除相关缓存，返回切换结果。时区切换后，前端需要刷新页面重新加载时间数据。
|
||
|
||
## 接口详情
|
||
|
||
### 基本信息
|
||
- **接口名称**：切换时区
|
||
- **接口描述**：切换当前登录用户的时区偏好
|
||
- **请求方式**：POST
|
||
- **请求路径**：`/system/timezone/switch`
|
||
- **权限要求**：无（需要登录）
|
||
|
||
### 请求参数
|
||
| 参数名 | 类型 | 必选 | 说明 |
|
||
|--------|------|------|------|
|
||
| timeZone | String | 是 | 时区ID（如 Asia/Shanghai、America/New_York） |
|
||
|
||
### 请求示例
|
||
```bash
|
||
curl -X POST 'http://localhost:8080/system/timezone/switch' \
|
||
-H 'Authorization: Bearer {token}' \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{
|
||
"timeZone": "America/New_York"
|
||
}'
|
||
```
|
||
|
||
### 响应数据结构
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码（200 成功，400/500 失败） |
|
||
| msg | String | 提示信息 |
|
||
| data | Object | 数据对象（通常为 null） |
|
||
|
||
### 响应示例
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "时区切换成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**失败响应（无效的时区ID）：**
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"msg": "无效的时区ID",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**失败响应（未找到用户信息）：**
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "未找到用户信息",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 业务规则
|
||
1. 验证时区ID的有效性
|
||
2. 更新用户时区偏好到数据库
|
||
3. 清除用户时区缓存
|
||
4. 清除相关数据缓存（如字典缓存、配置缓存等）
|
||
5. 时区切换后，前端需要刷新页面重新加载时间数据
|
||
6. 时区切换记录审计日志
|
||
7. 时区切换响应时间 < 500ms
|
||
|
||
### 性能要求
|
||
- **响应时间**：< 500ms
|
||
- **数据库更新时间**：< 100ms
|
||
|
||
### 相关文档
|
||
- [需求文档](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/requirements/2026-01-21-002-04-时区国际化需求.md)
|
||
- [设计文档](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/design/2026-01-21-002-04-时区国际化设计.md)
|