kris/datai

Fork 0

Kris 3d290a8dd1 feat：归档当前所有文件

2026-01-28 18:23:25 +08:00

19 KiB

Raw Permalink Blame History

项目国际化需求

元数据

需求编号：2026-01-21-002
创建时间：2026-01-21
创建人：SSOT 架构师
状态：进行中
优先级：高

需求概述

实现项目的全面国际化功能，支持前端、后端、数据库三层国际化，支持中文和英文两种语言，通过 i18n 框架实现，支持时区国际化以及货币、日期、数字格式化，采用分阶段实施策略。国际化资源文件采用集中式管理，支持按需加载，资源键采用点号分隔。语言切换为全局生效，前端自动检测用户语言类型，支持快捷键切换。系统默认使用中文，语言偏好保存在后端用户表，所有用户都可以切换语言，为未来扩展更多语言奠定基础。

目标

全面国际化：实现前端、后端、数据库三层国际化，确保系统各层面都支持多语言
语言支持：初期支持中文和英文两种语言，为未来扩展更多语言奠定基础
框架集成：使用 i18n 框架实现国际化，遵循业界最佳实践
资源管理：国际化资源文件采用集中式管理，支持按需加载，资源键采用点号分隔
语言切换：语言切换为全局生效，前端自动检测用户语言类型，支持快捷键切换
语言偏好：系统默认使用中文，语言偏好保存在后端用户表，所有用户都可以切换语言
时区支持：支持时区国际化，确保时间显示符合用户所在时区
格式化支持：支持货币、日期、数字的格式化，符合不同地区的显示习惯
分阶段实施：采用分阶段实施策略，降低实施风险，确保质量

业务上下文

当前问题

系统当前只支持中文，无法满足国际化用户的需求
前端界面、后端消息、数据库数据都未实现国际化
时间、货币、日期、数字格式固定，无法根据用户地区自动调整
缺乏语言切换功能，用户体验不佳

业务场景

国际化支持
├─ 前端国际化
│  ├─ 界面元素：按钮、菜单、标签、提示信息等
│  ├─ 表单验证：错误提示、必填项提示等
│  └─ 动态内容：表格列名、状态显示等
├─ 后端国际化
│  ├─ 错误消息：系统异常、业务异常等
│  ├─ 日志消息：操作日志、系统日志等
│  ├─ 验证消息：参数校验、业务校验等
│  └─ 通知消息：邮件、短信、站内信等
├─ 数据库国际化
│  ├─ 字典数据：字典项名称、字典项说明等
│  ├─ 系统配置：配置项名称、配置项说明等
│  └─ 菜单数据：菜单名称、菜单提示等
└─ 格式化支持
   ├─ 时区支持：根据用户时区显示时间
   ├─ 货币格式：根据用户地区显示货币
   ├─ 日期格式：根据用户地区显示日期
   └─ 数字格式：根据用户地区显示数字

应用场景

多语言用户：不同国家和地区的用户使用系统，需要显示不同语言
跨国企业：跨国企业的员工使用系统，需要支持多种语言
国际化部署：系统部署到不同国家，需要支持当地语言
数据展示：不同地区用户需要看到符合当地习惯的数据格式

涉众分析

角色	需求	影响
系统管理员	能够配置系统支持的语言，管理国际化资源	降低运维成本，提高系统灵活性
开发人员	使用统一的国际化框架，快速实现国际化功能	降低开发复杂度，提高开发效率
最终用户	能够切换语言，看到符合自己语言习惯的界面	提升用户体验，提高用户满意度
运维人员	能够监控系统国际化状态，快速定位问题	提高系统可维护性，减少故障时间

功能需求

核心功能

功能 1：前端国际化

描述：实现前端界面的国际化，支持界面元素、表单验证、动态内容的国际化
验收标准：
1. 支持中文和英文两种语言
2. 支持语言切换功能，切换后立即生效
3. 所有界面元素（按钮、菜单、标签、提示信息）都支持国际化
4. 表单验证消息支持国际化
5. 动态内容（表格列名、状态显示）支持国际化
6. 语言偏好保存在用户配置中，下次登录自动应用
优先级：高
依赖关系：依赖后端国际化接口

功能 2：后端国际化

