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

13 KiB
Raw Permalink Blame History

数字格式化需求

元数据

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

需求概述

实现数字格式化功能，支持根据用户地区显示数字，支持数字千分位分隔符、数字小数位格式化。后端使用 Java 的 NumberFormat 和 DecimalFormat 进行数字格式化，结合 AOP 在 Service 层自动进行数字格式化，支持多语言数字显示。

目标

  1. 千分位分隔符：支持数字千分位分隔符（如：,、. 等）
  2. 小数位格式化：支持数字小数位格式化
  3. 自动选择：根据用户地区偏好自动选择数字格式
  4. 自定义格式：支持自定义数字格式
  5. AOP 自动格式化：使用 AOP 在 Service 层自动进行数字格式化
  6. 缓存机制：使用 Redis 缓存用户的数字格式偏好，提高性能
  7. 配置管理：在配置文件中设置系统默认数字格式
  8. API 接口：提供数字格式化偏好管理的 RESTful API 接口

业务上下文

当前问题

  • 数字显示格式固定，无法根据用户地区自动调整
  • 缺乏数字格式化功能，用户体验不佳
  • 缺乏后端数字格式化功能，无法在 Service 层自动格式化
  • 缺乏用户数字格式偏好管理功能
  • 缺乏数字格式化缓存机制，性能有待提升

业务场景

数字格式化
├─ 千分位分隔符
│  ├─ 逗号分隔：1,234.56
│  ├─ 点分隔：1.234,56
│  └─ 空格分隔：1 234.56
├─ 小数位
│  ├─ 两位小数：1,234.56
│  ├─ 三位小数：1,234.567
│  └─ 四位小数：1,234.5678
├─ 后端实现
│  ├─ NumberFormat：标准数字格式化
│  ├─ DecimalFormat：自定义数字格式化
│  └─ AOP 切面：Service 层自动格式化
├─ 缓存机制
│  ├─ Redis 缓存：用户数字格式偏好
│  ├─ 缓存策略：24 小时 TTL
│  └─ 缓存更新：用户切换格式时更新
├─ 配置管理
│  ├─ 系统默认格式：配置文件设置
│  ├─ 常用格式列表：预定义格式
│  └─ 格式验证：格式有效性检查
├─ API 接口
│  ├─ 获取用户数字格式偏好
│  ├─ 切换用户数字格式偏好
│  ├─ 获取系统默认数字格式
│  └─ 获取常用数字格式列表
└─ 显示场景
   ├─ 统计数据：用户数、订单数等
   ├─ 财务数据：金额、利润等
   └─ 报表数据：各种统计指标

应用场景

  1. 多地区用户：不同国家和地区的用户使用系统，需要看到符合当地习惯的数字格式
  2. 数据展示：显示数据时，需要符合用户地区的数字格式
  3. 报表生成：生成报表时，需要符合用户地区的数字格式
  4. Service 层自动格式化：在 Service 层使用 AOP 自动进行数字格式化，减少重复代码
  5. 用户偏好管理：用户可以自定义数字格式偏好，系统自动应用
  6. 高性能场景：使用 Redis 缓存用户数字格式偏好，提高响应速度

功能需求

核心功能

功能 1：千分位分隔符

  • 描述：支持数字千分位分隔符
  • 验收标准：
    1. 支持逗号分隔符（,）
    2. 支持点分隔符（.）
    3. 支持空格分隔符（ ）
    4. 支持自定义分隔符
  • 优先级：高
  • 依赖关系：无

功能 2：小数位格式化

  • 描述：支持数字小数位格式化
  • 验收标准：
    1. 支持两位小数格式化
    2. 支持三位小数格式化
    3. 支持四位小数格式化
    4. 支持自定义小数位
    5. 小数位四舍五入
  • 优先级：高
  • 依赖关系：无

功能 3：自动选择格式

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

功能 4：自定义格式

  • 描述：支持用户自定义数字格式
  • 验收标准：
    1. 支持用户自定义千分位分隔符
    2. 支持用户自定义小数位
    3. 自定义格式立即生效
  • 优先级：中
  • 依赖关系：依赖用户语言偏好表

