datai/docs/archive/sessions/2026-01-25-002-05-session.md

会话记录：货币格式化功能

元数据

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

执行阶段

阶段 1：需求定义

• 状态：已完成
• 生成文档：需求文档
• 关键决策：
  • 扩展 sys_user 表，添加 currency_code 字段
  • 支持用户级别的货币偏好覆盖系统默认设置
  • 在配置文件中设置系统默认货币
  • 在后端返回数据时进行格式化，通过 AOP 在 Service 层统一处理
  • 需要支持多货币显示
  • 需要实时汇率转换
  • 后端使用 java.text.DecimalFormat
  • 不考虑性能、安全性等问题

阶段 2：方案设计

• 状态：已完成
• 生成文档：设计文档
• 关键设计决策：
  • 使用 Java DecimalFormat 进行货币格式化
  • 使用 Redis 缓存汇率数据，提高性能
  • 货币格式化在 Service 层进行，使用 AOP 切面拦截响应
  • 货币优先级：用户 > 系统
  • 汇率数据存储在数据库中，支持手动更新和 API 自动更新
  • 所有金额字段使用 BigDecimal 类型
  • 缓存策略：汇率缓存（TTL = 60 分钟）、货币列表缓存（TTL = 24 小时）、默认货币缓存（TTL = 24 小时）

阶段 3：方案决策

• 状态：已完成
• 生成文档：决策记录
• 关键决策：
  • 决策 1：货币格式化技术选择 - Java DecimalFormat
    • 理由：Java 内置、无需额外依赖、功能完整、性能优秀、成熟稳定、与框架兼容
    • 放弃方案：Joda-Money 库（需要额外依赖）、自定义格式化实现（维护成本高）
  • 决策 2：缓存策略选择 - Redis 缓存
    • 理由：已集成、性能优秀、分布式支持、自动过期、数据结构丰富、支持持久化
    • 缓存策略：汇率缓存（TTL = 60 分钟）、货币列表缓存（TTL = 24 小时）、默认货币缓存（TTL = 24 小时）
    • 放弃方案：Caffeine 本地缓存（无法在分布式环境下共享）、数据库缓存（性能较差、无法自动过期）
  • 决策 3：货币格式化层选择 - Service 层格式化 + AOP 切面拦截
    • 理由：统一处理、AOP 切面自动格式化、业务逻辑分离、易于维护、性能优化
    • 实现方案：使用 @Around 切面拦截 Service 方法返回值，提供 @CurrencyFormat 注解
    • 放弃方案：Controller 层格式化（职责过重、代码重复）、数据库层格式化（违反分层架构、兼容性差）
  • 决策 4：货币优先级策略选择 - 双级优先级策略（用户 > 系统）
    • 理由：灵活性高、用户体验好、系统默认、易于扩展
    • 优先级规则：用户货币 > 系统货币 > 硬编码默认（CNY）
    • 放弃方案：单级优先级（仅用户货币/仅系统货币）- 灵活性不足

阶段 4：数据库结构

• 状态：已完成
• 生成文档：SQL 脚本
• 数据库变更：
  • 创建新表：sys_exchange_rate（汇率表）
    • 字段：id、from_currency、to_currency、rate、source、create_by、create_time、update_by、update_time、remark
    • 索引：主键索引（id）、唯一索引（from_currency, to_currency）、普通索引（source）
  • 修改现有表：sys_user（用户表）
    • 新增字段：currency_code（货币代码），默认值为 CNY
    • 新增索引：idx_currency_code（currency_code 字段）
  • 插入初始数据：
    • 插入常用货币配置（CNY、USD、EUR、GBP、JPY）

阶段 5：提示词生成

• 状态：已完成
• 生成文档：提示词文档
• 提示词内容摘要：
  • 引用真源：需求文档、设计文档、决策记录、SQL 脚本
  • 需求描述：货币格式化功能、汇率管理功能、货币优先级策略、缓存管理、自动货币格式化
  • 设计方案：Java DecimalFormat、Redis、MySQL 8.3.0、Spring Boot 3.5.7 + 若依框架、分层架构
  • 输出格式要求：
    • Entity 层：SysExchangeRate.java
    • 修改现有文件：SysUser.java（添加 currency_code 字段）
    • Utils 层：CurrencyUtils.java
    • 注解：@CurrencyFormat.java
    • Aspect 层：CurrencyFormatAspect.java（拦截 Service 方法返回值）
    • Mapper 层：SysExchangeRateMapper.java、SysExchangeRateMapper.xml
    • Service 层：ISysExchangeRateService.java、SysExchangeRateServiceImpl.java
    • Controller 层：SysExchangeRateController.java
    • 单元测试：CurrencyUtilsTest.java、SysExchangeRateServiceTest.java
  • 代码规范要求：命名规范、注释规范、代码格式、导入规范
  • 测试要求：单元测试覆盖率 ≥ 80%、测试用例场景、测试框架、测试用例命名规范、测试数据
  • 注意事项：货币格式化、缓存、权限控制、日志记录、异常处理、性能优化、安全、AOP 切面

阶段 6：代码生成

