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)
|