项目结构
本文面向需要接手、排查或扩展 art-design-pro-ui 的研发人员。目标不是机械罗列目录，而是帮助你建立定位能力：
- 页面问题应该去哪个目录查
- 新增功能时应该改哪几层
- 哪些目录是业务层，哪些目录是底座层
先看整体结构
下面是当前 art-design-pro-ui 中对扩展开发最有帮助的目录树，重点保留日常开发、联调和使用会频繁接触的部分。
text
├── src
│ ├── api # API 接口封装，按业务域拆分
│ │ ├── auth.ts # 登录、注册、刷新令牌、用户信息
│ │ ├── user.ts # 用户管理与个人中心相关接口
│ │ ├── roles.ts # 角色管理接口
│ │ ├── departments.ts # 部门管理接口
│ │ ├── menu.ts # 菜单与权限相关接口
│ │ ├── dicts.ts # 字典接口
│ │ ├── site-settings.ts # 站点配置接口
│ │ ├── system-params.ts # 系统参数接口
│ │ ├── files.ts # 文件中心接口
│ │ ├── notifications.ts # 通知中心接口
│ │ ├── scheduler.ts # 定时任务接口
│ │ ├── workflow.ts # 工作流接口
│ │ ├── content.ts # 内容管理接口
│ │ ├── content-category.ts # 内容分类接口
│ │ ├── content-tag.ts # 内容标签接口
│ │ ├── mall.ts # 商城模块接口
│ │ ├── monitor.ts # 监控模块接口
│ │ ├── logs.ts # 日志相关接口
│ │ ├── feedback.ts # 反馈管理接口
│ │ ├── security-audit.ts # 安全审计接口
│ │ └── ai-assistant.ts # AI 助手接口
│ ├── App.vue # 根组件，决定整个应用入口壳层
│ ├── main.ts # 启动入口，挂载 store、router、i18n、全局指令
│ ├── assets # 静态资源目录
│ │ ├── images # 图片资源
│ │ │ ├── login # 登录页图片
│ │ │ ├── common # 通用图片
│ │ │ ├── settings # 设置面板相关图片
│ │ │ ├── ceremony # 节日与氛围图
│ │ │ └── ...
│ │ ├── styles # 全局样式
│ │ │ ├── core # 系统级样式、主题和变量
│ │ │ ├── custom # 自定义业务样式
│ │ │ └── index.scss # 样式入口
│ │ └── svg # SVG 资源与加载动画定义
│ ├── components # 组件层
│ │ ├── business # 业务组件
│ │ │ └── comment-widget # 评论相关业务组件
│ │ └── core # 通用组件库
│ │ ├── banners # 横幅类组件
│ │ ├── base # 基础组件
│ │ ├── cards # 卡片组件
│ │ ├── charts # 图表组件
│ │ ├── forms # 表单组件
│ │ ├── layouts # 布局组件
│ │ ├── media # 上传、媒体类组件
│ │ ├── others # 其他通用组件
│ │ ├── tables # 表格组件
│ │ ├── text-effect # 文本效果组件
│ │ ├── theme # 主题切换相关组件
│ │ ├── views # 页面级通用视图组件
│ │ └── widget # 小部件组件
│ ├── config # 系统配置目录
│ │ ├── assets
│ │ │ └── images.ts # 配置层引用的图片路径
│ │ ├── modules
│ │ │ ├── component.ts # 组件级配置
│ │ │ ├── fastEnter.ts # 快捷入口配置
│ │ │ ├── festival.ts # 节日氛围配置
│ │ │ ├── globalSearch.ts # 全局搜索配置
│ │ │ └── headerBar.ts # 顶部栏能力配置
│ │ ├── index.ts # 系统主配置入口
│ │ └── setting.ts # 设置面板默认值
│ ├── constants # 常量定义
│ │ ├── api-permissions.ts # API 权限码常量
│ │ └── logs.ts # 日志相关常量
│ ├── directives # 自定义指令
│ │ ├── business
│ │ │ ├── highlight.ts # 高亮指令
│ │ │ └── ripple.ts # 波纹效果指令
│ │ ├── core
│ │ │ ├── auth.ts # 权限指令
│ │ │ └── roles.ts # 角色指令
│ │ └── index.ts # 指令注册入口
│ ├── enums # 枚举定义
│ │ ├── appEnum.ts # 主题、菜单、语言等应用级枚举
│ │ └── formEnum.ts # 表单状态、规则等枚举
│ ├── hooks # 组合式函数
│ │ ├── core
│ │ │ ├── useAuth.ts # 认证相关逻辑
│ │ │ ├── useChart.ts # 图表逻辑
│ │ │ ├── useCommon.ts # 通用逻辑
│ │ │ ├── useFastEnter.ts # 快捷入口逻辑
│ │ │ ├── useHeaderBar.ts # 顶部栏逻辑
│ │ │ ├── useLayoutHeight.ts # 布局高度计算
│ │ │ ├── useTable.ts # 表格逻辑
│ │ │ ├── useTableColumns.ts # 表格列逻辑
│ │ │ ├── useTableHeight.ts # 表格高度计算
│ │ │ ├── useTheme.ts # 主题切换逻辑
│ │ │ └── ...
│ │ └── index.ts # Hooks 导出入口
│ ├── locales # 国际化资源
│ │ ├── index.ts # i18n 初始化入口
│ │ └── langs
│ │ ├── en.json # 英文语言包
│ │ └── zh.json # 中文语言包
│ ├── mock # Mock 与更新日志数据
│ │ ├── temp # 临时模拟数据
│ │ └── upgrade # 版本更新日志数据
│ ├── plugins # 第三方插件注册
│ │ ├── echarts.ts # ECharts 配置
│ │ ├── element-plus.ts # Element Plus 语言与配置
│ │ └── index.ts # 插件总入口
│ ├── router # 路由系统
│ │ ├── core # 动态路由底层能力
│ │ │ ├── ComponentLoader.ts # 页面组件加载器
│ │ │ ├── IframeRouteManager.ts
│ │ │ ├── MenuProcessor.ts # 菜单处理器
│ │ │ ├── RouteRegistry.ts # 路由注册器
│ │ │ ├── RouteTransformer.ts # 路由转换器
│ │ │ ├── RouteValidator.ts # 路由校验器
│ │ │ ├── RoutePermissionValidator.ts # 路由权限校验
│ │ │ └── index.ts
│ │ ├── guards
│ │ │ ├── beforeEach.ts # 登录校验、动态路由初始化
│ │ │ └── afterEach.ts # 后置守卫
│ │ ├── modules # 模块化路由定义
│ │ │ ├── dashboard.ts # 仪表盘路由
│ │ │ ├── system.ts # 系统管理路由
│ │ │ ├── monitor.ts # 监控路由
│ │ │ ├── scheduler.ts # 定时任务路由
│ │ │ ├── workflow.ts # 工作流路由
│ │ │ ├── content.ts # 内容管理路由
│ │ │ ├── mall.ts # 商城路由
│ │ │ ├── notification.ts # 通知路由
│ │ │ ├── template.ts # 模板页路由
│ │ │ ├── result.ts # 结果页路由
│ │ │ ├── exception.ts # 异常页路由
│ │ │ ├── help.ts # 帮助和文档入口路由
│ │ │ └── index.ts # 路由模块入口
│ │ ├── routes
│ │ │ ├── asyncRoutes.ts # 动态路由入口
│ │ │ └── staticRoutes.ts # 静态路由入口
│ │ ├── index.ts # 路由初始化入口
│ │ └── routesAlias.ts # 路由别名定义
│ ├── store # Pinia 状态管理
│ │ ├── modules
│ │ │ ├── menu.ts # 菜单状态
│ │ │ ├── notification.ts # 通知状态
│ │ │ ├── setting.ts # 设置状态
│ │ │ ├── site-settings.ts # 站点配置状态
│ │ │ ├── table.ts # 表格状态
│ │ │ ├── user.ts # 用户状态
│ │ │ └── worktab.ts # 工作标签页状态
│ │ └── index.ts # Store 入口
│ ├── types # TypeScript 类型
│ │ ├── api # 后端接口类型
│ │ ├── common # 通用响应与公共类型
│ │ ├── component # 组件类型
│ │ ├── config # 配置类型
│ │ ├── directive # 指令类型
│ │ ├── import # 自动导入生成类型
│ │ ├── router # 路由类型
│ │ ├── store # 状态管理类型
│ │ └── index.ts # 类型总入口
│ ├── utils # 工具函数目录
│ │ ├── constants # 常量工具
│ │ ├── form # 表单工具
│ │ ├── http # 请求封装、错误处理、状态码
│ │ ├── navigation # 跳转、路由、标签页工具
│ │ ├── socket # WebSocket 相关工具
│ │ ├── storage # 本地存储工具
│ │ ├── sys # 系统工具、升级、事件总线
│ │ ├── table # 表格工具
│ │ ├── ui # UI 工具、颜色、动画、loading
│ │ ├── api-security.ts # API 安全头相关处理
│ │ ├── crypto.ts # 前端加密工具
│ │ ├── router.ts # 路由工具
│ │ └── index.ts # 工具总入口
│ └── views # 页面目录
│ ├── auth # 登录、注册、忘记密码
│ ├── dashboard # 仪表盘页面
│ ├── system # 系统管理页
│ ├── monitor # 监控页
│ ├── scheduler # 定时任务页
│ ├── workflow # 工作流页
│ ├── content # 内容管理页
│ ├── mall # 商城页
│ ├── template # 模板页
│ ├── result # 成功/失败页
│ ├── exception # 异常页
│ ├── outside # iframe 外链页
│ └── index # 主布局与壳层页
├── env.d.ts # Vite 环境变量类型声明
├── tsconfig.json # TypeScript 配置
└── vite.config.ts # Vite 构建、代理、按需加载配置目录分层
第一层：业务页面层
主要是 views、api。
views解决“页面长什么样”api解决“页面如何与后端通信”
如果你在改业务功能，绝大多数工作都会落在这两层。
第二层：路由与权限编排层
主要是 router、store/modules/menu.ts、store/modules/user.ts。
这层决定：
- 登录后跳到哪里
- 菜单渲染方式
- 动态路由注册方式
- 权限按钮什么时候显示
第三层：系统配置与体验层
主要是 config、store/modules/setting.ts、store/modules/site-settings.ts。
这层决定：
- 系统默认名称
- 菜单布局
- 主题色
- 顶部栏能力
- 站点欢迎文案
第四层：复用能力层
主要是 components、hooks、utils。
这层是项目能否长期维护的关键。如果一个逻辑会反复出现，就应该考虑提升到这层，而不是一直写在页面里。
建议阅读顺序
想理解一个页面的工作方式
建议按这个顺序看：
router/modules/*.tsviews/<module>api/*.ts- 相关
store/hooks
想理解登录、菜单、权限主链路
建议按这个顺序看：
main.tsrouter/index.tsrouter/guards/beforeEach.tsutils/http/index.tsstore/modules/user.tsstore/modules/menu.ts
常见需求对应的入口
| 需求 | 优先查看 |
|---|---|
| 新增业务页面 | views + router/modules |
| 新增接口 | api |
| 菜单不显示 | router/guards + router/core + 菜单 store |
| 登录后跳转异常 | utils/http + router/guards + 用户 store |
| 修改品牌和系统配置 | config + site-settings store |
| 抽离可复用逻辑 | components/core、hooks/core、utils |
扩展开发建议
适合新增文件的地方
- 新页面：
views/<module> - 新接口：
api - 新业务组件：业务模块目录或
components/business - 新通用组件：
components/core - 新 hooks：
hooks/core
不建议随意堆逻辑的地方
main.ts- 全局守卫
config/index.ts
这些文件一旦被堆太多业务逻辑，后续会很难维护。
检查清单
接手项目后，建议确认：
- 能根据菜单或页面名称定位到
views、router/modules和api中的对应实现。 - 能区分业务页面层、路由权限层、系统配置层和复用能力层。
- 新增业务功能时不会把项目专属逻辑直接写入
main.ts、全局守卫或全局配置入口。