kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/docs/archive/2026-01-21-002-06-日期格式化需求.md

13 KiB
Raw Permalink Blame History

日期格式化需求

元数据

  • 需求编号：2026-01-21-002-06
  • 创建时间：2026-01-21
  • 创建人：SSOT 架构师
  • 状态：进行中
  • 优先级：中
  • 父需求：2026-01-21-002-项目国际化需求

需求概述

实现日期格式化功能，支持根据用户地区显示日期，支持常用日期格式、日期时间格式化、短日期和长日期格式化。后端使用 Java 的 DateTimeFormatter 进行日期格式化，结合时区转换功能，支持多语言日期显示。

目标

  1. 日期格式支持：支持常用日期格式（如：YYYY-MM-DD、DD/MM/YYYY、MM/DD/YYYY 等）
  2. 日期时间格式化：支持日期时间格式化
  3. 长短格式：支持短日期和长日期格式
  4. 自动选择：根据用户地区偏好自动选择日期格式
  5. 自定义格式：支持用户自定义日期格式
  6. 时区转换：结合时区转换功能，支持跨时区日期格式化
  7. 多语言支持：支持多语言日期显示（如：星期几、月份名称的本地化）
  8. AOP 自动格式化：使用 AOP 在 Service 层自动进行日期格式化

业务上下文

当前问题

  • 日期显示格式固定，无法根据用户地区自动调整
  • 缺乏日期格式化功能，用户体验不佳
  • 未结合时区转换，跨时区日期显示不准确
  • 未支持多语言日期显示，国际化体验不佳

业务场景

日期格式化
├─ 常用日期格式
│  ├─ ISO 8601：YYYY-MM-DD
│  ├─ 欧洲格式：DD/MM/YYYY
│  ├─ 美国格式：MM/DD/YYYY
│  └─ 中国格式：YYYY年MM月DD日
├─ 日期时间格式
│  ├─ 短格式：YYYY-MM-DD HH:mm:ss
│  ├─ 长格式：YYYY年MM月DD日 HH时mm分ss秒
│  └─ 相对时间：X分钟前、X小时前、X天前（前端实现）
└─ 显示场景
   ├─ 表格列：创建时间、更新时间等
   ├─ 表单字段：出生日期、入职日期等
   └─ 日志记录：操作时间、登录时间等

应用场景

  1. 多地区用户：不同国家和地区的用户使用系统，需要看到符合当地习惯的日期格式
  2. 数据展示：显示数据时，需要符合用户地区的日期格式
  3. 报表生成：生成报表时，需要符合用户地区的日期格式
  4. 跨时区协作：不同时区的用户协作时，需要看到正确的本地时间
  5. 多语言环境：不同语言环境的用户需要看到本地化的日期显示

功能需求

核心功能

功能 1：常用日期格式

  • 描述：支持常用日期格式
  • 验收标准：
    1. 支持 ISO 8601 格式（YYYY-MM-DD）
    2. 支持欧洲格式（DD/MM/YYYY）
    3. 支持美国格式（MM/DD/YYYY）
    4. 支持中国格式（YYYY年MM月DD日）
    5. 支持自定义格式
  • 优先级：高
  • 依赖关系：无

功能 2：日期时间格式化

  • 描述：支持日期时间格式化
  • 验收标准：
    1. 支持短日期时间格式（YYYY-MM-DD HH:mm:ss）
    2. 支持长日期时间格式（YYYY年MM月DD日 HH时mm分ss秒）
    3. 支持自定义格式
  • 优先级：高
  • 依赖关系：无

功能 3：长短格式

  • 描述：支持短日期和长日期格式
  • 验收标准：
    1. 支持短日期格式（如：2026-01-21）
    2. 支持长日期格式（如：2026年01月21日）
    3. 支持自定义格式
  • 优先级：高
  • 依赖关系：无

功能 4：自动选择格式

  • 描述：根据用户地区偏好自动选择日期格式
  • 验收标准：
    1. 根据用户地区偏好自动选择日期格式
    2. 格式选择准确无误
    3. 支持常用地区（中国、美国、欧洲等）
  • 优先级：高
  • 依赖关系：依赖用户语言偏好表

