diff --git a/docs/SRC-STRUCTURE.md b/docs/SRC-STRUCTURE.md new file mode 100644 index 0000000..0758bdc --- /dev/null +++ b/docs/SRC-STRUCTURE.md @@ -0,0 +1,592 @@ +# src 目录结构说明 + +> 本文档详细说明了项目 src 目录下所有文件和文件夹的作用 + +## 📁 目录结构总览 + +``` +src/ +├── api/ # API 接口层 +├── assets/ # 静态资源 +├── components/ # 公共组件 +├── directives/ # 自定义指令 +├── i18n/ # 国际化 +├── layout/ # 布局组件 +├── router/ # 路由配置 +├── stores/ # 状态管理（Pinia） +├── theme/ # 样式主题 +├── types/ # TypeScript 类型定义 +├── utils/ # 工具函数 +├── views/ # 页面视图 +├── App.vue # 根组件 +└── main.ts # 应用入口 +``` + +--- + +## 🎯 核心文件 + +### App.vue +- **作用**: Vue 应用根组件 +- **功能**: 定义应用的最外层结构 + +### main.ts +- **作用**: 应用入口文件 +- **功能**: + - 初始化 Vue 实例 + - 注册全局插件（Router、Store、i18n） + - 挂载应用到 DOM + +--- + +## 📡 API 接口层 (`/api`) + +统一管理所有后端接口调用 + +``` +api/ +├── assets/ # 资产管理接口 +├── cid/ # CID 相关接口 +├── common/ # 公共接口（文件上传等） +├── customerService/ # 客服系统接口 +├── digitalHuman/ # 数字人相关接口 +│ ├── audioAssets/ # 音频资产接口 +│ ├── avatar/ # 数字人形象接口 +│ ├── creation/ # 内容创作接口 +│ ├── modelConfig/ # 模型配置接口 +│ ├── skill/ # 技能管理接口 ⭐ +│ └── videoAssets/ # 视频资产接口 +├── knowledge/ # 知识库接口 +│ ├── dataset/ # 数据集接口 +│ ├── document/ # 文档接口 +│ └── model/ # 模型接口 +├── login/ # 登录认证接口 +├── menu/ # 菜单接口 +├── system/ # 系统管理接口 +│ ├── cache/ # 缓存管理 +│ ├── config/ # 系统配置 +│ ├── dept/ # 部门管理 +│ ├── dict/ # 字典管理 +│ ├── menu/ # 菜单管理 +│ ├── monitor/ # 系统监控 +│ ├── personal/ # 个人中心 +│ ├── post/ # 岗位管理 +│ ├── role/ # 角色管理 +│ ├── tenant/ # 租户管理 +│ └── user/ # 用户管理 +└── trade/ # 交易运营接口 + └── operation/ # 运营数据 + ├── analysis/ # 数据分析 + ├── distribution/# 分销数据 + ├── setting/ # 运营设置 + └── stats/ # 统计数据 +``` + +**关键文件**: +- 每个模块的 `index.ts` 包含该模块的所有接口定义 +- 使用 TypeScript 定义接口参数和返回值类型 + +--- + +## 🎨 静态资源 (`/assets`) + +存放项目静态资源文件 + +``` +assets/ +├── 401.png # 401 无权限页面图片 +├── 404.png # 404 页面未找到图片 +├── bg.jpg # 背景图 +├── login-icon-two.svg # 登录页图标 +└── logo-mini.svg # 小尺寸 Logo +``` + +--- + +## 🧩 公共组件 (`/components`) + +可复用的 Vue 组件 + +``` +components/ +├── auth/ # 权限控制组件 +│ ├── auth.vue # 单个权限控制 +│ ├── authAll.vue # 全部权限控制 +│ └── auths.vue # 多权限控制 +├── cropper/ # 图片裁剪组件 +│ └── index.vue +├── editor/ # 富文本编辑器 +│ ├── index.vue +│ └── toolbar.ts # 工具栏配置 +├── iconSelector/ # 图标选择器 +│ └── index.vue +├── model/ # 模型选择器 ⭐ +│ └── ModelSelector.vue +├── myCodeMirror/ # 代码编辑器 +│ └── index.vue +├── noticeBar/ # 通知栏组件 +│ └── index.vue +├── pagination/ # 分页组件 +│ └── index.vue +├── skill/ # 技能选择器 ⭐ +│ ├── NodeSkillSelector.vue # 节点技能选择器 +│ └── SkillSelector.vue # 技能选择器 +└── svgIcon/ # SVG 图标组件 + └── index.vue +``` + +**使用说明**: +- 组件可在任何页面中导入使用 +- 部分组件已注册为全局组件 + +--- + +## 📜 自定义指令 (`/directives`) + +Vue 自定义指令 + +``` +directives/ +└── debounce.ts # 防抖指令 +``` + +**使用示例**: +```vue +点击 +``` + +--- + +## 🌍 国际化 (`/i18n`) + +多语言支持 + +``` +i18n/ +├── lang/ # 语言包 +│ ├── en.ts # 英文 +│ ├── zh-cn.ts # 简体中文 +│ └── zh-tw.ts # 繁体中文 +├── pages/ # 页面级国际化 +│ ├── formI18n/ # 表单国际化 +│ └── login/ # 登录页国际化 +└── index.ts # 国际化配置入口 +``` + +**支持语言**: +- 简体中文 (zh-cn) +- 繁体中文 (zh-tw) +- 英文 (en) + +--- + +## 🏗️ 布局组件 (`/layout`) + +应用整体布局结构 + +``` +layout/ +├── component/ # 布局基础组件 +│ ├── aside.vue # 侧边栏 +│ ├── columnsAside.vue # 分栏侧边栏 +│ ├── header.vue # 头部 +│ └── main.vue # 主体内容区 +├── footer/ # 页脚 +│ └── index.vue +├── lockScreen/ # 锁屏功能 +│ └── index.vue +├── logo/ # Logo 组件 +│ └── index.vue +├── main/ # 主布局模式 +│ ├── classic.vue # 经典布局 +│ ├── columns.vue # 分栏布局 +│ ├── defaults.vue # 默认布局 +│ └── transverse.vue # 横向布局 +├── navBars/ # 导航栏 +│ ├── breadcrumb/ # 面包屑导航 +│ │ ├── breadcrumb.vue # 面包屑 +│ │ ├── closeFull.vue # 全屏切换 +│ │ ├── index.vue # 导航栏入口 +│ │ ├── search.vue # 搜索 +│ │ ├── setings.vue # 设置 +│ │ ├── user.vue # 用户信息 +│ │ └── userNews.vue # 用户消息 +│ └── tagsView/ # 标签页视图 +│ ├── contextmenu.vue # 右键菜单 +│ └── tagsView.vue # 标签页 +├── navMenu/ # 导航菜单 +│ ├── horizontal.vue # 横向菜单 +│ ├── subItem.vue # 子菜单项 +│ └── vertical.vue # 纵向菜单 +├── routerView/ # 路由视图 +│ ├── iframes.vue # iframe 视图 +│ ├── link.vue # 外链视图 +│ └── parent.vue # 父级视图 +└── index.vue # 布局入口 +``` + +**布局模式**: +- 经典布局 (classic) +- 分栏布局 (columns) +- 默认布局 (defaults) +- 横向布局 (transverse) + +--- + +## 🛣️ 路由配置 (`/router`) + +Vue Router 路由管理 + +``` +router/ +├── backEnd.ts # 后端动态路由 +├── frontEnd.ts # 前端静态路由 +├── index.ts # 路由入口 +└── route.ts # 路由工具函数 +``` + +**路由模式**: +- 前端路由: 静态配置，适合固定菜单 +- 后端路由: 动态加载，根据权限生成 + +--- + +## 🗄️ 状态管理 (`/stores`) + +Pinia 状态管理 + +``` +stores/ +├── interface/ # Store 接口定义 +│ └── index.ts +├── bigUpload.ts # 大文件上传状态 +├── index.ts # Store 入口 +├── keepAliveNames.ts # 页面缓存名称 +├── requestOldRoutes.ts # 旧路由请求 +├── routesList.ts # 路由列表状态 +├── tagsViewRoutes.ts # 标签页路由状态 +├── themeConfig.ts # 主题配置状态 +└── userInfo.ts # 用户信息状态 +``` + +**主要 Store**: +- `userInfo`: 用户登录信息、权限 +- `themeConfig`: 主题、布局配置 +- `routesList`: 动态路由列表 +- `tagsViewRoutes`: 标签页历史记录 + +--- + +## 🎨 样式主题 (`/theme`) + +全局样式和主题配置 + +``` +theme/ +├── common/ # 公共样式 +│ └── transition.scss # 过渡动画 +├── media/ # 响应式样式 +│ ├── chart.scss # 图表样式 +│ ├── cityLinkage.scss # 城市联动 +│ ├── date.scss # 日期选择器 +│ ├── dialog.scss # 对话框 +│ ├── error.scss # 错误页 +│ ├── form.scss # 表单 +│ ├── home.scss # 首页 +│ ├── index.scss # 媒体查询入口 +│ ├── layout.scss # 布局 +│ ├── login.scss # 登录页 +│ ├── media.scss # 响应式断点 +│ ├── pagination.scss # 分页 +│ ├── personal.scss # 个人中心 +│ ├── scrollbar.scss # 滚动条 +│ └── tagsView.scss # 标签页 +├── mixins/ # SCSS 混入 +│ ├── button-text.scss # 按钮文本混入 +│ └── index.scss # 混入入口 +├── app.scss # 应用主样式 +├── dark.scss # 暗黑主题 +├── element.scss # Element Plus 样式覆盖 +├── iconSelector.scss # 图标选择器样式 +├── index.scss # 样式入口 +├── loading.scss # 加载动画 +├── other.scss # 其他样式 +└── waves.scss # 波纹效果 +``` + +**主题功能**: +- 支持亮色/暗色主题切换 +- 响应式布局适配 +- Element Plus 组件样式定制 + +--- + +## 📝 类型定义 (`/types`) + +TypeScript 类型声明 + +``` +types/ +└── file-saver.d.ts # file-saver 库类型定义 +``` + +**说明**: 为第三方库提供 TypeScript 类型支持 + +--- + +## 🛠️ 工具函数 (`/utils`) + +通用工具函数库 + +``` +utils/ +├── arrayOperation.ts # 数组操作工具 +├── assetSubscribe.ts # 资产订阅工具 +├── authDirective.ts # 权限指令工具 +├── authFunction.ts # 权限判断函数 +├── build.ts # 构建相关工具 +├── commonFunction.ts # 公共函数 +├── customDirective.ts # 自定义指令注册 +├── debounce.ts # 防抖函数 +├── diffUtils.ts # 差异对比工具 +├── directive.ts # 指令工具 +├── formatTime.ts # 时间格式化 +├── getStyleSheets.ts # 获取样式表 +├── gfast.ts # GFast 框架工具 +├── loading.ts # 加载状态工具 +├── other.ts # 其他工具函数 +├── request.ts # HTTP 请求封装 ⭐ +├── setIconfont.ts # 设置图标字体 +├── storage.ts # 本地存储封装 +├── theme.ts # 主题切换工具 +├── toolsValidate.ts # 表单验证规则 +└── wartermark.ts # 水印工具 +``` + +**核心工具**: +- `request.ts`: Axios 封装，统一处理 HTTP 请求、错误拦截 +- `storage.ts`: localStorage/sessionStorage 封装 +- `authFunction.ts`: 权限判断函数 +- `formatTime.ts`: 日期时间格式化 + +--- + +## 📄 页面视图 (`/views`) + +所有页面组件 + +### 核心业务模块 + +#### 数字人模块 (`/digitalHuman`) ⭐ + +``` +digitalHuman/ +├── audioAssets/ # 音频资产管理 +│ ├── component/ +│ │ └── ttsDialog.vue # TTS 对话框 +│ └── index.vue +├── avatar/ # 数字人形象管理 +│ └── index.vue +├── creation/ # 内容创作 +│ └── index.vue +├── modelConfig/ # 模型配置 +│ ├── modelModule/ # 模型模块管理 +│ │ ├── component/ +│ │ │ └── editModule.vue # 编辑模型 +│ │ └── index.vue +│ └── modelType/ # 模型类型管理 +│ └── index.vue +├── skill/ # 技能管理 ⭐ +│ └── index.vue +└── videoAssets/ # 视频资产管理 + └── index.vue +``` + +**功能说明**: +- **音频资产**: 管理 TTS 音频文件 +- **数字人形象**: 配置数字人外观 +- **内容创作**: 创建数字人内容 +- **模型配置**: 管理 AI 模型（推理、图片、音频） +- **技能管理**: 管理技能模板（zip 格式，包含 .md 文件） +- **视频资产**: 管理视频素材 + +#### 知识库模块 (`/knowledge`) + +``` +knowledge/ +├── component/ +│ └── documentDetailDialog.vue # 文档详情对话框 +├── dataset/ # 数据集管理 +│ ├── component/ +│ │ └── editDataset.vue +│ └── index.vue +├── document/ # 文档管理 +│ ├── component/ +│ │ ├── documentChunks.vue # 文档分块 +│ │ ├── previewDocument.vue # 文档预览 +│ │ └── uploadDocument.vue # 上传文档 +│ ├── detail.vue # 文档详情 +│ └── index.vue +└── index.vue +``` + +#### 客服系统 (`/customerService`) + +``` +customerService/ +├── account/ # 客服账号管理 +├── product/ # 产品管理 +├── report/ # 报表统计 +└── script/ # 话术管理 +``` + +#### 资产管理 (`/assets`) + +``` +assets/ +├── asset/ # 资产管理 +├── category/ # 资产分类 +├── location/ # 库位管理 +├── operation/ # 资产操作 +│ └── count/ # 盘点管理 +├── warehouse/ # 仓库管理 +└── zone/ # 库区管理 +``` + +#### 交易运营 (`/trade`) + +``` +trade/ +└── operation/ + ├── analysis/ # 数据分析 + │ ├── product/ # 产品分析 + │ ├── region/ # 区域分析 + │ └── shop/ # 店铺分析 + ├── distribution/ # 分销管理 + │ ├── effect/ # 分销效果 + │ └── order/ # 分销订单 + ├── order/ # 订单管理 + ├── setting/ # 运营设置 + │ ├── anchor/ # 主播管理 + │ ├── live-account/# 直播账号 + │ └── scheduling/ # 排期管理 + └── stats/ # 统计数据 + ├── anchor/ # 主播统计 + └── shop/ # 店铺统计 +``` + +### 系统管理模块 (`/system`) + +``` +system/ +├── config/ # 系统配置 +├── dept/ # 部门管理 +├── dict/ # 字典管理 +├── menu/ # 菜单管理 +├── monitor/ # 系统监控 +│ ├── loginLog/ # 登录日志 +│ ├── operLog/ # 操作日志 +│ ├── server/ # 服务器监控 +│ └── userOnline/ # 在线用户 +├── personal/ # 个人中心 +├── post/ # 岗位管理 +├── role/ # 角色管理 +├── tenant/ # 租户管理 +└── user/ # 用户管理 +``` + +### 其他模块 + +``` +views/ +├── ads/ # 广告数据分析 +├── chart/ # 图表示例 +├── error/ # 错误页（401, 404） +├── fun/ # 功能演示 +│ ├── clipboard/ # 剪贴板 +│ ├── codemirror/ # 代码编辑器 +│ ├── countup/ # 数字滚动 +│ ├── cropper/ # 图片裁剪 +│ ├── echartsMap/ # 地图 +│ ├── gridLayout/ # 网格布局 +│ ├── printJs/ # 打印 +│ ├── qrcode/ # 二维码 +│ ├── splitpanes/ # 分割面板 +│ └── tagsView/ # 标签页 +├── home/ # 首页 +├── login/ # 登录页 +├── make/ # 组件制作 +├── menu/ # 菜单示例 +├── pages/ # 页面示例 +│ ├── awesome/ # 精选组件 +│ ├── drag/ # 拖拽 +│ ├── dynamicForm/ # 动态表单 +│ ├── element/ # Element 组件 +│ ├── filtering/ # 筛选 +│ ├── formAdapt/ # 表单适配 +│ ├── formI18n/ # 表单国际化 +│ ├── formRules/ # 表单验证 +│ ├── iocnfont/ # 图标字体 +│ ├── lazyImg/ # 图片懒加载 +│ ├── listAdapt/ # 列表适配 +│ ├── preview/ # 预览 +│ ├── steps/ # 步骤条 +│ ├── tableRules/ # 表格验证 +│ ├── tree/ # 树形控件 +│ ├── waterfall/ # 瀑布流 +│ ├── waves/ # 波纹效果 +│ └── workflow/ # 工作流 +├── params/ # 参数传递 +├── personal/ # 个人中心 +├── report-engine/ # 报表引擎 +├── tools/ # 工具页 +└── visualizing/ # 数据可视化 +``` + +--- + +## 🔑 关键文件说明 + +| 文件 | 作用 | 重要性 | +|------|------|--------| +| `main.ts` | 应用入口，初始化 Vue、Router、Store | ⭐⭐⭐ | +| `utils/request.ts` | HTTP 请求封装，统一错误处理 | ⭐⭐⭐ | +| `router/index.ts` | 路由配置，权限控制 | ⭐⭐⭐ | +| `stores/userInfo.ts` | 用户信息状态管理 | ⭐⭐⭐ | +| `stores/themeConfig.ts` | 主题配置状态管理 | ⭐⭐ | +| `components/model/ModelSelector.vue` | 模型选择器组件 | ⭐⭐ | +| `components/skill/SkillSelector.vue` | 技能选择器组件 | ⭐⭐ | +| `views/digitalHuman/` | 数字人核心业务模块 | ⭐⭐⭐ | + +--- + +## 📚 开发规范 + +### 文件命名 +- 组件文件: PascalCase (如 `ModelSelector.vue`) +- 工具文件: camelCase (如 `request.ts`) +- 样式文件: kebab-case (如 `login.scss`) + +### 目录组织 +- 每个业务模块独立目录 +- 组件相关文件放在 `component/` 子目录 +- 接口定义放在对应的 `api/` 目录 + +### 代码风格 +- 使用 TypeScript +- 遵循 ESLint 规则 +- 使用 Prettier 格式化 + +--- + +## 🔄 更新日志 + +- 2024-XX-XX: 创建文档 +- 添加数字人模块说明 +- 添加技能管理功能说明 + +--- + +## 📞 联系方式 + +如有问题，请联系开发团队。