• 状态：已完成
• 生成文档：代码文档、实施方案
• 代码生成情况：
  • 代码生成器生成：
    • SysExchangeRate.java（实体类）
    • SysExchangeRateMapper.java（Mapper 接口）
    • SysExchangeRateMapper.xml（Mapper XML）
    • SysExchangeRateService.java（Service 接口基础方法）
    • SysExchangeRateServiceImpl.java（Service 实现类基础方法）
    • SysExchangeRateController.java（Controller 类基础接口）
  • 手动生成/扩展：
    • ISysExchangeRateService.java：扩展方法（getExchangeRate、convert、batchConvert、updateExchangeRate、updateExchangeRateFromApi、getAvailableCurrencies、getDefaultCurrency）
    • SysExchangeRateServiceImpl.java：实现扩展方法，包含 Redis 缓存逻辑
    • CurrencyUtils.java：货币格式化工具类（format、convert、isValidCurrencyCode、getPattern、getSymbol）
    • CurrencyConstants.java：货币常量类（货币代码、货币符号、货币格式化模式）
    • @CurrencyFormat.java：货币格式化注解
    • CurrencyFormatAspect.java：货币格式化切面（拦截 Service 方法返回值）
    • SysUser.java：添加 currency_code 字段
    • SysUserController.java：添加用户货币偏好管理接口
    • SysExchangeRateDto.java：添加汇率转换相关字段
    • CacheConstants.java：添加汇率相关缓存常量
• 关键实现：
  • 使用 AOP 切面拦截 Service 方法返回值进行货币格式化
  • Redis 缓存策略：汇率缓存 60 分钟，货币列表缓存 24 小时，默认货币缓存 24 小时
  • 递归格式化复杂对象中的 BigDecimal 字段
  • 支持多货币显示，自动转换并显示多种货币
  • 异常处理：无效货币使用默认货币，null 值安全处理
• 修复的问题：
  • CurrencyFormatAspect.java 中的 SYS_CONFIG 常量引用错误（修改为 SYS_CONFIG_KEY）
• 补充的接口：
  • GET /system/user/currency：获取当前用户货币偏好
  • POST /system/user/switchCurrency：切换用户货币偏好（已添加 @Log 注解记录审计日志）
  • POST /system/exchangeRate/convert：汇率转换
  • POST /system/exchangeRate/batchConvert：批量汇率转换
  • POST /system/exchangeRate/update：更新汇率（手动）
  • POST /system/exchangeRate/updateFromApi：更新汇率（API）
• 需求实现情况：
  • ✅ 功能 1：货币符号支持 - 已实现
  • ✅ 功能 2：小数格式化 - 已实现
  • ✅ 功能 3：千分位分隔符 - 已实现（逗号分隔符）
  • ⚠️ 功能 4：自动格式选择 - 已实现（部分）
  • ⚠️ 功能 5：自定义格式 - 已实现（部分）
  • ✅ 功能 6：多货币显示 - 已实现
  • ✅ 功能 7：AOP 自动格式化 - 已实现
  • ✅ 功能 8：用户货币偏好 - 已实现
  • ✅ 功能 9：系统默认货币 - 已实现
  • ✅ 功能 10：汇率管理 - 已实现
  • ✅ 功能 11：汇率转换 - 已实现
  • ✅ 功能 12：汇率缓存 - 已实现
  • ⚠️ 功能 13：货币优先级 - 已实现（部分，缺少租户货币支持）
• 未实现的需求：
  • 空格分隔符支持（功能 3 的部分需求）
  • 自定义千分位分隔符（功能 5 的部分需求）
  • 自定义货币符号（功能 5 的部分需求）
  • 租户货币支持（功能 13 的部分需求）
  • 单元测试
  • 性能测试

阶段 7：会话记录

• 状态：已完成
• 生成文档：当前文档（2026-01-25-002-05-session.md）
• 更新内容：
  • 更新阶段 6 的代码生成情况
  • 记录补充的接口信息
  • 记录需求实现情况
  • 记录未实现的需求

阶段 8：变更日志

• 状态：待开始
• 生成文档：待生成

阶段 9：复盘与接口

• 状态：待开始
• 生成文档：待生成

阶段 10：代码提交

• 状态：待开始
• 生成文档：待生成

关键设计决策

技术选型

1. 货币格式化技术：Java DecimalFormat

   • 理由：Java 内置，无需引入额外依赖；支持自定义格式化模式；性能优秀，格式化时间 < 10ms；成熟稳定，社区支持良好

2. 缓存技术：Redis

   • 理由：项目已集成 Redis，无需额外配置；性能优秀，响应时间 < 1ms；支持分布式部署；支持自动过期机制；丰富的数据结构支持

3. 数据库技术：MySQL 8.3.0

   • 理由：项目现有数据库；支持 BigDecimal 类型；性能优秀，支持高并发；事务支持完善

4. 框架技术：Spring Boot 3.5.7 + 若依框架

   • 理由：项目现有框架；Spring Boot 3.5.7 支持 Java 21；若依框架提供完善的权限、缓存、日志等功能；社区活跃，文档完善

架构设计

