技术	版本	用途
Vue 3	3.x	响应式前端框架，提供 Composition API。
TypeScript	5.x	静态类型检查，提高代码质量。
Vite	5.x	现代化前端构建工具，提供快速的开发体验。
Pinia	2.x	Vue 3 官方状态管理库。
Vue Router	4.x	Vue 官方路由管理库。
Tailwind CSS	3.x	实用优先的 CSS 框架，提高样式开发效率。
Shadcn UI	最新	可定制的 UI 组件库，基于 Tailwind CSS。
pnpm	10.x	高效的包管理器，支持 Monorepo 结构。
Axios	1.x	HTTP 客户端，用于 API 请求。
Echarts	5.x	数据可视化库。

3. Monorepo 结构

Tagtag Starter 前端采用 Monorepo 结构管理代码，使用 pnpm 作为包管理器。这种结构的优势包括：

3.1 代码共享

多个应用可以共享组件、工具类和配置，减少重复代码。

3.2 统一依赖管理

所有应用使用相同版本的依赖，避免版本冲突。

3.3 统一构建工具

共享构建配置和脚本，提高开发效率。

3.4 更好的协作

团队成员可以更方便地共享和复用代码。

3.5 简化版本管理

统一版本号管理，简化发布流程。

4. 目录结构

注意：以下描述均在 cd frontend 后的目录结构基础上进行说明。

frontend
├── apps                  # 应用层
│   └── tagtag            # 主应用
│       ├── public        # 静态资源
│       └── src           # 源代码
├── packages              # 核心包层
│   ├── @core             # 核心共享库
│   │   ├── base          # 基础设计系统、图标和共享工具
│   │   ├── composables   # 通用组合式函数
│   │   ├── preferences   # 应用偏好设置管理
│   │   └── ui-kit        # UI 组件库
│   ├── constants         # 常量定义
│   └── effects           # 业务副作用与逻辑封装
└── internal              # 内部工具层
    ├── lint-configs      # 代码规范配置
    ├── node-utils        # Node.js 工具函数
    ├── tailwind-config   # Tailwind CSS 配置
    ├── tsconfig          # TypeScript 配置文件
    └── vite-config       # Vite 构建配置

5. 核心模块

5.1 应用层 (`apps`)

包含具体的应用实现，每个子目录对应一个独立的前端应用。

5.1.1 主应用 (`apps/tagtag`)

核心组件：

src/api/: API 请求定义和封装
- core/: 核心 API（认证、用户、菜单）
- modules/: 模块 API（IAM、系统、存储）
- request.ts: Axios 实例配置
src/views/: 页面视图组件
- _core/: 核心页面（登录、个人中心、404 等）
- dashboard/: 仪表盘页面
- modules/: 模块页面（IAM、系统、存储）
src/router/: 路由配置
- routes/: 路由定义
- access.ts: 路由守卫
- guard.ts: 权限守卫
src/store/: Pinia 状态管理
- auth.ts: 认证状态管理
src/layouts/: 布局组件
- auth.vue: 认证布局
- basic.vue: 基础布局
src/components/: 业务组件
src/locales/: 国际化配置
- langs/: 语言包

5.2 核心包层 (`packages`)

提供可复用的核心功能和组件，供应用层使用。

子模块：

5.2.1 核心共享库 (`packages/@core`)

子模块：

base: 基础设计系统、图标和共享工具
- design/: 设计系统和设计令牌
- icons/: 图标库
- shared/: 共享工具类
- typings/: 类型定义
composables: 通用组合式函数
- use-is-mobile.ts: 移动端检测
- use-layout-style.ts: 布局样式管理
- use-namespace.ts: 命名空间管理
- use-scroll-lock.ts: 滚动锁定管理
- use-sortable.ts: 排序功能
preferences: 应用偏好设置管理
- 主题设置
- 布局设置
- 其他用户偏好
ui-kit: 封装的 UI 组件库
- shadcn-ui: 基于 Shadcn UI 的基础组件
- form-ui: 表单组件封装
- layout-ui: 布局组件封装
- popup-ui: 弹窗、抽屉等组件封装
- tabs-ui: 标签页组件封装
- menu-ui: 菜单组件封装

5.2.2 常量定义 (`packages/constants`)

核心常量定义
业务常量定义

5.2.3 业务副作用与逻辑封装 (`packages/effects`)

access: 权限控制逻辑
- 权限指令
- 权限组件
- 权限管理
common-ui: 通用 UI 组件
- 关于页面
- fallback 页面
- 个人中心组件
hooks: 通用 Hooks
- use-app-config.ts: 应用配置管理
- use-content-maximize.ts: 内容最大化管理
- use-design-tokens.ts: 设计令牌管理
- use-hover-toggle.ts: 悬停切换管理
- use-pagination.ts: 分页管理
- use-refresh.ts: 刷新功能
- use-tabs.ts: 标签页管理
- use-watermark.ts: 水印功能
layouts: 布局组件
- 基础布局
- 认证布局
- iframe 布局
plugins: 第三方插件集成
- echarts: ECharts 图表集成
- motion: 动画集成
- vxe-table: 表格集成

5.3 内部工具层 (`internal`)

提供构建、开发和维护所需的工具和配置。

核心组件：

lint-configs/: ESLint, Prettier, Stylelint 等代码规范配置
node-utils/: Node.js 工具函数
tailwind-config/: Tailwind CSS 配置封装
tsconfig/: TypeScript 配置文件
- base.json: 基础 TypeScript 配置
- library.json: 库 TypeScript 配置
- node.json: Node.js TypeScript 配置
- web-app.json: Web 应用 TypeScript 配置
- web.json: Web TypeScript 配置
vite-config/: Vite 构建配置封装
- 应用配置
- 库配置
- 插件配置

6. 数据流设计

6.1 状态管理

使用 Pinia 进行状态管理，将应用状态划分为多个模块，每个模块负责一个独立的功能域。

状态管理流程：

组件通过 useStore 钩子获取状态
组件调用 action 修改状态
Action 可以调用 API 获取数据
Mutation 修改状态（在 Pinia 中，action 可以直接修改状态）
状态变化触发组件重新渲染

6.2 API 请求流程

组件调用 API 函数
API 函数使用封装的 Axios 实例发送请求
请求拦截器添加认证信息和其他头部
后端处理请求，返回响应
响应拦截器处理响应，统一处理错误
API 函数返回响应数据
组件处理响应数据，更新状态或 UI

6.3 路由流程

用户访问某个路由
路由守卫检查用户权限
权限通过后，加载对应的组件
组件获取数据，渲染页面

7. 权限控制

Tagtag Starter 前端实现了基于角色的权限控制（RBAC），包括：

7.1 路由权限

动态路由生成：根据用户角色生成可访问的路由
路由守卫：检查用户是否有权限访问某个路由

7.2 组件权限

权限指令：使用 v-access 指令控制组件的显示和隐藏
权限组件：使用 AccessControl 组件控制子组件的显示和隐藏

7.3 按钮权限

按钮权限指令：使用 v-access 指令控制按钮的显示和隐藏

8. 国际化支持

Tagtag Starter 前端支持多语言切换，使用 Vue I18n 实现。

国际化配置：

src/locales/langs/: 语言包文件
src/locales/index.ts: 国际化配置

使用方式：

<template>
  <div>{{ $t('common.save') }}</div>
</template>

<script setup lang="ts">
import { useI18n } from 'vue-i18n'
const { t } = useI18n()
</script>