项目结构

项目目录按照“页面、复用能力、应用基础设施、数据来源和工程配置”组织。阅读源码时不要从根目录逐个文件浏览，应该先确定当前任务属于哪条链路，再沿调用关系向下阅读。

根目录

art-design-pro-x/
├── build/                 # Vite 插件、CSS、依赖预构建和分包策略
├── docs/                  # 仓库内的接入、权限、安全和部署说明
├── public/                # 不经过模块打包的静态资源
├── scripts/               # 发布安全检查脚本
├── src/                   # 应用源码
├── .env                   # 公共环境变量
├── .env.development       # 开发代理
├── .env.production        # 生产环境配置
├── vite.config.ts         # Vite 主配置
├── package.json           # 依赖、命令和运行环境要求
└── AGENTS.md              # 项目事实、开发约定和交付边界

src 目录

src/
├── api/                   # 真实 HTTP 接口
├── assets/                # 图片、字体、全局样式和主题 Token
├── components/            # 全局通用组件与业务复用组件
├── config/                # 系统、布局、主题和功能开关
├── constants/             # 业务常量
├── data/                  # 产品自身使用的静态配置数据
├── directives/            # auth、roles 等全局指令
├── enums/                 # 菜单、主题等枚举
├── hooks/                 # 表格、权限、主题和布局组合逻辑
├── locales/               # 中英文语言包与 i18n 初始化
├── mock/                  # 尚未接入后端的业务预置数据
├── plugins/               # Element Plus 等插件初始化
├── router/                # 路由模块、守卫和动态注册核心
├── services/              # 可选业务流程编排，不存放 HTTP 接口定义
├── store/                 # Pinia 状态模块
├── types/                 # 接口、路由、组件和配置类型
├── utils/                 # HTTP、表格、存储、安全等工具
├── views/                 # 页面视图
├── App.vue                # 根组件
└── main.ts                # 应用启动入口

数据相关目录

src/api

这里统一保存所有真实 HTTP 接口。请求 URL、请求方法、参数、返回类型和单接口字段适配都应该放在 src/api，不能放到页面、Store 或 src/services。

初始项目只要求认证和可选远程菜单接口：

src/api/auth.ts
src/api/menu.ts

接入客户业务时按领域新增文件，例如：

src/api/customer/user.ts
src/api/customer/order.ts

API 文件负责接口地址、请求参数、返回类型和必要的字段转换，不应该包含页面状态、路由跳转或弹窗流程。

src/services

src/services 不是接口目录。当前源码只在认证和账号场景保留了流程封装：

• auth.ts：组合 src/api/auth.ts、响应校验和会话恢复语义。
• account.ts：组合个人资料、密码和登录会话的本地流程。

新增后端接口时仍然先在 src/api/<domain> 中定义。只有一个业务动作确实需要编排多个 API、组合多个数据源或复用复杂流程时，才考虑增加 Service；Service 内部只能调用 API，不能成为 URL 和请求函数的存放位置。普通 CRUD 页面直接调用对应 API 模块即可。

src/mock

预置数据按业务域组织：

src/mock/
├── account.ts
├── assistant/
├── content/
├── files/
├── monitor/
├── notification/
├── scheduler/
├── system/
├── workflow/
└── shared/                # clone、delay、filter、pagination、action

它不是 Mock Server，也不是浏览器数据库。页面直接调用异步函数，读取静态数据的隔离副本。详细约定见本地数据模式。

路由目录

src/router/
├── core/
│   ├── MenuProcessor.ts              # 菜单获取、校验和路径规范化
│   ├── RouteRegistry.ts              # 动态路由注册与移除
│   ├── RoutePermissionValidator.ts   # 当前菜单访问校验
│   ├── ComponentLoader.ts            # 视图组件解析
│   └── menu-filter.ts                # 角色过滤与空菜单清理
├── guards/
│   ├── beforeEach.ts                 # 登录、用户、菜单和动态路由初始化
│   └── afterEach.ts                  # 导航完成处理
├── modules/                           # 按业务域拆分的动态路由
├── routes/
│   ├── staticRoutes.ts               # 登录、错误页等静态路由
│   └── asyncRoutes.ts                # 动态路由入口
└── index.ts                           # Router 创建与注册

新增业务页面通常只需要在 views 和 router/modules 中工作，不要直接修改 RouteRegistry 等核心类，除非你正在扩展全局路由协议。

页面与复用能力

src/views

页面按业务域组织。标准列表页参考：

src/views/system/user/
├── index.vue
└── modules/
    ├── user-search.vue
    └── user-dialog.vue

推荐职责：

• index.vue：页面编排、列表状态和操作入口。
• modules/*-search.vue：搜索配置与表单校验。
• modules/*-dialog.vue：新增、编辑、详情等局部流程。

src/components

全局可复用组件位于这里，包含布局、表格、搜索、按钮、图表和安全 HTML 等。只有被多个业务域稳定复用的组件才应提升到全局目录，单个页面专用组件保留在页面 modules 中。

src/hooks

核心组合式逻辑包括：

• useTable：列表请求、分页、搜索、刷新和响应适配。
• useTableColumns：列配置、显隐和顺序。
• useAuth：按钮和角色判断。
• useTheme：主题初始化与切换。
• useLayoutHeight、useResponsiveMenuLayout：布局响应逻辑。

配置与状态

src/config

文件	主要职责
index.ts	系统名称、商业入口、主题列表、菜单布局和主色
setting.ts	用户设置默认值
modules/headerBar.ts	顶部栏功能
modules/fastEnter.ts	快速入口
modules/theme-studio/*	主题预设、色板和定制状态

src/store

Pinia 初始化位于 src/store/index.ts，模块位于 src/store/modules。修改持久化字段时，需要同时评估登出清理、账号切换和旧版本存储迁移。

按任务找文件

任务	建议阅读顺序
修改登录协议	api/auth.ts -> services/auth.ts -> utils/http -> store/modules/user.ts
排查登录后 500	router/guards/beforeEach.ts -> services/auth.ts -> api/auth.ts -> MenuProcessor.ts
新增菜单页面	views/<domain> -> router/modules/<domain>.ts -> locales
接入列表接口	页面导入 -> mock/<domain> -> api/<domain> -> types/api
修改按钮权限	路由 permissionPrefix/authList -> useAuth -> 页面按钮
调整主题布局	config/setting.ts -> store/modules/setting.ts -> 主题组件和样式 Token
修改品牌信息	config/index.ts -> store/modules/site-settings.ts -> mock/system/site-setting.ts
调整表格响应	页面 useTable 配置 -> utils/table/tableConfig.ts
准备部署	.env.production -> vite.config.ts -> build/vite -> docs/deployment.md

常见目录误区

• 不要把真实客户数据写入 src/mock 并作为生产存储。
• 不要在 src/config 或 .env 中保存后端密钥。
• 不要在页面内重复创建 Axios 实例或手写 Token 逻辑。
• 不要把接口 URL 和请求函数放入 src/services，所有 HTTP 接口统一归档到 src/api。
• 不要为一个页面专用组件过早创建全局抽象。
• 不要通过复制核心路由类来建立第二套路由体系。
• 删除页面时要同步清理路由、语言包、类型、Mock/API 和相关资源。

下一章建议阅读本地数据模式，理解页面数据为何可以逐步迁移。