前端文档介绍
这套文档面向 art-design-pro-x-ui 的本地运行、接口联调、权限路由和扩展开发。它不只说明技术栈，也帮助你理解业务模块的代码落点、配置方式和部署注意事项。
适用版本
本套文档适用于 前后端版（Java）与前后端版（Nest.js）共用的 art-design-pro-x-ui。组件、表格、主题、国际化、状态管理与路由机制共用；连接地址、后端启动方式和部分功能范围按实际购买的版本区分。
| 项目 | Java 版 | Nest.js 版 |
|---|---|---|
| 配套后端目录 | art-design-pro-x-java | art-design-pro-x-server |
| 本地后端默认端口 | 13001 | 13000 |
| 前端目录 | art-design-pro-x-ui | art-design-pro-x-ui |
| 请求签名 | 当前后端返回 signatureRequired: false，前端跳过签名 | 依据后端安全配置决定是否签名 |
| 开发工具与 AI 代码生成器 | 不包含 | 按 Nest.js 版交付范围使用 |
| AI 助手 | 流式对话，需自行配置模型服务 | 按 Nest.js 后端配置启用 |
本套文档不适用于独立的纯前端商业版 art-design-pro-x，其使用方式请看 纯前端版文档。文中提到的后端文档如标注 Nest.js，仅用于该后端实现；Java 的启动和配置详见 Java 后端文档。
共享前端源码中的页面与类型定义不代表两个后端提供全部相同能力。文件存储、审批、商城等业务边界见 能力概览。
阅读入口
首次接手项目时，建议先建立以下认知：
- 项目如何启动并连接后端。
- 请求、Token、刷新令牌和接口签名如何协作。
- 菜单、动态路由和按钮权限如何驱动页面。
- 业务模块在目录、路由和接口层分别落在哪里。
- 新增页面、菜单、按钮权限和接口时需要同步哪些内容。
- 生产部署前必须确认哪些域名、路径和 Cookie 策略。
建议阅读顺序
第一次接手项目
准备做扩展开发
准备部署上线
前端定位
art-design-pro-x-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生成规范化提交信息
这部分虽然在开源文档里已有通用说明，但商业版项目本身也已经配好了脚本，建议直接纳入你的日常开发流程。
常见使用场景
场景一：完成首次运行与演示
优先看：
- 快速开始
- 接口联调
- 常见问题
场景二：研发要开始改业务
优先看：
- 项目结构
- 业务模块地图
- 路由与权限
- 扩展开发指南
场景三：项目准备上线
优先看：
- 构建部署
- 接口联调
- 常见问题
阅读后你可以掌握
- 独立把项目在本地跑起来
- 知道前后端联调配置在哪里改
- 知道菜单、按钮和权限问题的排查入口
- 知道一个页面从“菜单到接口到组件”的落点
- 知道项目启动和部署时该优先配置哪些内容