798 lines
23 KiB
Markdown
798 lines
23 KiB
Markdown
# API 文档：日期格式化接口
|
||
|
||
## 元数据
|
||
- **需求编号**：2026-01-21-002-06
|
||
- **创建时间**：2026-01-26
|
||
- **创建人**：SSOT 架构师
|
||
- **父需求**：2026-01-21-002-项目国际化需求
|
||
|
||
## API 概述
|
||
日期格式化接口提供了常用日期格式、日期时间格式化、短日期和长日期格式化、自动选择格式、自定义格式、时区转换、多语言日期显示等功能。通过 AOP 在 Service 层统一处理日期格式化，根据用户日期格式偏好、时区偏好和语言偏好自动格式化日期数据。
|
||
|
||
## 接口列表
|
||
|
||
---
|
||
|
||
### 接口 1：获取日期格式列表
|
||
|
||
#### 功能描述
|
||
获取系统支持的日期格式列表，包括日期格式代码、日期格式名称、日期格式模式等信息。
|
||
|
||
#### 请求方式
|
||
GET
|
||
|
||
#### 请求路径
|
||
`/system/dateFormat/list`
|
||
|
||
#### 权限要求
|
||
- 无（通常公开或需登录）
|
||
|
||
#### 请求参数
|
||
| 参数名 | 类型 | 必选 | 说明 |
|
||
|--------|------|------|------|
|
||
| formatCode | String | 否 | 日期格式代码（如 yyyy-MM-dd） |
|
||
| status | String | 否 | 状态（0正常 1停用） |
|
||
|
||
#### 请求示例
|
||
```bash
|
||
curl -X GET 'http://localhost:8080/system/dateFormat/list?status=0' \
|
||
-H 'Authorization: Bearer {token}'
|
||
```
|
||
|
||
#### 响应数据结构
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码（200 成功，500 失败） |
|
||
| msg | String | 提示信息 |
|
||
| data | Array | 日期格式列表 |
|
||
| data[].formatCode | String | 日期格式代码（如 yyyy-MM-dd） |
|
||
| data[].formatName | String | 日期格式名称（如 ISO 8601） |
|
||
| data[].formatNameEn | String | 日期格式英文名称（如 ISO 8601） |
|
||
| data[].formatPattern | String | 日期格式模式（如 yyyy-MM-dd） |
|
||
| data[].isDefault | Boolean | 是否默认格式 |
|
||
| data[].sortOrder | Integer | 排序 |
|
||
| data[].status | String | 状态（0正常 1停用） |
|
||
|
||
#### 响应示例
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": [
|
||
{
|
||
"formatCode": "yyyy-MM-dd",
|
||
"formatName": "ISO 8601",
|
||
"formatNameEn": "ISO 8601",
|
||
"formatPattern": "yyyy-MM-dd",
|
||
"isDefault": true,
|
||
"sortOrder": 1,
|
||
"status": "0"
|
||
},
|
||
{
|
||
"formatCode": "dd/MM/yyyy",
|
||
"formatName": "欧洲格式",
|
||
"formatNameEn": "European Format",
|
||
"formatPattern": "dd/MM/yyyy",
|
||
"isDefault": false,
|
||
"sortOrder": 2,
|
||
"status": "0"
|
||
},
|
||
{
|
||
"formatCode": "MM/dd/yyyy",
|
||
"formatName": "美国格式",
|
||
"formatNameEn": "US Format",
|
||
"formatPattern": "MM/dd/yyyy",
|
||
"isDefault": false,
|
||
"sortOrder": 3,
|
||
"status": "0"
|
||
},
|
||
{
|
||
"formatCode": "yyyy年MM月dd日",
|
||
"formatName": "中国格式",
|
||
"formatNameEn": "Chinese Format",
|
||
"formatPattern": "yyyy年MM月dd日",
|
||
"isDefault": false,
|
||
"sortOrder": 4,
|
||
"status": "0"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**失败响应：**
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "获取日期格式列表失败",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 错误码说明
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 获取成功 |
|
||
| 500 | 获取失败 |
|
||
|
||
#### 业务规则
|
||
1. 日期格式列表从数据库读取
|
||
2. 日期格式列表固定，后续不允许用户调整
|
||
3. 日期格式列表使用 Redis 缓存，缓存时间 24 小时
|
||
4. 返回的日期格式列表按排序字段排序
|
||
5. 只返回状态为正常（0）的日期格式
|
||
|
||
---
|
||
|
||
### 接口 2：获取当前用户日期格式偏好
|
||
|
||
#### 功能描述
|
||
获取当前登录用户的日期格式偏好，返回用户的日期格式代码、日期格式名称等信息。如果用户未设置日期格式，返回系统默认日期格式。
|
||
|
||
#### 请求方式
|
||
GET
|
||
|
||
#### 请求路径
|
||
`/system/user/dateFormat`
|
||
|
||
#### 权限要求
|
||
- 无（需要登录）
|
||
|
||
#### 请求参数
|
||
无
|
||
|
||
#### 请求示例
|
||
```bash
|
||
curl -X GET 'http://localhost:8080/system/user/dateFormat' \
|
||
-H 'Authorization: Bearer {token}'
|
||
```
|
||
|
||
#### 响应数据结构
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码（200 成功，500 失败） |
|
||
| msg | String | 提示信息 |
|
||
| data | Object | 日期格式信息 |
|
||
| data.dateFormat | String | 日期格式代码（如 yyyy-MM-dd） |
|
||
| data.dateFormatPattern | String | 日期格式模式（如 yyyy-MM-dd） |
|
||
| data.formatName | String | 日期格式名称（如 ISO 8601） |
|
||
| data.formatNameEn | String | 日期格式英文名称（如 ISO 8601） |
|
||
| data.isDefault | Boolean | 是否系统默认格式 |
|
||
|
||
#### 响应示例
|
||
|
||
**成功响应（用户已设置日期格式）：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"dateFormat": "yyyy-MM-dd",
|
||
"dateFormatPattern": "yyyy-MM-dd",
|
||
"formatName": "ISO 8601",
|
||
"formatNameEn": "ISO 8601",
|
||
"isDefault": false
|
||
}
|
||
}
|
||
```
|
||
|
||
**成功响应（用户未设置日期格式，返回系统默认格式）：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"dateFormat": "yyyy-MM-dd",
|
||
"dateFormatPattern": "yyyy-MM-dd",
|
||
"formatName": "ISO 8601",
|
||
"formatNameEn": "ISO 8601",
|
||
"isDefault": true
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败响应：**
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "获取当前用户日期格式偏好失败",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 错误码说明
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 获取成功 |
|
||
| 500 | 获取失败或未找到用户信息 |
|
||
|
||
#### 业务规则
|
||
1. 优先级：用户日期格式偏好 > 系统默认格式
|
||
2. 如果用户未设置日期格式，返回系统默认日期格式
|
||
3. 用户日期格式偏好使用 Redis 缓存，缓存时间 24 小时
|
||
4. 需要用户登录才能获取日期格式信息
|
||
|
||
---
|
||
|
||
### 接口 3：切换日期格式
|
||
|
||
#### 功能描述
|
||
切换当前登录用户的日期格式偏好，更新用户日期格式设置，清除相关缓存，返回切换结果。日期格式切换后，前端需要刷新页面重新加载日期数据。
|
||
|
||
#### 请求方式
|
||
POST
|
||
|
||
#### 请求路径
|
||
`/system/user/switchDateFormat`
|
||
|
||
#### 权限要求
|
||
- 无（需要登录）
|
||
|
||
#### 请求参数
|
||
| 参数名 | 类型 | 必选 | 说明 |
|
||
|--------|------|------|------|
|
||
| dateFormat | String | 是 | 日期格式代码（如 yyyy-MM-dd、dd/MM/yyyy） |
|
||
| dateFormatPattern | String | 否 | 自定义日期格式模式（如 yyyy年MM月dd日） |
|
||
|
||
#### 请求示例
|
||
```bash
|
||
curl -X POST 'http://localhost:8080/system/user/switchDateFormat' \
|
||
-H 'Authorization: Bearer {token}' \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{
|
||
"dateFormat": "dd/MM/yyyy"
|
||
}'
|
||
```
|
||
|
||
#### 响应数据结构
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码（200 成功，400/500 失败） |
|
||
| msg | String | 提示信息 |
|
||
| data | Object | 数据对象（通常为 null） |
|
||
|
||
#### 响应示例
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "日期格式切换成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**失败响应（无效的日期格式代码）：**
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"msg": "无效的日期格式代码",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**失败响应（未找到用户信息）：**
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "未找到用户信息",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 错误码说明
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 切换成功 |
|
||
| 400 | 无效的日期格式代码 |
|
||
| 500 | 切换失败或未找到用户信息 |
|
||
|
||
#### 业务规则
|
||
1. 验证日期格式代码的有效性
|
||
2. 更新用户日期格式偏好到数据库
|
||
3. 清除用户日期格式缓存
|
||
4. 清除相关数据缓存（如日期数据缓存等）
|
||
5. 日期格式切换后，前端需要刷新页面重新加载日期数据
|
||
6. 日期格式切换记录审计日志
|
||
7. 日期格式切换响应时间 < 500ms
|
||
|
||
---
|
||
|
||
### 接口 4：获取系统默认日期格式
|
||
|
||
#### 功能描述
|
||
获取系统默认日期格式配置，返回系统默认日期格式的详细信息。系统默认日期格式用于用户未设置日期格式时的回退格式。
|
||
|
||
#### 请求方式
|
||
GET
|
||
|
||
#### 请求路径
|
||
`/system/dateFormat/default`
|
||
|
||
#### 权限要求
|
||
- 无（通常公开或需登录）
|
||
|
||
#### 请求参数
|
||
无
|
||
|
||
#### 请求示例
|
||
```bash
|
||
curl -X GET 'http://localhost:8080/system/dateFormat/default' \
|
||
-H 'Authorization: Bearer {token}'
|
||
```
|
||
|
||
#### 响应数据结构
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码（200 成功，500 失败） |
|
||
| msg | String | 提示信息 |
|
||
| data | Object | 日期格式信息 |
|
||
| data.dateFormat | String | 日期格式代码（如 yyyy-MM-dd） |
|
||
| data.dateFormatPattern | String | 日期格式模式（如 yyyy-MM-dd） |
|
||
| data.formatName | String | 日期格式名称（如 ISO 8601） |
|
||
| data.formatNameEn | String | 日期格式英文名称（如 ISO 8601） |
|
||
|
||
#### 响应示例
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"dateFormat": "yyyy-MM-dd",
|
||
"dateFormatPattern": "yyyy-MM-dd",
|
||
"formatName": "ISO 8601",
|
||
"formatNameEn": "ISO 8601"
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败响应：**
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "获取默认日期格式失败",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 错误码说明
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 获取成功 |
|
||
| 500 | 获取失败或未找到默认日期格式 |
|
||
|
||
#### 业务规则
|
||
1. 系统必须有默认日期格式配置
|
||
2. 默认日期格式从配置文件读取
|
||
3. 默认日期格式使用 Redis 缓存，缓存时间 24 小时
|
||
4. 默认日期格式用于用户未设置日期格式时的回退格式
|
||
|
||
---
|
||
|
||
### 接口 5：格式化日期
|
||
|
||
#### 功能描述
|
||
根据用户日期格式偏好、时区偏好和语言偏好格式化日期，返回格式化后的日期字符串。支持自定义日期格式，包括日期格式、时区转换、多语言本地化等。
|
||
|
||
#### 请求方式
|
||
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
|
||
}
|
||
```
|
||
|
||
#### 错误码说明
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 格式化成功 |
|
||
| 400 | 无效的日期时间或日期格式代码 |
|
||
| 500 | 格式化失败 |
|
||
|
||
#### 业务规则
|
||
1. 如果未指定日期格式，使用用户日期格式偏好
|
||
2. 如果未指定日期格式模式，使用日期格式默认模式
|
||
3. 如果未指定时区，使用用户时区偏好
|
||
4. 如果未指定语言环境，使用用户语言偏好
|
||
5. 自动将 UTC 时间转换为用户时区
|
||
6. 根据用户语言偏好本地化日期（如星期几、月份名称）
|
||
7. 日期格式化时间 < 10ms
|
||
|
||
---
|
||
|
||
### 接口 6：刷新日期格式缓存
|
||
|
||
#### 功能描述
|
||
刷新日期格式缓存，清除所有日期格式相关的缓存数据，使最新的日期格式数据立即生效。
|
||
|
||
#### 请求方式
|
||
DELETE
|
||
|
||
#### 请求路径
|
||
`/system/dateFormat/refreshCache`
|
||
|
||
#### 权限要求
|
||
- `system:dateFormat:refresh`
|
||
|
||
#### 请求参数
|
||
无
|
||
|
||
#### 请求示例
|
||
```bash
|
||
curl -X DELETE 'http://localhost:8080/system/dateFormat/refreshCache' \
|
||
-H 'Authorization: Bearer {token}'
|
||
```
|
||
|
||
#### 响应数据结构
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码（200 成功，500 失败） |
|
||
| msg | String | 提示信息 |
|
||
| data | Object | 数据对象（通常为 null） |
|
||
|
||
#### 响应示例
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "日期格式缓存刷新成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**失败响应：**
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "日期格式缓存刷新失败",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
#### 错误码说明
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 刷新成功 |
|
||
| 500 | 刷新失败 |
|
||
|
||
#### 业务规则
|
||
1. 清除日期格式列表缓存（sys:dateFormat:list）
|
||
2. 清除用户日期格式缓存（user:dateFormat:*）
|
||
3. 刷新后，下次查询时重新加载日期格式数据
|
||
|
||
---
|
||
|
||
## 数据库表结构
|
||
|
||
### sys_date_format 表（日期格式配置表）
|
||
```sql
|
||
CREATE TABLE `sys_date_format` (
|
||
`id` bigint NOT NULL AUTO_INCREMENT COMMENT '日期格式ID',
|
||
`format_code` varchar(50) NOT NULL COMMENT '日期格式代码（如：yyyy-MM-dd）',
|
||
`format_name` varchar(50) NOT NULL COMMENT '日期格式名称（如：ISO 8601）',
|
||
`format_name_en` varchar(50) NOT NULL COMMENT '日期格式英文名称（如：ISO 8601）',
|
||
`format_pattern` varchar(100) NOT NULL COMMENT '日期格式模式（如：yyyy-MM-dd）',
|
||
`is_default` tinyint(1) DEFAULT '0' COMMENT '是否默认格式（0否 1是）',
|
||
`sort_order` int DEFAULT '0' COMMENT '排序',
|
||
`status` char(1) DEFAULT '0' COMMENT '状态（0正常 1停用）',
|
||
`create_by` varchar(64) DEFAULT '' COMMENT '创建者',
|
||
`create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||
`update_by` varchar(64) DEFAULT '' COMMENT '更新者',
|
||
`update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
|
||
`remark` varchar(500) DEFAULT NULL COMMENT '备注',
|
||
PRIMARY KEY (`id`),
|
||
UNIQUE KEY `uk_format_code` (`format_code`),
|
||
KEY `idx_status` (`status`),
|
||
KEY `idx_sort_order` (`sort_order`)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='日期格式配置表';
|
||
```
|
||
|
||
### sys_user 表修改（用户表）
|
||
```sql
|
||
ALTER TABLE `sys_user`
|
||
ADD COLUMN `date_format` varchar(50) DEFAULT NULL COMMENT '日期格式' AFTER `currency_code`,
|
||
ADD COLUMN `date_format_pattern` varchar(100) DEFAULT NULL COMMENT '日期格式模式' AFTER `date_format`;
|
||
```
|
||
|
||
---
|
||
|
||
## 常用日期格式列表
|
||
|
||
| 日期格式代码 | 日期格式名称 | 日期格式英文名称 | 日期格式模式 | 是否默认 |
|
||
|-------------|-------------|-----------------|-------------|---------|
|
||
| yyyy-MM-dd | ISO 8601 | ISO 8601 | yyyy-MM-dd | 是 |
|
||
| dd/MM/yyyy | 欧洲格式 | European Format | dd/MM/yyyy | 否 |
|
||
| MM/dd/yyyy | 美国格式 | US Format | MM/dd/yyyy | 否 |
|
||
| yyyy年MM月dd日 | 中国格式 | Chinese Format | yyyy年MM月dd日 | 否 |
|
||
|
||
---
|
||
|
||
## 日期时间格式列表
|
||
|
||
| 日期时间格式代码 | 日期时间格式名称 | 日期时间格式英文名称 | 日期时间格式模式 |
|
||
|-----------------|-----------------|---------------------|-----------------|
|
||
| yyyy-MM-dd HH:mm:ss | 短格式 | Short Format | yyyy-MM-dd HH:mm:ss |
|
||
| yyyy年MM月dd日 HH时mm分ss秒 | 长格式 | Long Format | yyyy年MM月dd日 HH时mm分ss秒 |
|
||
|
||
---
|
||
|
||
## 日期格式化说明
|
||
|
||
### 日期格式化流程
|
||
```
|
||
日期格式化
|
||
├─ 读取用户日期格式偏好（date_format）
|
||
├─ 读取用户时区偏好（time_zone）
|
||
├─ 读取用户语言偏好（lang_code）
|
||
├─ 读取系统默认日期格式配置
|
||
├─ 将 UTC 时间转换为用户时区
|
||
├─ 根据用户日期格式偏好格式化日期
|
||
├─ 根据用户语言偏好本地化日期
|
||
│ ├─ 星期几本地化（中文：星期一；英文：Monday）
|
||
│ └─ 月份名称本地化（中文：一月；英文：January）
|
||
└─ 返回格式化后的日期
|
||
```
|
||
|
||
### 日期格式化示例
|
||
```java
|
||
// 示例：格式化日期
|
||
String dateTimeStr = "2026-01-26T10:30:00Z";
|
||
String dateFormat = "yyyy年MM月dd日";
|
||
String timeZone = "Asia/Shanghai";
|
||
String locale = "zh_CN";
|
||
boolean includeTime = true;
|
||
|
||
// 解析日期时间
|
||
ZonedDateTime utcDateTime = ZonedDateTime.parse(dateTimeStr);
|
||
ZoneId userTimeZone = ZoneId.of(timeZone);
|
||
ZonedDateTime userDateTime = utcDateTime.withZoneSameInstant(userTimeZone);
|
||
|
||
// 格式化日期
|
||
DateTimeFormatter formatter = DateTimeFormatter.ofPattern(dateFormatPattern, Locale.forLanguageTag(locale));
|
||
String formattedDateTime = formatter.format(userDateTime);
|
||
|
||
// 结果：2026年01月26日
|
||
```
|
||
|
||
---
|
||
|
||
## 时区转换说明
|
||
|
||
### 时区转换流程
|
||
```
|
||
时区转换
|
||
├─ 读取用户时区偏好（time_zone）
|
||
├─ 读取系统默认时区配置
|
||
├─ 将 UTC 时间转换为用户时区
|
||
│ ├─ ZonedDateTime.parse(utcDateTime)
|
||
│ ├─ withZoneSameInstant(userTimeZone)
|
||
│ └─ 返回用户时区时间
|
||
└─ 返回转换后的时间
|
||
```
|
||
|
||
### 时区转换示例
|
||
```java
|
||
// 示例：时区转换
|
||
String utcDateTimeStr = "2026-01-26T10:30:00Z";
|
||
String userTimeZone = "Asia/Shanghai";
|
||
|
||
// 解析 UTC 时间
|
||
ZonedDateTime utcDateTime = ZonedDateTime.parse(utcDateTimeStr);
|
||
|
||
// 转换为用户时区
|
||
ZoneId timeZone = ZoneId.of(userTimeZone);
|
||
ZonedDateTime userDateTime = utcDateTime.withZoneSameInstant(timeZone);
|
||
|
||
// 结果：2026-01-26T18:30:00+08:00[Asia/Shanghai]
|
||
```
|
||
|
||
---
|
||
|
||
## 多语言本地化说明
|
||
|
||
### 多语言本地化流程
|
||
```
|
||
多语言本地化
|
||
├─ 读取用户语言偏好（lang_code）
|
||
├─ 读取系统默认语言配置
|
||
├─ 根据用户语言偏好本地化日期
|
||
│ ├─ 星期几本地化
|
||
│ │ ├─ 中文：星期一、星期二、...、星期日
|
||
│ │ └─ 英文：Monday、Tuesday、...、Sunday
|
||
│ └─ 月份名称本地化
|
||
│ ├─ 中文：一月、二月、...、十二月
|
||
│ └─ 英文：January、February、...、December
|
||
└─ 返回本地化后的日期
|
||
```
|
||
|
||
### 多语言本地化示例
|
||
```java
|
||
// 示例：多语言本地化
|
||
String locale = "zh_CN";
|
||
ZonedDateTime dateTime = ZonedDateTime.now();
|
||
|
||
// 本地化星期几
|
||
String dayOfWeek = dateTime.format(DateTimeFormatter.ofPattern("EEEE", Locale.forLanguageTag(locale)));
|
||
// 中文：星期一
|
||
// 英文：Monday
|
||
|
||
// 本地化月份名称
|
||
String monthName = dateTime.format(DateTimeFormatter.ofPattern("MMMM", Locale.forLanguageTag(locale)));
|
||
// 中文：一月
|
||
// 英文：January
|
||
```
|
||
|
||
---
|
||
|
||
## 缓存策略
|
||
|
||
### 缓存键格式
|
||
- 日期格式列表：`sys:dateFormat:list`
|
||
- 用户日期格式：`user:dateFormat:{userId}`
|
||
|
||
### 缓存时间
|
||
- 日期格式列表缓存：24 小时
|
||
- 用户日期格式缓存：24 小时
|
||
|
||
### 缓存刷新规则
|
||
1. 日期格式列表更新时，清除日期格式列表缓存
|
||
2. 日期格式切换时，清除用户日期格式缓存
|
||
3. 手动刷新日期格式缓存时，清除所有日期格式相关缓存
|
||
|
||
---
|
||
|
||
## AOP 统一处理说明
|
||
|
||
### AOP 切面设计
|
||
```java
|
||
@Aspect
|
||
@Component
|
||
public class DateFormatAspect {
|
||
|
||
@Autowired
|
||
private DateFormatService dateFormatService;
|
||
|
||
@AfterReturning(pointcut = "@annotation(com.datai.common.annotation.DateFormat)", returning = "result")
|
||
public void formatDate(JoinPoint joinPoint, Object result) {
|
||
if (result == null) {
|
||
return;
|
||
}
|
||
|
||
Object formattedResult = dateFormatService.formatObject(result);
|
||
return formattedResult;
|
||
}
|
||
}
|
||
```
|
||
|
||
### AOP 使用示例
|
||
```java
|
||
@Service
|
||
public class OrderServiceImpl implements IOrderService {
|
||
|
||
@DateFormat
|
||
@Override
|
||
public Order getOrderById(Long orderId) {
|
||
Order order = orderMapper.selectOrderById(orderId);
|
||
return order;
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **日期格式验证**：切换日期格式时，必须验证日期格式代码的有效性
|
||
2. **日期格式化**：日期格式化在 Service 层通过 AOP 统一处理
|
||
3. **日期存储**：所有日期字段使用 LocalDateTime 或 ZonedDateTime 类型存储
|
||
4. **时区转换**：自动将 UTC 时间转换为用户时区
|
||
5. **缓存管理**：日期格式和用户日期格式需要缓存，提高性能
|
||
6. **页面刷新**：日期格式切换后立即刷新页面，重新加载日期数据
|
||
7. **日期格式列表**：日期格式列表固定存储在数据库中，后续不允许用户调整
|
||
8. **多语言本地化**：根据用户语言偏好本地化日期（如星期几、月份名称）
|
||
9. **权限控制**：所有用户都可以设置和切换日期格式
|
||
10. **审计日志**：记录日期格式设置变更日志
|
||
|
||
---
|
||
|
||
## 性能要求
|
||
|
||
- **日期格式化时间**：< 10ms
|
||
- **日期格式切换响应时间**：< 500ms
|
||
- **时区转换时间**：< 10ms
|
||
- **缓存命中率**：≥ 90%
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- [需求文档](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/reference-code/2026-01-25-002-06-code-日期格式化功能实现.md)
|
||
- [实施方案](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/implementation/2026-01-25-002-06-implementation-日期格式化功能实现.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)
|