功能 5：自定义格式

  • 描述：支持用户自定义日期格式
  • 验收标准：
    1. 支持用户自定义日期格式
    2. 支持常用格式模板
    3. 自定义格式立即生效
    4. 自定义格式存储在数据库中
  • 优先级：中
  • 依赖关系：依赖用户语言偏好表

功能 6：时区转换

  • 描述：结合时区转换功能，支持跨时区日期格式化
  • 验收标准：
    1. 自动将 UTC 时间转换为用户时区
    2. 支持用户时区偏好
    3. 支持系统默认时区
    4. 时区转换准确无误
  • 优先级：高
  • 依赖关系：依赖时区转换功能（2026-01-21-002-04）

功能 7：多语言支持

  • 描述：支持多语言日期显示
  • 验收标准：
    1. 支持星期几的本地化（中文：星期一；英文：Monday）
    2. 支持月份名称的本地化（中文：一月；英文：January）
    3. 支持常用语言（中文、英文等）
    4. 根据用户语言偏好自动选择语言
  • 优先级：中
  • 依赖关系：依赖国际化功能（2026-01-21-002-03）

功能 8：AOP 自动格式化

  • 描述：使用 AOP 在 Service 层自动进行日期格式化
  • 验收标准：
    1. 实现 @DateFormat 注解
    2. 实现 DateFormatAspect 切面
    3. 自动拦截标记的方法，格式化返回值中的日期字段
    4. 支持递归格式化嵌套对象中的日期字段
    5. 格式化性能满足要求（< 10ms）
  • 优先级：高
  • 依赖关系：无

功能 9：用户日期格式偏好

  • 描述：支持用户设置日期格式偏好
  • 验收标准：
    1. 扩展 SysUser 表，添加 date_format 字段
    2. 支持用户切换日期格式
    3. 支持用户自定义日期格式
    4. 切换操作记录到审计日志
  • 优先级：高
  • 依赖关系：无

功能 10：系统默认日期格式

  • 描述：支持在配置文件中设置系统默认日期格式
  • 验收标准：
    1. 在配置文件中设置系统默认日期格式
    2. 用户未设置时使用系统默认格式
    3. 系统默认格式可配置
  • 优先级：高
  • 依赖关系：无

功能 11：缓存机制

  • 描述：使用 Redis 缓存用户日期格式偏好
  • 验收标准：
    1. 使用 Redis 缓存用户日期格式偏好
    2. 缓存 TTL 设置为 24 小时
    3. 用户切换格式时清除缓存
    4. 缓存键符合项目规范
  • 优先级：中
  • 依赖关系：无

功能 12：相对时间（前端实现）

  • 描述：支持相对时间格式（X分钟前、X小时前、X天前）
  • 验收标准：
    1. 支持相对时间格式
    2. 相对时间实时更新
    3. 支持多种时间单位（秒、分钟、小时、天、周、月、年）
  • 优先级：低
  • 依赖关系：前端实现
  • 备注：此功能在前端实现，不在本次后端开发范围

非功能需求

性能需求

  • 格式化时间：日期格式化时间 < 10ms
  • 缓存命中率：用户日期格式偏好缓存命中率 ≥ 90%

兼容性需求

  • Java 版本：Java 21
  • Spring Boot 版本：3.5.7
  • 日期格式化库：使用 Java 内置的 DateTimeFormatter

可维护性需求

  • 代码可读性：代码符合项目编码规范，注释完整
  • 测试覆盖率：单元测试覆盖率 ≥ 80%
  • 文档完整性：所有功能都有对应的文档说明

安全性需求

  • 输入验证：验证用户输入的日期格式，防止格式注入攻击
  • 权限控制：用户只能设置自己的日期格式偏好
  • 审计日志：记录用户切换日期格式的操作

数据需求

数据依赖

  • 依赖用户语言偏好表（sys_user_lang）
  • 依赖时区转换功能（sys_timezone）

