kris/datai-vue
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai-vue/docs/sessions/2026-01-26-002-01-session.md

36 KiB
Raw Permalink Blame History

会话记录

元数据

  • 需求编号：2026-01-26-002-01
  • 开始时间：2026-01-26
  • 结束时间：2026-01-26
  • 当前阶段：阶段 9：闭环复盘和接口文档
  • 状态：已完成

需求澄清与优化记录

1. 初始拆分

基于总需求文档拆分出基础架构子需求。

2. 项目现状深度扫描 (Optimization 1)

扫描时间：2026-01-26 扫描结果：

  1. 依赖缺失：package.json 中未安装 vue-i18n。
  2. 存储机制：src/store/modules/app.ts 和 src/utils/auth.ts 均使用 localStorage，确认沿用此机制存储语言偏好。
  3. 组件缺失：项目无 LangSelect 组件，参考 src/components/SizeSelect 现有实现进行封装。
  4. 布局结构：src/layout/components/Navbar/index.vue 的 .right-menu 区域适合放置语言切换入口。
  5. 图标资源：src/assets/icons/svg/language.svg 已存在，可直接使用。

3. 后端 API 深度扫描 (Optimization 2)

扫描时间：2026-01-26 API 分析结果：

  1. 语言列表 (/system/language/list)：返回 langCode (如 zh-CN) 和 langName，可作为未来 LangSelect 的动态数据源。
  2. 用户偏好 (/system/i18n/currentLocale)：返回 langCode 为 zh_CN (下划线)，与前端标准 zh-CN (连字符) 不一致。
  3. 资源列表 (/system/i18nresource/list)：使用 langCode=zh-CN 参数。
  4. Header：后端支持 Accept-Language: zh-CN。

4. 需求文档二次修订

根据 API 扫描结果，对需求文档进行了补充：

  • 格式规范：明确前端使用 zh-CN，后端可能返回 zh_CN，需在对接层进行归一化处理。
  • 组件扩展：LangSelect 组件预留 API 数据源接入设计。
  • 网络适配：明确 Accept-Language 请求头使用 zh-CN 格式。

生成的文档

阶段 2：方案设计

关键设计决策

  1. 技术栈选择：

    • 使用 vue-i18n@9 作为核心国际化库，支持 Vue 3 Composition API
    • 利用现有 Pinia 状态管理，在 app.ts 中新增 language 状态
    • 利用现有 Axios 拦截器，自动注入 Accept-Language 请求头

  2. 架构设计：

    • 采用模块化设计，核心模块包括：i18n 实例、Store 状态、网络拦截器、资源目录、UI 组件
    • 数据流设计清晰：初始化流程、语言切换流程、API 请求流程
    • 与若依框架深度集成，遵循项目现有规范

  3. 组件设计：

    • LangSelect 组件参考 SizeSelect 实现，使用 el-dropdown 下拉菜单
    • 集成到 Navbar 的 .right-menu 区域，添加 Tooltip 提示
    • 预留接口，未来可替换为 GET /system/language/list 动态数据源

  4. 持久化策略：

    • 使用 localStorage 存储 language 键值
    • Store 的 setLanguage action 负责同步更新 localStorage、i18n 实例和 DOM 属性

  5. 格式规范：

    • 前端统一使用 zh-CN 格式（连字符）
    • 后端已确认支持 Accept-Language: zh-CN 格式
    • 后续对接 currentLocale 接口时，需在前端层进行格式转换（zh_CN -> zh-CN）

生成的文档

阶段 3：方案决策

关键决策内容

决策 1：选择 vue-i18n@9 作为核心国际化库

选择理由：

  • Vue 3 官方推荐，与 Vue 3 生态深度集成
  • 完美支持 Composition API，符合项目开发规范
  • 提供完整的 TypeScript 类型定义
  • 社区活跃度高，文档丰富
  • 性能优秀，支持懒加载和按需加载
  • 与 Element Plus 的国际化方案兼容良好

决策 2：使用 Pinia 进行状态管理

选择理由：

  • 项目已使用 Pinia，无需引入新的依赖
  • 与若依框架保持技术栈一致性
  • 开发人员熟悉，学习成本低
  • 性能优于 Vuex，支持 TypeScript
  • 与 Vue 3 Composition API 集成良好

