admin-ui/docs/SRC-STRUCTURE.md

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          # 防抖指令

使用示例:

<el-button v-debounce="handleClick">点击</el-button>

---

🌍 国际化 (/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: 创建文档
• 添加数字人模块说明
• 添加技能管理功能说明

---

📞 联系方式

如有问题，请联系开发团队。