数据存储需求

  1. 扩展 SysUser 表：

    • 添加 date_format 字段（VARCHAR(50)）：存储用户日期格式偏好
    • 添加 date_format_pattern 字段（VARCHAR(100)）：存储用户自定义日期格式模式

  2. 配置文件：

    • 添加系统默认日期格式配置（sys.default.date.format）
    • 添加系统默认日期格式模式配置（sys.default.date.format.pattern）

  3. Redis 缓存：

    • 缓存用户日期格式偏好
    • 缓存键：SYS_DATE_FORMAT_KEY
    • 缓存 TTL：24 小时

数据流转需求

日期显示
  └─ 读取用户日期格式偏好（缓存或数据库）
  └─ 读取用户时区偏好（缓存或数据库）
  └─ 读取用户语言偏好（缓存或数据库）
  └─ 将 UTC 时间转换为用户时区
  └─ 根据用户日期格式偏好格式化日期
  └─ 根据用户语言偏好本地化日期
  └─ 显示格式化后的日期

业务规则

  1. 日期格式优先级：用户日期格式偏好 > 系统默认格式
  2. 时区优先级：用户时区偏好 > 系统默认时区
  3. 语言优先级：用户语言偏好 > 系统默认语言
  4. 格式化准确性：日期格式化必须准确无误
  5. 自定义格式权限：所有用户都可以自定义日期格式
  6. 缓存更新：用户切换日期格式时立即清除缓存

技术约束

  1. Spring Boot 版本：3.5.7
  2. Java 版本：21
  3. 日期格式化库：Java 内置的 DateTimeFormatter
  4. 必须使用现有的认证授权机制：不能引入新的认证方式
  5. 必须使用现有的缓存机制：使用 CacheUtils 进行缓存操作
  6. 必须使用现有的 AOP 机制：使用 @Aspect 注解实现切面

技术方案

后端实现方案

  1. 日期格式化工具类：创建 DateFormatUtils 工具类，提供常用的日期格式化方法
  2. AOP 切面：创建 DateFormatAspect 切面，使用 @Aspect 注解实现
  3. 注解：创建 @DateFormat 注解，标记需要格式化的方法
  4. 缓存机制：使用 CacheUtils 进行缓存操作，缓存键为 SYS_DATE_FORMAT_KEY
  5. 时区转换：复用已实现的时区转换功能（TimeZoneConvertAspect）
  6. 多语言支持：结合国际化功能，使用 Locale 进行本地化

数据库设计

  1. 扩展 SysUser 表：

    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 '日期格式模式';

  2. 配置文件：

    # 系统默认日期格式
sys:
  default:
    date:
      format: yyyy-MM-dd
      format-pattern: yyyy年MM月dd日

缓存设计

  1. 缓存键：SYS_DATE_FORMAT_KEY
  2. 缓存结构： 
    SYS_DATE_FORMAT_KEY -> {
  "userId": {
    "dateFormat": "yyyy-MM-dd",
    "dateFormatPattern": "yyyy年MM月dd日"
  }
}
  3. 缓存 TTL：24 小时

API 设计

  1. 获取用户日期格式偏好：GET /system/user/dateFormat
  2. 切换用户日期格式：POST /system/user/switchDateFormat
  3. 获取系统默认日期格式：GET /system/dateFormat/default

成功标准

  1. 支持常用日期格式
  2. 支持日期时间格式化
  3. 支持短日期和长日期格式
  4. 支持自动选择格式
  5. 支持自定义格式
  6. 支持时区转换
  7. 支持多语言日期显示
  8. 实现 AOP 自动格式化
  9. 日期格式化时间 < 10ms
  10. 单元测试覆盖率 ≥ 80%

风险评估

风险 影响程度 发生概率 缓解措施
日期格式化错误 中 低 使用 Java 内置的 DateTimeFormatter，充分测试
时区转换错误 中 低 复用已实现的时区转换功能，充分测试
地区识别错误 低 低 实现地区识别验证机制
缓存一致性 中 中 用户切换格式时立即清除缓存
性能问题 中 低 使用缓存，优化格式化逻辑

依赖关系

  • 依赖用户语言偏好表
  • 依赖时区转换功能（2026-01-21-002-04）
  • 依赖国际化功能（2026-01-21-002-03）
  • 依赖现有的 Spring Boot 框架
  • 依赖现有的认证授权机制
  • 依赖现有的缓存机制

相关文档