111 lines
3.8 KiB
Markdown
111 lines
3.8 KiB
Markdown
# API 文档：格式化日期接口
|
||
|
||
## 元数据
|
||
- **需求编号**：2026-01-21-002-06-05
|
||
- **创建时间**：2026-01-26
|
||
- **创建人**：SSOT 架构师
|
||
- **父需求**：2026-01-21-002-06-日期格式化需求
|
||
|
||
## 接口概述
|
||
根据用户日期格式偏好、时区偏好和语言偏好格式化日期，返回格式化后的日期字符串。支持自定义日期格式，包括日期格式、时区转换、多语言本地化等。
|
||
|
||
## 接口详情
|
||
|
||
### 基本信息
|
||
- **接口名称**：格式化日期
|
||
- **接口描述**：根据用户日期格式偏好、时区偏好和语言偏好格式化日期
|
||
- **请求方式**：POST
|
||
- **请求路径**：`/system/dateFormat/format`
|
||
- **权限要求**：无（需要登录）
|
||
|
||
### 请求参数
|
||
| 参数名 | 类型 | 必选 | 说明 |
|
||
|--------|------|------|------|
|
||
| dateTime | String | 是 | 日期时间（ISO 8601 格式，如 2026-01-26T10:30:00Z） |
|
||
| dateFormat | String | 否 | 日期格式代码（如 yyyy-MM-dd），不传则使用用户日期格式偏好 |
|
||
| dateFormatPattern | String | 否 | 自定义日期格式模式（如 yyyy年MM月dd日），不传则使用日期格式默认模式 |
|
||
| timeZone | String | 否 | 时区（如 Asia/Shanghai），不传则使用用户时区偏好 |
|
||
| locale | String | 否 | 语言环境（如 zh_CN、en_US），不传则使用用户语言偏好 |
|
||
| includeTime | Boolean | 否 | 是否包含时间（默认 false） |
|
||
|
||
### 请求示例
|
||
```bash
|
||
curl -X POST 'http://localhost:8080/system/dateFormat/format' \
|
||
-H 'Authorization: Bearer {token}' \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{
|
||
"dateTime": "2026-01-26T10:30:00Z",
|
||
"dateFormat": "yyyy-MM-dd",
|
||
"dateFormatPattern": "yyyy年MM月dd日",
|
||
"timeZone": "Asia/Shanghai",
|
||
"locale": "zh_CN",
|
||
"includeTime": true
|
||
}'
|
||
```
|
||
|
||
### 响应数据结构
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码（200 成功，400/500 失败） |
|
||
| msg | String | 提示信息 |
|
||
| data | Object | 格式化结果 |
|
||
| data.formattedDateTime | String | 格式化后的日期时间（如 2026年01月26日 18:30:00） |
|
||
| data.dateFormat | String | 日期格式代码（如 yyyy-MM-dd） |
|
||
| data.dateFormatPattern | String | 日期格式模式（如 yyyy年MM月dd日） |
|
||
| data.timeZone | String | 时区（如 Asia/Shanghai） |
|
||
| data.locale | String | 语言环境（如 zh_CN） |
|
||
| data.includeTime | Boolean | 是否包含时间 |
|
||
|
||
### 响应示例
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "格式化成功",
|
||
"data": {
|
||
"formattedDateTime": "2026年01月26日 18:30:00",
|
||
"dateFormat": "yyyy-MM-dd",
|
||
"dateFormatPattern": "yyyy年MM月dd日",
|
||
"timeZone": "Asia/Shanghai",
|
||
"locale": "zh_CN",
|
||
"includeTime": true
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败响应（无效的日期时间）：**
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"msg": "无效的日期时间",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**失败响应（无效的日期格式代码）：**
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"msg": "无效的日期格式代码",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 业务规则
|
||
1. 如果未指定日期格式，使用用户日期格式偏好
|
||
2. 如果未指定日期格式模式，使用日期格式默认模式
|
||
3. 如果未指定时区，使用用户时区偏好
|
||
4. 如果未指定语言环境，使用用户语言偏好
|
||
5. 自动将 UTC 时间转换为用户时区
|
||
6. 根据用户语言偏好本地化日期（如星期几、月份名称）
|
||
7. 日期格式化时间 < 10ms
|
||
|
||
### 性能要求
|
||
- **响应时间**：< 10ms
|
||
- **格式化精度**：支持纳秒级精度
|
||
|
||
### 相关文档
|
||
- [需求文档](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)
|