datai/datai-scenes/datai-scene-salesforce/docs/changelog/2026-01-25-002-04-changelog.md

变更日志

元数据

• 需求编号：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 字段

相关文档

核心文档

• 需求文档
• 设计文档
• 决策记录

实施文档

• SQL 脚本
• 提示词文档
• 参考代码文档
• 实施方案文档

记录文档

• 会话记录
• 变更日志

技术选型

时区库

• 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 注解