功能 5：后端数字格式化

  • 描述：使用 Java 的 NumberFormat 和 DecimalFormat 进行数字格式化
  • 验收标准：
    1. 使用 NumberFormat 进行标准数字格式化
    2. 使用 DecimalFormat 进行自定义数字格式化
    3. 支持整数、浮点数、大数字格式化
    4. 支持负数格式化
    5. 支持百分比格式化
    6. 格式化准确无误
  • 优先级：高
  • 依赖关系：无

功能 6：AOP 自动格式化

  • 描述：使用 AOP 在 Service 层自动进行数字格式化
  • 验收标准：
    1. 使用 @NumberFormat 注解标记需要格式化的方法
    2. 使用 NumberFormatAspect 切面自动格式化返回值
    3. 支持单个数字格式化
    4. 支持 List 集合数字格式化
    5. 支持 Page 分页对象数字格式化
    6. 支持嵌套对象数字格式化
    7. 格式化不影响原始数据
  • 优先级：高
  • 依赖关系：依赖功能 5（后端数字格式化）

功能 7：Redis 缓存机制

  • 描述：使用 Redis 缓存用户的数字格式偏好
  • 验收标准：
    1. 缓存用户数字格式偏好（number_format、decimal_places）
    2. 缓存系统默认数字格式
    3. 缓存常用数字格式列表
    4. 缓存 TTL 为 24 小时
    5. 用户切换格式时更新缓存
    6. 缓存命中率高
    7. 缓存更新及时
  • 优先级：高
  • 依赖关系：依赖功能 4（自定义格式）

功能 8：配置管理

  • 描述：在配置文件中设置系统默认数字格式
  • 验收标准：
    1. 在配置文件中设置系统默认数字格式
    2. 在配置文件中设置常用数字格式列表
    3. 配置项易于理解和修改
    4. 配置项支持热更新
    5. 配置项有默认值
  • 优先级：中
  • 依赖关系：无

功能 9：API 接口

  • 描述：提供数字格式化偏好管理的 RESTful API 接口
  • 验收标准：
    1. GET /system/user/numberFormat - 获取当前用户数字格式偏好
    2. POST /system/user/switchNumberFormat - 切换用户数字格式偏好
    3. GET /system/config/defaultNumberFormat - 获取系统默认数字格式
    4. GET /system/config/commonNumberFormats - 获取常用数字格式列表
    5. API 接口符合 RESTful 规范
    6. API 接口有完整的错误处理
    7. API 接口有完整的日志记录
  • 优先级：高
  • 依赖关系：依赖功能 7（Redis 缓存机制）、功能 8（配置管理）

非功能需求

性能需求

  • 格式化时间：数字格式化时间 < 1ms
  • 缓存命中率：Redis 缓存命中率 ≥ 90%
  • 响应时间：API 接口响应时间 < 100ms

兼容性需求

  • Spring Boot 版本：3.5.7
  • Java 版本：21
  • 国际化库：使用 Java 内置的 NumberFormat 和 DecimalFormat
  • Redis 版本：支持 Redis 6.0+

可维护性需求

  • 代码可读性：代码符合项目编码规范，注释完整
  • 测试覆盖率：单元测试覆盖率 ≥ 80%，集成测试覆盖率 ≥ 60%
  • 日志记录：完整的日志记录，包括格式化操作、缓存操作、API 调用

安全性需求

  • 权限控制：用户只能修改自己的数字格式偏好
  • 数据验证：对用户输入的数字格式进行验证，防止注入攻击
  • 缓存安全：Redis 缓存数据加密存储

可扩展性需求

  • 格式扩展：支持未来扩展新的数字格式
  • 地区扩展：支持未来扩展新的地区格式
  • 功能扩展：支持未来扩展新的格式化功能（如：科学计数法）

数据需求

数据依赖

  • 依赖用户语言偏好表（sys_user_lang）
  • 依赖用户表（sys_user）- 需要扩展字段

数据库设计

需要在 sys_user 表中添加以下字段：

  • number_format VARCHAR(50) - 用户数字格式（如：COMMA、DOT、SPACE）
  • decimal_places INT - 用户小数位偏好（如：2、3、4）

配置文件设计

需要在配置文件中添加以下配置项：

  • system.default.number.format - 系统默认数字格式
  • system.default.decimal.places - 系统默认小数位
  • system.common.number.formats - 常用数字格式列表

