# API 文档：日期格式化功能

## 元数据
- API 文档编号：2026-01-25-002-06-api
- 需求编号：2026-01-21-002-06
- 功能名称：日期格式化功能
- 版本：3.8.5
- 发布日期：2026-01-25
- 状态：已完成
- 阶段：阶段 9：复盘与接口

## API 概述

日期格式化功能提供了用户日期格式偏好管理和系统默认日期格式查询的 API 接口，支持用户设置和切换日期格式偏好，获取系统默认日期格式和常用日期格式列表。

## API 列表

### 1. 获取当前用户日期格式偏好

#### 接口信息
- **接口路径**：/system/user/dateFormat
- **请求方法**：GET
- **接口描述**：获取当前用户日期格式偏好
- **权限要求**：需要登录
- **接口分类**：用户管理

#### 请求参数
无

#### 响应示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "userId": 1,
    "dateFormat": "ISO_8601",
    "dateFormatPattern": null
  }
}
```

#### 响应字段说明
| 字段名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 响应码，200 表示成功 |
| msg | String | 响应消息 |
| data | Object | 响应数据 |
| data.userId | Long | 用户 ID |
| data.dateFormat | String | 日期格式模式（ISO_8601、US、EU、CN、JP、KR、SHORT、LONG、CUSTOM） |
| data.dateFormatPattern | String | 自定义日期格式（当 dateFormat 为 CUSTOM 时有效） |

#### 错误响应
```json
{
  "code": 401,
  "msg": "用户未登录"
}
```

### 2. 切换用户日期格式偏好

#### 接口信息
- **接口路径**：/system/user/switchDateFormat
- **请求方法**：POST
- **接口描述**：切换用户日期格式偏好
- **权限要求**：需要登录
- **接口分类**：用户管理

#### 请求参数
```json
{
  "dateFormat": "ISO_8601",
  "dateFormatPattern": null
}
```

#### 请求字段说明
| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| dateFormat | String | 是 | 日期格式模式（ISO_8601、US、EU、CN、JP、KR、SHORT、LONG、CUSTOM） |
| dateFormatPattern | String | 条件必填 | 自定义日期格式（当 dateFormat 为 CUSTOM 时必填） |

#### 响应示例
```json
{
  "code": 200,
  "msg": "操作成功"
}
```

#### 错误响应
```json
{
  "code": 500,
  "msg": "日期格式模式不能为空"
}
```

```json
{
  "code": 500,
  "msg": "自定义日期格式不能为空"
}
```

### 3. 获取系统默认日期格式

#### 接口信息
- **接口路径**：/system/config/defaultDateFormat
- **请求方法**：GET
- **接口描述**：获取系统默认日期格式
- **权限要求**：需要登录
- **接口分类**：配置管理

#### 请求参数
无

#### 响应示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "dateFormat": "yyyy-MM-dd",
    "dateTimeFormat": "yyyy-MM-dd HH:mm:ss"
  }
}
```

#### 响应字段说明
| 字段名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 响应码，200 表示成功 |
| msg | String | 响应消息 |
| data | Object | 响应数据 |
| data.dateFormat | String | 系统默认日期格式 |
| data.dateTimeFormat | String | 系统默认日期时间格式 |

#### 错误响应
```json
{
  "code": 500,
  "msg": "获取系统默认日期格式失败"
}
```

### 4. 获取常用日期格式列表

#### 接口信息
- **接口路径**：/system/config/commonDateFormats
- **请求方法**：GET
- **接口描述**：获取常用日期格式列表
- **权限要求**：需要登录
- **接口分类**：配置管理

#### 请求参数
无

#### 响应示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "dateFormats": {
      "ISO_8601": "yyyy-MM-dd",
      "US": "MM/dd/yyyy",
      "EU": "dd/MM/yyyy",
      "CN": "yyyy年MM月dd日",
      "JP": "yyyy/MM/dd",
      "KR": "yyyy. MM. dd.",
      "SHORT": "yy/MM/dd"
    },
    "dateTimeFormats": {
      "ISO_8601": "yyyy-MM-dd HH:mm:ss",
      "US": "MM/dd/yyyy HH:mm:ss",
      "EU": "dd/MM/yyyy HH:mm:ss",
      "CN": "yyyy年MM月dd日 HH:mm:ss",
      "JP": "yyyy/MM/dd HH:mm:ss",
      "KR": "yyyy. MM. dd. HH:mm:ss",
      "SHORT": "yy/MM/dd HH:mm"
    }
  }
}
```

#### 响应字段说明
| 字段名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 响应码，200 表示成功 |
| msg | String | 响应消息 |
| data | Object | 响应数据 |
| data.dateFormats | Object | 常用日期格式列表 |
| data.dateTimeFormats | Object | 常用日期时间格式列表 |

#### 日期格式说明
| 格式代码 | 日期格式 | 日期时间格式 | 说明 |
|---------|---------|-------------|------|
| ISO_8601 | yyyy-MM-dd | yyyy-MM-dd HH:mm:ss | ISO 8601 标准格式 |
| US | MM/dd/yyyy | MM/dd/yyyy HH:mm:ss | 美国格式 |
| EU | dd/MM/yyyy | dd/MM/yyyy HH:mm:ss | 欧洲格式 |
| CN | yyyy年MM月dd日 | yyyy年MM月dd日 HH:mm:ss | 中国格式 |
| JP | yyyy/MM/dd | yyyy/MM/dd HH:mm:ss | 日本格式 |
| KR | yyyy. MM. dd. | yyyy. MM. dd. HH:mm:ss | 韩国格式 |
| SHORT | yy/MM/dd | yy/MM/dd HH:mm | 短格式 |
| LONG | yyyy年MM月dd日 EEEE | yyyy年MM月dd日 EEEE HH:mm:ss | 长格式 |
| CUSTOM | 自定义 | 自定义 | 自定义格式 |

#### 错误响应
```json
{
  "code": 500,
  "msg": "获取常用日期格式列表失败"
}
```

## 使用示例

### 示例 1：获取当前用户日期格式偏好

#### 请求
```http
GET /system/user/dateFormat
Authorization: Bearer {token}
```

#### 响应
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "userId": 1,
    "dateFormat": "ISO_8601",
    "dateFormatPattern": null
  }
}
```

