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