1. 系统架构：前端层（Vue 3）→ Controller 层 → Service 层 → Mapper 层 → 数据库层（MySQL 8.3.0）→ 缓存层（Redis）
2. 模块架构：
   • datai-admin（启动模块）：Controller 层
   • datai-system（系统模块）：Service 层、Mapper 层、实体类
   • datai-common（公共模块）：工具类、切面、常量
   • datai-plugins（插件模块）：Redis 缓存工具类

数据流设计

1. 用户登录流程：用户输入用户名密码 → Controller 接收登录请求 → Service 验证用户信息 → 从数据库读取用户货币偏好 → 从 Redis 缓存读取货币配置 → 将用户货币信息存储到 LoginUser → 生成 Token 并返回 → 前端存储 Token 和货币信息
2. 数据查询流程：前端发起数据查询请求 → Controller 接收请求 → Service 层从数据库读取金额数据 → AOP 切面拦截响应 → 根据用户货币格式化金额 → 返回格式化后的金额 → 前端显示格式化后的金额
3. 汇率转换流程：前端发起汇率转换请求 → Controller 接收请求 → Service 层从 Redis 缓存读取汇率 → 如果缓存未命中，从数据库读取汇率 → 返回转换后的金额 → 前端显示转换后的金额
4. 货币切换流程：用户选择新货币 → Controller 接收货币切换请求 → Service 验证货币代码有效性 → 更新用户货币偏好到数据库 → 清除 Redis 缓存 → 刷新 Token → 前端刷新页面，重新加载金额数据

数据模型设计

1. 汇率表（sys_exchange_rate）：
   • 字段：id、from_currency、to_currency、rate、source、create_by、create_time、update_by、update_time、remark
   • 索引：主键索引（id）、唯一索引（from_currency, to_currency）、普通索引（source）
2. 用户表修改（sys_user）：
   • 新增字段：currency_code（货币代码）
   • 默认值：CNY（人民币）
   • 位置：在 lang_code 字段之后

接口设计

1. 获取汇率列表：GET /system/exchangeRate/list
   • 权限要求：@PreAuthorize("@ss.hasPermi('system:exchangeRate:list')")
   • 响应数据：汇率列表（包含 id、fromCurrency、toCurrency、rate、source）
2. 获取当前用户货币偏好：GET /system/user/currency
   • 权限要求：需要登录
   • 响应数据：货币代码（如：CNY）
3. 切换货币偏好：POST /system/user/switchCurrency
   • 权限要求：需要登录
   • 请求参数：currencyCode（货币代码）
   • 响应数据：成功/失败消息
4. 汇率转换：POST /system/exchangeRate/convert
   • 权限要求：需要登录
   • 请求参数：amount（金额）、fromCurrency（源货币）、toCurrency（目标货币）
   • 响应数据：转换后的金额
5. 批量汇率转换：POST /system/exchangeRate/batchConvert
   • 权限要求：需要登录
   • 请求参数：amounts（金额列表）、fromCurrency（源货币）、toCurrency（目标货币）
   • 响应数据：转换后的金额列表
6. 更新汇率（手动）：POST /system/exchangeRate/update
   • 权限要求：@PreAuthorize("@ss.hasPermi('system:exchangeRate:edit')")
   • 请求参数：fromCurrency（源货币）、toCurrency（目标货币）、rate（汇率）
   • 响应数据：成功/失败消息
7. 更新汇率（API）：POST /system/exchangeRate/updateFromApi
   • 权限要求：@PreAuthorize("@ss.hasPermi('system:exchangeRate:edit')")
   • 响应数据：成功更新的汇率数量

实现要点

1. 关键实现逻辑：
   • 货币格式化在 Service 层进行，使用 AOP 切面拦截响应
   • 使用 CurrencyUtils 工具类进行货币格式化和转换
   • 处理 null 值，避免空指针异常
   • 处理无效货币代码，使用默认货币
   • 支持多货币显示，自动转换并显示多种货币
2. 异常处理设计：
   • 货币格式化异常：捕获异常，记录日志，返回原始金额，提示用户货币格式化失败
   • 货币代码无效异常：捕获异常，记录日志，返回错误响应，提示用户货币代码无效
   • 缓存读取异常：捕获异常，记录日志，从数据库重新加载数据，提示用户缓存读取失败
   • 汇率转换异常：捕获异常，记录日志，返回原始金额，提示用户汇率转换失败
3. 性能优化设计：
   • 缓存优化：使用 Redis 缓存汇率数据，汇率缓存 60 分钟，货币列表缓存 24 小时，默认货币缓存 24 小时
   • 索引优化：为常用查询字段创建索引，提高查询性能
   • 批量转换优化：批量转换时使用并行处理，合理设置线程池大小
4. 安全设计：
   • 数据验证：验证货币代码有效性、格式、白名单
   • 权限控制：使用 @PreAuthorize 注解控制接口权限，使用数据权限控制数据访问范围
   • 审计日志：使用 @Log 注解记录操作日志，记录操作人、操作时间、操作内容

相关文档

• 需求文档
• 设计文档
• 决策记录
• SQL 脚本
• 提示词文档
• 代码文档
• 实施方案