前端文档介绍
这套文档面向 art-design-pro-ui 的本地运行、接口联调、权限路由和扩展开发。它不只说明技术栈，也帮助你理解业务模块的代码落点、配置方式和部署注意事项。
首次接手项目时，建议先建立以下认知：
- 项目如何启动并连接后端。
- 请求、Token、刷新令牌和接口签名如何协作。
- 菜单、动态路由和按钮权限如何驱动页面。
- 业务模块在目录、路由和接口层分别落在哪里。
- 新增页面、菜单、按钮权限和接口时需要同步哪些内容。
- 生产部署前必须确认哪些域名、路径和 Cookie 策略。
建议阅读顺序
第一次接手项目
准备做扩展开发
准备部署上线
前端定位
art-design-pro-ui 是与商业版后端配套的中后台前端工程，适合作为业务项目的前端项目底座。它具备以下特点：
- 有完整的登录、刷新令牌、站点配置、动态菜单和权限联动
- 业务模块已覆盖系统管理、监控、通知、调度、工作流、内容、商城等核心场景
- 页面结构和通用能力已经具备继续扩展的基础，不需要从零搭框架
- 更适合作为可持续扩展的项目底座，而不是一次性演示页面集合
技术栈总览
| 分类 | 实际使用 |
|---|---|
| 核心框架 | Vue 3、TypeScript、Vite |
| 路由体系 | Vue Router 4，静态路由 + 动态菜单路由 |
| 状态管理 | Pinia |
| UI 体系 | Element Plus + 项目级通用组件 |
| 样式体系 | Tailwind CSS v4、Sass |
| 国际化 | vue-i18n |
| 测试 | Vitest、Playwright |
| 工程工具 | ESLint、Prettier、Husky、Lint-staged、Commitizen |
能力分层
1. 页面层
用户真正看到和操作的页面，例如：
- 登录
- 仪表盘
- 系统管理
- 文件中心
- 工作流
- 商城
2. 平台层
支撑使用体验的公共能力，例如：
- 动态菜单
- 工作标签页
- 全局搜索
- 布局切换
- 站点配置
- 权限控制
3. 工程层
支撑长期维护和扩展的底座，例如：
- HTTP 请求封装
- 路由守卫
- 配置中心
- 组合式函数
- 通用组件和工具库
与开源文档的关系
开源文档已经覆盖了一部分通用能力，比如：
- 主题配置
- 图标
- 部分组件
- 部分工程说明
商业版文档重点回答更贴近项目使用的问题：
- 这个商业版仓库如何与后端实际联调
- 当前商业版有哪些真实业务模块
- 当前目录下哪些文件是你最常改的
- 做项目定制时先改哪里、后改哪里
- 出现登录、菜单、权限、部署问题时该查哪里
所以阅读方式上，建议把商业版文档当作主线，把开源文档当作补充参考。
代码规范与提交
前端项目已经接入了代码质量和提交规范工具链，开始多人协作前建议先阅读开源文档中的 规范。
当前前端项目实际可用的相关脚本包括：
bash
pnpm lint
pnpm fix
pnpm lint:prettier
pnpm lint:stylelint
pnpm lint:lint-staged
pnpm test
pnpm test:e2e
pnpm commit推荐开发节奏：
- 日常编码时优先保持 ESLint 和类型提示干净
- 提交前执行
pnpm lint - 样式或格式需要统一时执行
pnpm lint:prettier和pnpm lint:stylelint - 使用
pnpm commit生成规范化提交信息
这部分虽然在开源文档里已有通用说明，但商业版项目本身也已经配好了脚本，建议直接纳入你的日常开发流程。
常见使用场景
场景一：完成首次运行与演示
优先看：
- 快速开始
- 接口联调
- 常见问题
场景二：研发要开始改业务
优先看：
- 项目结构
- 业务模块地图
- 路由与权限
- 扩展开发指南
场景三：项目准备上线
优先看：
- 构建部署
- 接口联调
- 常见问题
阅读后你可以掌握
- 独立把项目在本地跑起来
- 知道前后端联调配置在哪里改
- 知道菜单、按钮和权限问题的排查入口
- 知道一个页面从“菜单到接口到组件”的落点
- 知道项目启动和部署时该优先配置哪些内容