248 lines
11 KiB
Markdown
248 lines
11 KiB
Markdown
# 变更日志：日期格式化功能
|
||
|
||
## 元数据
|
||
- 变更编号：2026-01-25-002-06-changelog
|
||
- 需求编号：2026-01-21-002-06
|
||
- 功能名称：日期格式化功能
|
||
- 版本：3.8.5
|
||
- 发布日期：2026-01-25
|
||
- 变更类型：新功能
|
||
- 状态：已完成
|
||
- 阶段：阶段 8：变更日志
|
||
|
||
## 变更概述
|
||
|
||
本次更新新增了日期格式化功能，支持根据用户地区显示日期，支持常用日期格式、日期时间格式化、短日期和长日期格式化。后端使用 Java 的 DateTimeFormatter 进行日期格式化，结合时区转换功能，支持多语言日期显示。
|
||
|
||
## 新增功能
|
||
|
||
### 1. 日期格式化功能
|
||
- **功能描述**：支持常用日期格式（ISO_8601、US、EU、CN、JP、KR 等）
|
||
- **影响范围**：datai-common、datai-framework
|
||
- **相关文件**：
|
||
- [DateConstants.java](file:///d:/idea_demo/datai/datai-common/src/main/java/com/datai/common/constant/DateConstants.java) - 日期格式常量类
|
||
- [@DateFormat.java](file:///d:/idea_demo/datai/datai-common/src/main/java/com/datai/common/annotation/DateFormat.java) - 日期格式化注解
|
||
- [DateFormatUtils.java](file:///d:/idea_demo/datai/datai-common/src/main/java/com/datai/common/utils/DateFormatUtils.java) - 日期格式化工具类
|
||
- [DateFormatAspect.java](file:///d:/idea_demo/datai/datai-framework/src/main/java/com/datai/framework/aspectj/DateFormatAspect.java) - 日期格式化 AOP 切面
|
||
|
||
### 2. 用户日期格式偏好管理
|
||
- **功能描述**：支持用户设置和切换日期格式偏好
|
||
- **影响范围**：datai-common、datai-system、datai-admin
|
||
- **相关文件**：
|
||
- [SysUser.java](file:///d:/idea_demo/datai/datai-common/src/main/java/com/datai/common/core/domain/entity/SysUser.java) - 添加日期格式偏好字段
|
||
- [ISysUserService.java](file:///d:/idea_demo/datai/datai-system/src/main/java/com/datai/system/service/ISysUserService.java) - 添加日期格式偏好管理方法
|
||
- [SysUserServiceImpl.java](file:///d:/idea_demo/datai/datai-system/src/main/java/com/datai/system/service/impl/SysUserServiceImpl.java) - 实现日期格式偏好管理逻辑
|
||
- [SysUserController.java](file:///d:/idea_demo/datai/datai-admin/src/main/java/com/datai/web/controller/system/SysUserController.java) - 添加日期格式偏好管理接口
|
||
|
||
### 3. 系统默认日期格式配置
|
||
- **功能描述**：支持在配置文件中设置系统默认日期格式
|
||
- **影响范围**：datai-admin
|
||
- **相关文件**：
|
||
- [application.yml](file:///d:/idea_demo/datai/datai-admin/src/main/resources/application.yml) - 添加系统默认日期格式配置
|
||
- [SysConfigController.java](file:///d:/idea_demo/datai/datai-admin/src/main/java/com/datai/web/controller/system/SysConfigController.java) - 添加系统默认日期格式接口
|
||
|
||
### 4. 缓存机制
|
||
- **功能描述**：使用 Redis 缓存用户日期格式偏好，提高查询性能
|
||
- **影响范围**：datai-common、datai-system
|
||
- **相关文件**：
|
||
- [CacheConstants.java](file:///d:/idea_demo/datai/datai-common/src/main/java/com/datai/common/constant/CacheConstants.java) - 添加日期格式缓存常量
|
||
- [SysUserServiceImpl.java](file:///d:/idea_demo/datai/datai-system/src/main/java/com/datai/system/service/impl/SysUserServiceImpl.java) - 实现缓存逻辑
|
||
|
||
### 5. 单元测试
|
||
- **功能描述**：为日期格式化功能添加单元测试
|
||
- **影响范围**：datai-common、datai-framework
|
||
- **相关文件**：
|
||
- [DateFormatUtilsTest.java](file:///d:/idea_demo/datai/datai-common/src/test/java/com/datai/common/utils/DateFormatUtilsTest.java) - DateFormatUtils 工具类单元测试
|
||
- [DateFormatAspectTest.java](file:///d:/idea_demo/datai/datai-framework/src/test/java/com/datai/framework/aspectj/DateFormatAspectTest.java) - DateFormatAspect AOP 切面单元测试
|
||
|
||
## 优化改进
|
||
|
||
### 1. 切面顺序控制
|
||
- **改进描述**：为 TimeZoneConvertAspect 添加 @Order(1) 注解，为 DateFormatAspect 添加 @Order(2) 注解，确保时区转换先于日期格式化执行
|
||
- **影响范围**：datai-framework
|
||
- **相关文件**：
|
||
- [TimeZoneConvertAspect.java](file:///d:/idea_demo/datai/datai-framework/src/main/java/com/datai/framework/aspectj/TimeZoneConvertAspect.java) - 添加 @Order(1) 注解
|
||
- [DateFormatAspect.java](file:///d:/idea_demo/datai/datai-framework/src/main/java/com/datai/framework/aspectj/DateFormatAspect.java) - 添加 @Order(2) 注解
|
||
|
||
### 2. 线程安全优化
|
||
- **改进描述**：使用 ConcurrentHashMap 缓存 DateTimeFormatter 和 SimpleDateFormat 实例，确保线程安全
|
||
- **影响范围**：datai-common
|
||
- **相关文件**：
|
||
- [DateFormatUtils.java](file:///d:/idea_demo/datai/datai-common/src/main/java/com/datai/common/utils/DateFormatUtils.java) - 使用 ConcurrentHashMap 缓存格式化器实例
|
||
|
||
### 3. 缓存一致性优化
|
||
- **改进描述**：用户切换日期格式偏好时立即清除缓存，确保缓存一致性
|
||
- **影响范围**：datai-system
|
||
- **相关文件**：
|
||
- [SysUserServiceImpl.java](file:///d:/idea_demo/datai/datai-system/src/main/java/com/datai/system/service/impl/SysUserServiceImpl.java) - 更新数据库后立即清除缓存
|
||
|
||
## 数据库变更
|
||
|
||
### 1. 扩展 SysUser 表
|
||
- **变更类型**：新增字段
|
||
- **变更内容**：
|
||
```sql
|
||
ALTER TABLE sys_user ADD COLUMN date_format VARCHAR(50) DEFAULT NULL COMMENT '日期格式';
|
||
ALTER TABLE sys_user ADD COLUMN date_format_pattern VARCHAR(100) DEFAULT NULL COMMENT '日期格式模式';
|
||
```
|
||
- **影响范围**：sys_user 表
|
||
- **相关文件**：
|
||
- [2026-01-25-002-06-日期格式化.sql](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/sql/2026-01-25-002-06-日期格式化.sql) - 数据库变更脚本
|
||
|
||
## 配置变更
|
||
|
||
### 1. 系统默认日期格式配置
|
||
- **变更类型**：新增配置项
|
||
- **变更内容**：
|
||
```yaml
|
||
user:
|
||
# 默认语言代码
|
||
defaultLangCode: zh_CN
|
||
# 默认日期格式
|
||
defaultDateFormat: yyyy-MM-dd
|
||
# 默认日期时间格式
|
||
defaultDateTimeFormat: yyyy-MM-dd HH:mm:ss
|
||
```
|
||
- **影响范围**：application.yml
|
||
- **相关文件**：
|
||
- [application.yml](file:///d:/idea_demo/datai/datai-admin/src/main/resources/application.yml) - 添加系统默认日期格式配置
|
||
|
||
## API 变更
|
||
|
||
### 1. 新增用户日期格式偏好管理接口
|
||
- **接口路径**：/system/user/dateFormat
|
||
- **请求方法**：GET
|
||
- **接口描述**：获取当前用户日期格式偏好
|
||
- **响应示例**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"userId": 1,
|
||
"dateFormat": "ISO_8601",
|
||
"dateFormatPattern": null
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 新增切换用户日期格式偏好接口
|
||
- **接口路径**：/system/user/switchDateFormat
|
||
- **请求方法**：POST
|
||
- **接口描述**：切换用户日期格式偏好
|
||
- **请求示例**：
|
||
```json
|
||
{
|
||
"dateFormat": "ISO_8601",
|
||
"dateFormatPattern": null
|
||
}
|
||
```
|
||
- **响应示例**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功"
|
||
}
|
||
```
|
||
|
||
### 3. 新增获取系统默认日期格式接口
|
||
- **接口路径**：/system/config/defaultDateFormat
|
||
- **请求方法**：GET
|
||
- **接口描述**：获取系统默认日期格式
|
||
- **响应示例**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"dateFormat": "yyyy-MM-dd",
|
||
"dateTimeFormat": "yyyy-MM-dd HH:mm:ss"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 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."
|
||
},
|
||
"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"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 依赖变更
|
||
|
||
本次更新无新增依赖，使用 Java 内置的 DateTimeFormatter 进行日期格式化。
|
||
|
||
## 兼容性说明
|
||
|
||
### 1. 向后兼容性
|
||
- 本次更新为新增功能，不影响现有功能
|
||
- 现有 API 接口保持不变
|
||
- 数据库变更为新增字段，不影响现有数据
|
||
|
||
### 2. 升级说明
|
||
- 执行数据库变更脚本：[2026-01-25-002-06-日期格式化.sql](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/sql/2026-01-25-002-06-日期格式化.sql)
|
||
- 更新配置文件：在 application.yml 中添加系统默认日期格式配置
|
||
- 重启应用：重启应用以加载新的配置和代码
|
||
|
||
### 3. 回滚说明
|
||
- 如需回滚，执行以下步骤：
|
||
1. 删除新增的数据库字段：`ALTER TABLE sys_user DROP COLUMN date_format; ALTER TABLE sys_user DROP COLUMN date_format_pattern;`
|
||
2. 删除新增的代码文件
|
||
3. 恢复修改的文件
|
||
4. 删除配置文件中的新增配置项
|
||
5. 重启应用
|
||
|
||
## 已知问题
|
||
|
||
本次更新无已知问题。
|
||
|
||
## 后续计划
|
||
|
||
1. 进行集成测试：测试用户日期格式偏好接口、系统默认日期格式接口、AOP 切面功能、缓存功能、多语言日期显示功能、时区转换 + 日期格式化集成功能
|
||
2. 进行手动测试：测试不同日期格式的格式化、多语言日期显示、时区转换 + 日期格式化、用户日期格式偏好切换、缓存功能、嵌套对象格式化
|
||
3. 创建复盘文档：[2026-01-25-002-06-retro.md](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/retros/2026-01-25-002-06-retro.md)
|
||
4. 创建 API 文档：[2026-01-25-002-06-api.md](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/api-docs/2026-01-25-002-06-api.md)
|
||
|
||
## 相关文档
|
||
|
||
- [需求文档](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/retros/2026-01-25-002-06-retro.md) - 待创建
|
||
- [API 文档](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/api-docs/2026-01-25-002-06-api.md) - 待创建
|
||
|
||
## 变更统计
|
||
|
||
- 新增文件：6 个
|
||
- 修改文件：8 个
|
||
- 新增 API 接口：4 个
|
||
- 数据库变更：2 个字段
|
||
- 配置变更：3 个配置项
|
||
- 单元测试：2 个测试类，30 个测试用例
|