### 示例 2：切换用户日期格式偏好为美国格式

#### 请求
```http
POST /system/user/switchDateFormat
Authorization: Bearer {token}
Content-Type: application/json

{
  "dateFormat": "US",
  "dateFormatPattern": null
}
```

#### 响应
```json
{
  "code": 200,
  "msg": "操作成功"
}
```

### 示例 3：切换用户日期格式偏好为自定义格式

#### 请求
```http
POST /system/user/switchDateFormat
Authorization: Bearer {token}
Content-Type: application/json

{
  "dateFormat": "CUSTOM",
  "dateFormatPattern": "yyyy/MM/dd"
}
```

#### 响应
```json
{
  "code": 200,
  "msg": "操作成功"
}
```

### 示例 4：获取系统默认日期格式

#### 请求
```http
GET /system/config/defaultDateFormat
Authorization: Bearer {token}
```

#### 响应
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "dateFormat": "yyyy-MM-dd",
    "dateTimeFormat": "yyyy-MM-dd HH:mm:ss"
  }
}
```

### 示例 5：获取常用日期格式列表

#### 请求
```http
GET /system/config/commonDateFormats
Authorization: Bearer {token}
```

#### 响应
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "dateFormats": {
      "ISO_8601": "yyyy-MM-dd",
      "US": "MM/dd/yyyy",
      "EU": "dd/MM/yyyy",
      "CN": "yyyy年MM月dd日",
      "JP": "yyyy/MM/dd",
      "KR": "yyyy. MM. dd.",
      "SHORT": "yy/MM/dd"
    },
    "dateTimeFormats": {
      "ISO_8601": "yyyy-MM-dd HH:mm:ss",
      "US": "MM/dd/yyyy HH:mm:ss",
      "EU": "dd/MM/yyyy HH:mm:ss",
      "CN": "yyyy年MM月dd日 HH:mm:ss",
      "JP": "yyyy/MM/dd HH:mm:ss",
      "KR": "yyyy. MM. dd. HH:mm:ss",
      "SHORT": "yy/MM/dd HH:mm"
    }
  }
}
```

## 注意事项

### 1. 日期格式模式
- 日期格式模式必须是预定义的格式之一（ISO_8601、US、EU、CN、JP、KR、SHORT、LONG、CUSTOM）
- 当日期格式模式为 CUSTOM 时，必须提供自定义日期格式
- 自定义日期格式必须符合 Java DateTimeFormatter 的格式规范

### 2. 缓存机制
- 用户日期格式偏好使用 Redis 缓存，TTL 为 24 小时
- 用户切换日期格式偏好时，缓存会立即清除
- 获取用户日期格式偏好时，会优先从缓存中读取

### 3. 权限控制
- 所有接口都需要登录
- 用户只能设置和获取自己的日期格式偏好
- 系统默认日期格式和常用日期格式列表对所有登录用户可见

### 4. 错误处理
- 日期格式模式不能为空时，返回错误提示
- 自定义日期格式不能为空时（当 dateFormat 为 CUSTOM 时），返回错误提示
- 用户未登录时，返回 401 错误码

### 5. 时区转换
- 日期格式化会结合时区转换功能，先进行时区转换，再进行日期格式化
- 时区转换切面（TimeZoneConvertAspect）的执行顺序优先于日期格式化切面（DateFormatAspect）

### 6. 多语言支持
- 日期格式化支持多语言日期显示（星期几、月份名称的本地化）
- 根据用户语言偏好自动选择语言

## 相关文档

- [需求文档](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/requirements/2026-01-21-002-06-日期格式化需求.md)
- [设计文档](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/design/2026-01-21-002-06-日期格式化设计.md)
- [架构决策记录](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/decisions/adr/2026-01-25-002-06-ADR-日期格式化技术选型.md)
- [SQL 脚本](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/sql/2026-01-25-002-06-日期格式化.sql)
- [提示词文档](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/prompts/2026-01-25-002-06-prompt-日期格式化功能.md)
- [会话记录](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/sessions/2026-01-25-002-06-session.md)
- [变更日志](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/changelog/2026-01-25-002-06-changelog.md)
- [复盘文档](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/retros/2026-01-25-002-06-retro.md)

## 更新记录

| 版本 | 日期 | 更新内容 | 更新人 |
|------|------|---------|--------|
| 3.8.5 | 2026-01-25 | 初始版本 | SSOT 架构师 |