10 KiB
10 KiB
变更日志
元数据
- 需求编号：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 单元测试
新增文档
需求文档
设计文档
决策记录
SQL 脚本
提示词文档
参考代码文档
实施方案文档
会话记录
影响范围
模块级别
datai-common- 公共模块datai-system- 系统模块datai-admin- 管理模块
功能级别
- 时区管理功能
- 时区转换功能
- 缓存管理功能
- 用户管理功能
文件级别
- 新增 8 个代码文件
- 修改 2 个现有文件
- 新增 1 个 SQL 脚本文件
- 新增 8 个文档文件
数据库级别
- 新增
sys_timezone表 - 修改
sys_user表，添加time_zone字段
相关文档
核心文档
实施文档
记录文档
技术选型
时区库
- 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 脚本：
-- 创建时区表
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 配置正确：
spring:
cache:
type: redis
AOP 配置
确保 Spring AOP 配置启用：
spring:
aop:
proxy-target-class: true
后续优化
性能优化
- 优化时区转换性能
- 支持批量时区转换
- 优化缓存命中率
功能扩展
- 支持租户时区
- 支持更多时间类型转换（Date、Timestamp）
- 支持时区转换日志记录
- 支持时区转换性能监控
用户体验
- 提供时区选择器界面
- 支持浏览器时区自动检测
- 支持时区切换动画效果
已知问题
未实现的需求
- 租户时区支持（功能 7 的部分需求）
- 数据缓存策略（在原有缓存键基础上添加时区后缀）
限制说明
- 当前仅支持"用户 > 系统"两级时区优先级
- 时区转换仅在 Service 层通过 AOP 自动进行
- 需要手动在 Service 方法上添加 @TimeZoneConvert 注解