309 lines
10 KiB
Markdown
309 lines
10 KiB
Markdown
# 变更日志
|
||
|
||
## 元数据
|
||
- 需求编号：002-04
|
||
- 创建时间：2026-01-25
|
||
- 创建人：AI Assistant
|
||
- 版本号：v1.0.0
|
||
|
||
## 变更概述
|
||
实现时区国际化功能，包括时区设置、时区转换、时区显示、时区列表管理、时区切换、时区缓存管理和时区优先级管理等功能。该功能使系统能够根据用户的时区偏好显示相应的时间，提升跨时区用户的体验。
|
||
|
||
## 变更内容
|
||
|
||
### 新增功能
|
||
|
||
#### 1. 时区设置
|
||
- 创建 SysTimezone 实体类，管理时区配置
|
||
- 扩展 SysUser 实体类，添加 time_zone 字段存储用户时区偏好
|
||
- 实现时区设置功能，支持用户设置时区偏好
|
||
- 支持系统默认时区配置
|
||
|
||
#### 2. 时区转换
|
||
- 创建 TimeZoneUtils 工具类，提供时区转换方法
|
||
- 创建 @TimeZoneConvert 注解，标记需要时区转换的 Service 方法
|
||
- 创建 TimeZoneConvertAspect 切面类，自动拦截 Service 方法返回值进行时区转换
|
||
- 支持递归转换复杂对象中的 LocalDateTime 字段
|
||
- 支持无效时区容错处理
|
||
|
||
#### 3. 时区显示
|
||
- 创建获取当前用户时区接口
|
||
- 支持显示时区偏移量
|
||
- 支持时区切换提示
|
||
|
||
#### 4. 时区列表管理
|
||
- 创建 SysTimezoneMapper 接口和 XML，提供时区数据访问
|
||
- 创建 ISysTimezoneService 接口，提供时区管理服务
|
||
- 创建 SysTimezoneServiceImpl 实现类，实现时区管理逻辑
|
||
- 创建 SysTimezoneController 控制器类，提供时区管理接口
|
||
- 支持时区列表查询、新增、修改、删除
|
||
- 支持时区数据缓存（24 小时）
|
||
|
||
#### 5. 时区切换
|
||
- 创建切换用户时区接口
|
||
- 实现时区切换功能，支持用户切换时区
|
||
- 支持时区切换后清除缓存
|
||
- 添加审计日志记录时区切换操作
|
||
|
||
#### 6. 时区缓存管理
|
||
- 实现 Redis 缓存策略，提高性能
|
||
- 时区列表缓存 24 小时
|
||
- 用户时区缓存 30 分钟
|
||
- 支持时区切换时清除缓存
|
||
- 使用 CacheUtils 统一缓存管理
|
||
|
||
#### 7. 时区优先级管理
|
||
- 实现多级时区优先级策略
|
||
- 支持用户时区 > 系统时区的优先级
|
||
- 实现默认时区回退机制
|
||
|
||
### 修改功能
|
||
|
||
#### 1. 扩展 SysUser 实体类
|
||
- 添加 time_zone 字段（VARCHAR(50)）
|
||
- 添加 getter 和 setter 方法
|
||
- 支持用户时区偏好持久化
|
||
|
||
#### 2. 扩展 ISysTimezoneService 接口
|
||
- 添加 getCurrentUserTimeZone 方法
|
||
- 添加 switchTimeZone 方法
|
||
- 添加 getDefaultTimeZone 方法
|
||
- 添加 getUserTimeZone 方法
|
||
|
||
#### 3. 实现 SysTimezoneServiceImpl 扩展方法
|
||
- 实现 getCurrentUserTimeZone 方法，获取当前用户时区
|
||
- 实现 switchTimeZone 方法，切换用户时区并清除缓存
|
||
- 实现 getDefaultTimeZone 方法，获取系统默认时区并缓存
|
||
- 实现 getUserTimeZone 方法，获取用户时区并缓存
|
||
- 使用 CacheUtils 统一缓存管理
|
||
|
||
#### 4. 扩展 SysTimezoneController 控制器
|
||
- 添加 GET /system/timezone/current 接口，获取当前用户时区
|
||
- 添加 POST /system/timezone/switch 接口，切换用户时区（含审计日志）
|
||
- 添加 GET /system/timezone/default 接口，获取系统默认时区（含权限控制）
|
||
|
||
#### 5. 扩展 CacheConstants 常量类
|
||
- 添加 SYS_TIMEZONE_KEY 常量，统一时区缓存键
|
||
|
||
### 新增代码文件
|
||
|
||
#### 实体类
|
||
- `datai-system/src/main/java/com/datai/system/domain/SysTimezone.java` - 时区实体类
|
||
- `datai-common/src/main/java/com/datai/common/core/domain/entity/SysUser.java` - 扩展用户实体类，添加 time_zone 字段
|
||
|
||
#### Mapper 接口
|
||
- `datai-system/src/main/java/com/datai/system/mapper/SysTimezoneMapper.java` - 时区数据访问接口
|
||
- `datai-system/src/main/resources/mapper/system/SysTimezoneMapper.xml` - 时区数据访问 XML
|
||
|
||
#### Service 接口和实现
|
||
- `datai-system/src/main/java/com/datai/system/service/ISysTimezoneService.java` - 时区服务接口（含扩展方法）
|
||
- `datai-system/src/main/java/com/datai/system/service/impl/SysTimezoneServiceImpl.java` - 时区服务实现类（含扩展方法）
|
||
|
||
#### Controller 控制器
|
||
- `datai-admin/src/main/java/com/datai/web/controller/system/SysTimezoneController.java` - 时区管理控制器（含扩展接口）
|
||
|
||
#### 工具类
|
||
- `datai-common/src/main/java/com/datai/common/utils/TimeZoneUtils.java` - 时区转换工具类
|
||
|
||
#### 注解
|
||
- `datai-common/src/main/java/com/datai/common/annotation/TimeZoneConvert.java` - 时区转换注解
|
||
|
||
#### 切面类
|
||
- `datai-common/src/main/java/com/datai/common/aspect/TimeZoneConvertAspect.java` - 时区转换切面类
|
||
|
||
#### 常量类
|
||
- `datai-common/src/main/java/com/datai/common/constant/CacheConstants.java` - 扩展缓存常量，添加 SYS_TIMEZONE_KEY
|
||
|
||
#### 单元测试
|
||
- `datai-common/src/test/java/com/datai/common/utils/TimeZoneUtilsTest.java` - TimeZoneUtils 单元测试
|
||
|
||
### 新增文档
|
||
|
||
#### 需求文档
|
||
- [时区国际化需求](../requirements/2026-01-21-002-04-时区国际化需求.md)
|
||
|
||
#### 设计文档
|
||
- [时区国际化设计](../design/2026-01-21-002-04-时区国际化设计.md)
|
||
|
||
#### 决策记录
|
||
- [时区国际化技术选型](../decisions/adr/2026-01-25-002-04-ADR-时区国际化技术选型.md)
|
||
|
||
#### SQL 脚本
|
||
- [时区国际化数据库变更](../sql/2026-01-25-002-04-timezone-internationalization.sql)
|
||
|
||
#### 提示词文档
|
||
- [时区国际化功能实现提示词](../prompts/2026-01-25-002-04-prompt-时区国际化功能.md)
|
||
|
||
#### 参考代码文档
|
||
- [时区国际化参考代码](../reference-code/2026-01-25-002-04-code-时区国际化功能.md)
|
||
|
||
#### 实施方案文档
|
||
- [时区国际化实施方案](../implementation/2026-01-25-002-04-implementation-时区国际化功能.md)
|
||
|
||
#### 会话记录
|
||
- [时区国际化功能实现会话记录](../sessions/2026-01-25-002-04-session.md)
|
||
|
||
## 影响范围
|
||
|
||
### 模块级别
|
||
- `datai-common` - 公共模块
|
||
- `datai-system` - 系统模块
|
||
- `datai-admin` - 管理模块
|
||
|
||
### 功能级别
|
||
- 时区管理功能
|
||
- 时区转换功能
|
||
- 缓存管理功能
|
||
- 用户管理功能
|
||
|
||
### 文件级别
|
||
- 新增 8 个代码文件
|
||
- 修改 2 个现有文件
|
||
- 新增 1 个 SQL 脚本文件
|
||
- 新增 8 个文档文件
|
||
|
||
### 数据库级别
|
||
- 新增 `sys_timezone` 表
|
||
- 修改 `sys_user` 表，添加 `time_zone` 字段
|
||
|
||
## 相关文档
|
||
|
||
### 核心文档
|
||
- [需求文档](../requirements/2026-01-21-002-04-时区国际化需求.md)
|
||
- [设计文档](../design/2026-01-21-002-04-时区国际化设计.md)
|
||
- [决策记录](../decisions/adr/2026-01-25-002-04-ADR-时区国际化技术选型.md)
|
||
|
||
### 实施文档
|
||
- [SQL 脚本](../sql/2026-01-25-002-04-timezone-internationalization.sql)
|
||
- [提示词文档](../prompts/2026-01-25-002-04-prompt-时区国际化功能.md)
|
||
- [参考代码文档](../reference-code/2026-01-25-002-04-code-时区国际化功能.md)
|
||
- [实施方案文档](../implementation/2026-01-25-002-04-implementation-时区国际化功能.md)
|
||
|
||
### 记录文档
|
||
- [会话记录](../sessions/2026-01-25-002-04-session.md)
|
||
- [变更日志](./2026-01-25-002-04-changelog.md)
|
||
|
||
## 技术选型
|
||
|
||
### 时区库
|
||
- Java TimeZone API（Java 21 内置）
|
||
- ZoneId、ZonedDateTime
|
||
|
||
### 缓存技术
|
||
- Spring Cache
|
||
- CacheUtils
|
||
- CacheConstants
|
||
|
||
### 数据库
|
||
- MySQL 8.3.0+
|
||
- 新增 `sys_timezone` 表
|
||
- 修改 `sys_user` 表
|
||
|
||
### 编码格式
|
||
- UTF-8
|
||
- 支持多语言字符
|
||
|
||
## 测试
|
||
|
||
### 单元测试
|
||
- TimeZoneUtils 单元测试
|
||
- testConvertUtcToTimeZone
|
||
- testConvertUtcToTimeZoneWithNull
|
||
- testConvertUtcToTimeZoneWithInvalidTimeZone
|
||
- testConvertTimeZoneToUtc
|
||
- testConvertTimeZoneToUtcWithNull
|
||
- testConvertTimeZoneToUtcWithInvalidTimeZone
|
||
- testIsValidTimeZone
|
||
- testIsValidTimeZoneWithInvalid
|
||
|
||
### 集成测试
|
||
- 时区设置功能测试
|
||
- 时区转换功能测试
|
||
- 时区查询功能测试
|
||
- 缓存同步测试
|
||
|
||
### 手动测试
|
||
- 测试不同时区的用户
|
||
- 测试时区切换功能
|
||
- 测试时区转换准确性
|
||
- 测试缓存功能
|
||
|
||
## 部署说明
|
||
|
||
### 数据库变更
|
||
执行以下 SQL 脚本：
|
||
```sql
|
||
-- 创建时区表
|
||
CREATE TABLE `sys_timezone` (
|
||
`timezone_id` varchar(50) NOT NULL COMMENT '时区ID',
|
||
`timezone_name` varchar(100) NOT NULL COMMENT '时区名称',
|
||
`timezone_offset` varchar(10) NOT NULL COMMENT '时区偏移量',
|
||
`is_active` char(1) DEFAULT '1' COMMENT '是否激活（0否 1是）',
|
||
`is_default` char(1) DEFAULT '0' COMMENT '是否默认（0否 1是）',
|
||
`create_by` varchar(64) DEFAULT '' COMMENT '创建者',
|
||
`create_time` datetime DEFAULT NULL COMMENT '创建时间',
|
||
`update_by` varchar(64) DEFAULT '' COMMENT '更新者',
|
||
`update_time` datetime DEFAULT NULL COMMENT '更新时间',
|
||
`remark` varchar(500) DEFAULT NULL COMMENT '备注',
|
||
PRIMARY KEY (`timezone_id`)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='时区表';
|
||
|
||
-- 修改用户表，添加时区字段
|
||
ALTER TABLE `sys_user`
|
||
ADD COLUMN `time_zone` varchar(50) NULL COMMENT '时区ID' AFTER `lang_code`;
|
||
|
||
-- 插入常用时区数据
|
||
INSERT INTO `sys_timezone` (`timezone_id`, `timezone_name`, `timezone_offset`, `is_active`, `is_default`, `create_by`, `create_time`, `remark`) VALUES
|
||
('Asia/Shanghai', '上海', 'UTC+8', '1', '1', 'admin', NOW(), '中国标准时间'),
|
||
('America/New_York', '纽约', 'UTC-5', '1', '0', 'admin', NOW(), '美国东部时间'),
|
||
('Europe/London', '伦敦', 'UTC+0', '1', '0', 'admin', NOW(), '格林威治标准时间'),
|
||
('Asia/Tokyo', '东京', 'UTC+9', '1', '0', 'admin', NOW(), '日本标准时间'),
|
||
('Australia/Sydney', '悉尼', 'UTC+10', '1', '0', 'admin', NOW(), '澳大利亚东部时间'),
|
||
('Europe/Paris', '巴黎', 'UTC+1', '1', '0', 'admin', NOW(), '中欧时间'),
|
||
('America/Los_Angeles', '洛杉矶', 'UTC-8', '1', '0', 'admin', NOW(), '美国太平洋时间');
|
||
```
|
||
|
||
### 配置文件
|
||
确保 Spring Cache 配置正确：
|
||
```yaml
|
||
spring:
|
||
cache:
|
||
type: redis
|
||
```
|
||
|
||
### AOP 配置
|
||
确保 Spring AOP 配置启用：
|
||
```yaml
|
||
spring:
|
||
aop:
|
||
proxy-target-class: true
|
||
```
|
||
|
||
## 后续优化
|
||
|
||
### 性能优化
|
||
- 优化时区转换性能
|
||
- 支持批量时区转换
|
||
- 优化缓存命中率
|
||
|
||
### 功能扩展
|
||
- 支持租户时区
|
||
- 支持更多时间类型转换（Date、Timestamp）
|
||
- 支持时区转换日志记录
|
||
- 支持时区转换性能监控
|
||
|
||
### 用户体验
|
||
- 提供时区选择器界面
|
||
- 支持浏览器时区自动检测
|
||
- 支持时区切换动画效果
|
||
|
||
## 已知问题
|
||
|
||
### 未实现的需求
|
||
- 租户时区支持（功能 7 的部分需求）
|
||
- 数据缓存策略（在原有缓存键基础上添加时区后缀）
|
||
|
||
### 限制说明
|
||
- 当前仅支持"用户 > 系统"两级时区优先级
|
||
- 时区转换仅在 Service 层通过 AOP 自动进行
|
||
- 需要手动在 Service 方法上添加 @TimeZoneConvert 注解 |