缓存设计

需要在 Redis 中缓存以下数据：

  • sys:number:format:{userId} - 用户数字格式偏好（24 小时 TTL）
  • sys:number:format:default - 系统默认数字格式（24 小时 TTL）
  • sys:number:formats:common - 常用数字格式列表（24 小时 TTL）

数据流转需求

数字格式化流程
  ├─ 读取用户数字格式偏好
  │  ├─ 从 Redis 缓存读取（优先）
  │  ├─ 从数据库读取（缓存未命中）
  │  └─ 写入 Redis 缓存
  ├─ 读取系统默认数字格式
  │  ├─ 从 Redis 缓存读取（优先）
  │  ├─ 从配置文件读取（缓存未命中）
  │  └─ 写入 Redis 缓存
  ├─ 读取常用数字格式列表
  │  ├─ 从 Redis 缓存读取（优先）
  │  ├─ 从配置文件读取（缓存未命中）
  │  └─ 写入 Redis 缓存
  ├─ 根据用户数字格式偏好格式化数字
  │  ├─ 使用 NumberFormat 进行标准格式化
  │  ├─ 使用 DecimalFormat 进行自定义格式化
  │  └─ 支持多语言数字显示
  └─ 返回格式化后的数字

业务规则

  1. 地区偏好优先级：用户地区偏好优先于系统默认格式
  2. 格式化准确性：数字格式化必须准确无误
  3. 四舍五入：数字小数位四舍五入
  4. 自定义格式权限：所有用户都可以自定义数字格式
  5. 缓存优先级：优先从 Redis 缓存读取数据，缓存未命中时从数据库或配置文件读取
  6. AOP 切面顺序：NumberFormatAspect 切面应该在时区转换切面之后执行
  7. 线程安全：NumberFormat 和 DecimalFormat 是线程安全的，可以在多线程环境下安全使用
  8. 格式验证：用户输入的数字格式必须经过验证，防止注入攻击

技术约束

  1. Spring Boot 版本：3.5.7
  2. Java 版本：21
  3. 数字格式化库：使用 Java 内置的 NumberFormat 和 DecimalFormat
  4. 缓存技术：使用 Redis 6.0+
  5. AOP 框架：使用 Spring AOP
  6. 必须使用现有的认证授权机制：不能引入新的认证方式
  7. 必须使用现有的缓存机制：不能引入新的缓存方式
  8. 必须使用现有的数据库连接池：不能引入新的数据库连接池

成功标准

  1. 支持千分位分隔符
  2. 支持小数位格式化
  3. 支持自动选择格式
  4. 支持自定义格式
  5. 支持后端数字格式化（NumberFormat 和 DecimalFormat）
  6. 支持 AOP 自动格式化
  7. 支持 Redis 缓存机制
  8. 支持配置管理
  9. 支持 RESTful API 接口
  10. 数字格式化时间 < 1ms
  11. Redis 缓存命中率 ≥ 90%
  12. API 接口响应时间 < 100ms
  13. 单元测试覆盖率 ≥ 80%
  14. 集成测试覆盖率 ≥ 60%

风险评估

风险 影响程度 发生概率 缓解措施
数字格式化错误 中 低 使用成熟的 Java 内置库，充分测试
地区识别错误 低 低 实现地区识别验证机制
缓存一致性 中 中 实现缓存更新机制，定期检查缓存一致性
性能问题 中 低 使用 Redis 缓存，优化格式化算法
AOP 切面顺序错误 高 低 明确切面顺序，充分测试
线程安全问题 中 低 使用线程安全的 NumberFormat 和 DecimalFormat
数据库字段冲突 中 低 在数据库设计阶段充分评估字段命名
API 接口安全问题 高 低 实现权限控制，数据验证，防止注入攻击

依赖关系

  • 依赖用户语言偏好表
  • 依赖用户表（sys_user）- 需要扩展字段
  • 依赖现有的 Spring Boot 框架
  • 依赖现有的认证授权机制
  • 依赖现有的缓存机制（Redis）
  • 依赖现有的数据库连接池
  • 依赖时区转换功能（AOP 切面顺序）

相关文档