描述：实现后端的国际化，支持错误消息、日志消息、验证消息、通知消息的国际化
验收标准：
1. 支持中文和英文两种语言
2. 所有错误消息支持国际化
3. 所有日志消息支持国际化
4. 所有验证消息支持国际化
5. 所有通知消息（邮件、短信、站内信）支持国际化
6. 使用 Spring MessageSource 实现
7. 支持根据用户语言偏好返回对应语言的消息
优先级：高
依赖关系：无

功能 3：数据库国际化

描述：实现数据库数据的国际化，支持字典数据、系统配置、菜单数据的国际化
验收标准：
1. 支持中文和英文两种语言
2. 字典数据支持国际化（字典项名称、字典项说明）
3. 系统配置支持国际化（配置项名称、配置项说明）
4. 菜单数据支持国际化（菜单名称、菜单提示）
5. 国际化数据存储在独立表中，便于管理
6. 支持根据用户语言偏好查询对应语言的数据
优先级：高
依赖关系：依赖数据库表结构设计

功能 4：时区国际化

描述：支持时区国际化，根据用户时区显示时间
验收标准：
1. 支持用户设置时区偏好
2. 所有时间显示根据用户时区自动转换
3. 支持常用时区（如：UTC+8、UTC-5 等）
4. 时区偏好保存在用户配置中
5. 支持系统默认时区配置
优先级：高
依赖关系：无

功能 5：货币格式化

描述：支持货币格式化，根据用户地区显示货币
验收标准：
1. 支持常用货币符号（如：¥、$、€ 等）
2. 支持货币小数位格式化
3. 支持货币千分位分隔符
4. 根据用户地区偏好自动选择货币格式
5. 支持自定义货币格式
优先级：中
依赖关系：无

功能 6：日期格式化

描述：支持日期格式化，根据用户地区显示日期
验收标准：
1. 支持常用日期格式（如：YYYY-MM-DD、DD/MM/YYYY、MM/DD/YYYY 等）
2. 支持日期时间格式化
3. 支持短日期和长日期格式
4. 根据用户地区偏好自动选择日期格式
5. 支持自定义日期格式
优先级：中
依赖关系：无

功能 7：数字格式化

描述：支持数字格式化，根据用户地区显示数字
验收标准：
1. 支持数字千分位分隔符（如：,、. 等）
2. 支持数字小数位格式化
3. 根据用户地区偏好自动选择数字格式
4. 支持自定义数字格式
优先级：中
依赖关系：无

次要功能

功能 8：语言管理

描述：提供语言管理功能，支持添加、编辑、删除语言
验收标准：
1. 支持添加新语言
2. 支持编辑语言信息
3. 支持删除语言（删除前检查是否被使用）
4. 支持设置系统默认语言
5. 支持启用/停用语言
优先级：中
依赖关系：依赖数据库国际化

功能 9：国际化资源管理

描述：提供国际化资源管理功能，支持添加、编辑、删除国际化资源
验收标准：
1. 支持添加国际化资源（键值对）
2. 支持编辑国际化资源
3. 支持删除国际化资源
4. 支持按语言、模块筛选资源
5. 支持批量导入导出资源
优先级：低
依赖关系：依赖后端国际化

非功能需求

性能需求

响应时间：语言切换响应时间 < 500ms
加载时间：国际化资源加载时间 < 1s
内存占用：国际化资源内存占用 < 10MB
并发用户数：支持 1000+ 并发用户

安全需求

认证方式：使用现有的 Spring Security 认证机制
授权机制：只有管理员权限才能管理语言和国际化资源
数据安全：国际化资源数据加密存储
审计日志：记录语言和国际化资源变更日志

可用性需求

系统可用性：99.9%
容错机制：国际化资源缺失时显示默认语言
灾备方案：国际化资源损坏时使用备用资源

兼容性需求

浏览器兼容性：支持主流浏览器（Chrome、Firefox、Edge、Safari）
操作系统兼容性：支持 Windows、Linux、macOS
框架兼容性：兼容现有的 Spring Boot 3.5.7 框架

可扩展性需求

扩展方式：支持新增语言，无需修改代码
资源扩展：支持新增国际化资源，无需重启应用
格式扩展：支持新增格式化规则，无需修改代码

可维护性需求

代码可读性：代码符合项目编码规范，注释完整
文档完整性：提供完整的使用文档和 API 文档
测试覆盖率：单元测试覆盖率 ≥ 80%

数据需求