决策 3：采用静态资源为主、预留动态资源的混合策略

选择理由：

  • 静态资源实现简单，可快速完成基础架构搭建
  • 无需网络请求，加载速度快
  • 不依赖后端接口，稳定性高
  • 预留动态资源加载接口，未来可无缝升级
  • 符合渐进式增强原则

决策 4：统一使用 zh-CN 格式（连字符）

选择理由：

  • 符合 RFC 4646 语言标签标准（BCP 47）
  • 浏览器原生支持 zh-CN 格式的 Accept-Language 请求头
  • 后端 API 文档确认支持 zh-CN 格式
  • 与 Element Plus 的 locale 命名规范一致
  • 统一格式减少混淆和错误

替代方案分析

  1. vue-i18n@8（Legacy 模式）：兼容 Vue 2，但不支持 Composition API，性能不如 v9
  2. Vuex 状态管理：社区成熟，但与项目现有技术栈不一致，性能不如 Pinia
  3. 完全动态资源加载：资源集中管理，但依赖后端接口，稳定性差，开发复杂度高
  4. zh_CN 格式（下划线）：与后端接口返回格式一致，但不符合国际标准，浏览器兼容性差

生成的文档

阶段 4：数据库结构生成

数据库变更分析

分析结果：不涉及数据库变更

分析理由：

  1. 前端需求：本需求为前端国际化基础架构，主要涉及前端代码实现

  2. 主要变更内容：

    • 安装 vue-i18n 库（npm 依赖）
    • 创建国际化资源目录和文件（src/locales/）
    • 修改 Store 状态管理（src/store/modules/app.ts）
    • 修改 Axios 拦截器（src/utils/request.ts）
    • 创建 LangSelect 组件（src/components/LangSelect/）
    • 修改 Navbar 组件（src/layout/components/Navbar/）

  3. 后端数据库变更：

    • 语言列表表、国际化资源表等数据库变更应由后端需求负责
    • 用户语言偏好字段等数据库变更应由后端需求负责
    • 前端需求不涉及后端数据库表结构的创建或修改

  4. 存储机制：

    • 前端使用 localStorage 存储语言偏好（非数据库）
    • 不涉及数据库的增删改查操作

结论：本需求不涉及数据库变更，跳过此阶段，直接进入阶段 5（提示词生成）。

阶段 5：提示词生成

提示词内容摘要

1. 引用真源

  • 需求文档：docs/requirements/2026-01-26-002-01-前端国际化-基础架构.md
  • 设计文档：docs/design/2026-01-26-002-01-前端国际化-基础架构-设计.md
  • 决策记录：docs/decisions/2026-01-26-002-01-ADR-前端国际化技术选型与架构决策.md

2. 需求描述

实现前端国际化基础架构，包括：

  • 核心库集成（vue-i18n@9）
  • 目录结构规范（src/locales/）
  • 状态管理（Store）
  • 语言切换组件（LangSelect）
  • Navbar 集成
  • 网络层适配（Axios 拦截器）
  • Element Plus 适配

3. 设计方案

  • 核心库：vue-i18n@9（Composition API 模式）
  • 状态管理：Pinia（在 app.ts 中新增 language 状态）
  • 网络拦截器：Axios（自动注入 Accept-Language 请求头）
  • UI 组件：Element Plus（ElConfigProvider 包裹、el-dropdown 下拉菜单）
  • 持久化策略：localStorage 存储 language 键值
  • 格式规范：统一使用 zh-CN 格式（连字符）
  • 资源策略：静态资源为主，预留动态资源加载接口

4. 输出格式要求

必须包含以下文件：

  • 依赖安装：npm install vue-i18n@9
  • 国际化资源文件：src/locales/index.ts、zh-CN.ts、en-US.ts
  • 状态管理文件：src/store/modules/app.ts（新增 language 状态和 setLanguage action）
  • 组件文件：src/components/LangSelect/index.vue
  • 布局文件：src/layout/components/Navbar/index.vue
  • 网络请求文件：src/utils/request.ts
  • 根组件文件：src/App.vue

5. 代码规范要求

  • 命名规范：组件命名（PascalCase）、文件命名（kebab-case）、变量命名（camelCase）
  • TypeScript 规范：必须添加类型注解、使用 interface 或 type 定义复杂类型
  • Vue 3 规范：必须使用 Composition API、