数据模型

sys_language（语言表）

sys_language (语言表)
├─ id (BIGINT) - 主键ID
├─ lang_code (VARCHAR) - 语言代码（如：zh、en）
├─ lang_name (VARCHAR) - 语言名称（如：中文、English）
├─ lang_name_en (VARCHAR) - 语言英文名称（如：Chinese、English）
├─ lang_flag (VARCHAR) - 语言图标
├─ is_default (CHAR) - 是否默认语言（0否 1是）
├─ status (CHAR) - 状态（0正常 1停用）
├─ sort_order (INT) - 排序
├─ create_by (VARCHAR) - 创建者
├─ create_time (DATETIME) - 创建时间
├─ update_by (VARCHAR) - 更新者
└─ update_time (DATETIME) - 更新时间

sys_i18n_resource（国际化资源表）

sys_i18n_resource (国际化资源表)
├─ id (BIGINT) - 主键ID
├─ lang_code (VARCHAR) - 语言代码（如：zh、en）
├─ module_name (VARCHAR) - 模块名称
├─ resource_key (VARCHAR) - 资源键
├─ resource_value (TEXT) - 资源值
├─ create_by (VARCHAR) - 创建者
├─ create_time (DATETIME) - 创建时间
├─ update_by (VARCHAR) - 更新者
└─ update_time (DATETIME) - 更新时间

sys_user_lang（用户语言偏好表）

sys_user_lang (用户语言偏好表)
├─ id (BIGINT) - 主键ID
├─ user_id (BIGINT) - 用户ID
├─ lang_code (VARCHAR) - 语言代码（如：zh、en）
├─ timezone (VARCHAR) - 时区（如：Asia/Shanghai、America/New_York）
├─ date_format (VARCHAR) - 日期格式（如：yyyy-MM-dd、MM/dd/yyyy）
├─ number_format (VARCHAR) - 数字格式（如：#,##0.00、#.##0,00）
├─ currency_format (VARCHAR) - 货币格式（如：¥#,##0.00、$#,##0.00）
├─ create_by (VARCHAR) - 创建者
├─ create_time (DATETIME) - 创建时间
├─ update_by (VARCHAR) - 更新者
└─ update_time (DATETIME) - 更新时间

数据存储需求

数据库类型：MySQL 8.3.0
存储容量：单表支持 1000 万+ 数据
数据备份策略：每日备份，保留 7 天

数据流转需求

用户登录
  └─ 读取用户语言偏好
  └─ 加载对应语言的国际化资源
  └─ 显示对应语言的界面

语言切换
  └─ 用户选择新语言
  └─ 更新用户语言偏好
  └─ 重新加载国际化资源
  └─ 刷新界面显示

国际化资源管理
  └─ 管理员添加/编辑/删除国际化资源
  └─ 更新数据库中的国际化资源
  └─ 刷新国际化资源缓存

业务规则

语言代码唯一性：语言代码（lang_code）必须唯一
资源键唯一性：同一语言下，资源键（resource_key）必须唯一
默认语言唯一性：只能有一个默认语言，系统默认使用中文（zh-CN）
用户语言偏好：每个用户只能有一个语言偏好，保存在后端用户表（sys_user_lang）
资源缺失处理：国际化资源缺失时，显示默认语言的资源
语言切换权限：所有用户都可以切换语言，语言切换为全局生效
语言管理权限：只有管理员权限才能管理语言和国际化资源
资源管理方式：国际化资源文件采用集中式管理
资源加载策略：支持按需加载国际化资源
资源命名规范：国际化资源键采用点号分隔（如 common.confirm、login.username）
语言切换方式：前端自动检测用户语言类型，支持快捷键切换（Ctrl + Shift + L）
语言扩展性：为未来扩展更多语言奠定基础

国际化资源管理

前端国际化资源管理

资源文件结构：集中式管理

src/
└── locales/
    ├── zh-CN.json  # 中文资源
    └── en-US.json  # 英文资源

资源加载策略：按需加载（懒加载）
资源命名规范：使用点号分隔（如 common.confirm、login.username）

资源示例：

{
  "common": {
    "confirm": "确定",
    "cancel": "取消",
    "save": "保存",
    "delete": "删除"
  },
  "login": {
    "title": "系统登录",
    "username": "用户名",
    "password": "密码"
  }
}

后端国际化资源管理