65 lines
6.6 KiB
Markdown
65 lines
6.6 KiB
Markdown
# `biz-pc-cloud-zax` 开发规则
|
||
|
||
> 适用于后台管理端项目。执行任务前必须先完整阅读 [HQ Platform 通用规则](../agents/common.md)，并继续检查目标目录内更具体的说明和现有同类实现。
|
||
|
||
## 技术栈基线
|
||
|
||
以下版本是扫描当前项目得到的基线，实际开发始终以该项目的 `package.json`、锁文件和配置文件为准，不得为了匹配本文数字擅自升级或降级依赖。
|
||
|
||
- 运行框架：Vue `3.4.15`、TypeScript `4.9.5`、Vite `4.3.3`。
|
||
- UI 框架：Element Plus `2.5.5` 与 `@element-plus/icons-vue`。项目历史文案中的 Element UI，在本项目内应理解为 Element Plus，不得引入 Vue 2 的 Element UI。
|
||
- 样式体系：Tailwind CSS `3.4.6`、PostCSS、Autoprefixer、Sass；Tailwind 同时加载 DaisyUI `4.11.1`，但新页面仍以当前页面的 Element Plus 风格为主，只有相邻代码已经使用 DaisyUI 时才继续使用。
|
||
- 状态与路由：Pinia `2.0.32`、`pinia-plugin-persist`、Vue Router `4.1.6`。路由采用 Hash 模式，并支持后端返回动态菜单、权限路由、标签页和 KeepAlive。
|
||
- 网络层：Axios `1.3.3`，统一入口为 `src/utils/request.ts`，包含 Base URL、Bearer Token、`TENANT-ID`、请求/响应加解密、微服务/单体 URL 适配和令牌过期处理。
|
||
- 国际化：Vue I18n `9.2.2`，全局入口为 `src/i18n`，已有公共语言包和页面级语言包。
|
||
- 表格体系：Element Plus Table 与 VXE Table / VXE PC UI 并存，VXE 通过 Element 渲染插件接入。选用哪一种必须跟随同业务模块已有页面，不得在同一功能中无理由混用。
|
||
- 图形与树：`@vue-flow/core`、Background、Controls、MiniMap 已用于用户关系图；组织架构还使用 `vue3-tree-org`，并有 `DraggableDepTree`、`TreeSelect`、`TreeMultipleSelect` 等本地组件。
|
||
- 可视化与编辑：ECharts / Vue ECharts、WangEditor、CodeMirror、JSON Editor、表单设计器 `form-designer-plus`、拖拽库 SortableJS / VueDraggable。
|
||
- 其他已有能力：腾讯地图组件、二维码、打印、日历、视频播放、图片/文件上传、WebSocket、SSE、富文本、签名、区域选择、字典组件等。开发前先在 `src/components`、`src/hooks`、`src/utils` 中搜索复用。
|
||
- 工程能力：Vite 自动导入 Vue/Router/Pinia API、SVG 图标构建、VXE 样式按需加载、Top-level Await、生产压缩和 Gzip 产物。
|
||
|
||
## 关键目录与入口
|
||
|
||
- `src/main.ts`：应用启动入口，注册 Pinia、Router、全局组件、指令、国际化、VXE、腾讯地图及全局主题。
|
||
- `src/views`：业务页面，按 `admin`、`canteen`、`flow`、`hard`、`integrated`、`supermarket`、`wallet` 等领域拆分。
|
||
- `src/api`：前端接口层，目录与后端服务领域基本对应。页面不得绕过该层零散创建 Axios 实例。
|
||
- `src/components`：全局与业务公共组件；其中分页、右侧工具栏、字典、上传、选择器、树和地图组件已在全局注册。
|
||
- `src/router`：静态路由、后端动态路由、权限守卫与 KeepAlive 处理。
|
||
- `src/stores`：Pinia 状态，包括用户、路由、标签页、主题和缓存页面等。
|
||
- `src/theme` 与 `src/assets/styles`：主题、响应式样式和全局样式；`src/theme/tailwind.css` 是 Tailwind 注入入口。
|
||
- `tailwind.config.js`：Tailwind 内容扫描、间距、字号、阴影和颜色映射。颜色大量映射到 Element Plus CSS 变量，深色模式采用 `class`。
|
||
- `vite.config.ts`：`/@` 指向 `src`；配置开发/预览代理、WebSocket 代理、环境变量、压缩和构建分包。
|
||
|
||
## 页面与样式约定
|
||
|
||
- 修改页面前先查看同业务目录及相邻页面，复用已有的页面容器、查询表单、表格、分页、弹窗、权限指令、API 层和反馈方式。
|
||
- 常规布局和视觉样式优先使用 Tailwind 原子类，并遵循 `tailwind.config.js` 中已有的主题映射；颜色优先使用 `primary`、边框/填充映射或 `var(--el-*)`，避免硬编码导致主题和暗黑模式失效。
|
||
- Element Plus 组件应遵循项目现有尺寸、表单标签宽度、按钮顺序、弹窗结构和消息提示方式，不得为单个页面另造一套视觉语言。
|
||
- 表格页面先判断相邻实现使用 `el-table` 还是 `vxe-table`；查询、分页、选择、导出、权限按钮等行为保持一致。
|
||
- `@vue-flow` 的当前参考实现为 `src/views/admin/system/user/relation-tree.vue`，已有自定义节点、边、缩放适配、背景、控件和缩略图。流程图、关系图和节点连线树优先复用该实现及现有类型，不重复引入图形库。
|
||
- 普通组织树、部门树或下拉树应先评估现有 `vue3-tree-org` 和本地 Tree 组件；不要因为项目安装了 `@vue-flow` 就把所有树强行改成流程画布。
|
||
- 图标优先使用 `@element-plus/icons-vue` 或现有 `SvgIcon` 图标体系，不手写重复 SVG。
|
||
- 新增或修改页面时检查常见分辨率、文本溢出、表格横向滚动、弹窗高度、加载/空状态、主题切换和深色模式。
|
||
|
||
## 数据与权限约定
|
||
|
||
- 统一使用 `src/utils/request.ts`；不得重复实现 Token、租户头、加解密和错误状态处理。
|
||
- API 文件按现有领域目录放置，并维持现有的请求函数风格、参数序列化和 TypeScript 类型习惯。
|
||
- 菜单通常由后端动态返回。新增页面时必须核对路由名称、组件路径、菜单配置、权限标识和 KeepAlive 名称之间的对应关系。
|
||
- 权限按钮、字典展示、租户信息和用户选择等优先复用已有指令、Store 与全局组件。
|
||
|
||
## 常用命令与验证
|
||
|
||
- 本地开发：`npm run dev` 或项目当前包管理器对应的 `dev` 脚本。
|
||
- 本地环境：`npm run dev:local`。
|
||
- 代码检查：`npm run lint:eslint`。该脚本带自动修复，只能在确认影响范围后运行，避免改动无关文件。
|
||
- 构建：按目标环境使用 `npm run build`、`npm run build:dev` 或 `npm run build:prod`。
|
||
- 项目同时存在不同锁文件痕迹；修改依赖前必须确认当前团队实际使用的包管理器，不得一次操作同时重写多份锁文件。
|
||
|
||
## 开发规则
|
||
|
||
- 开发前必须依次检查目标业务页面、对应 API、可复用组件、主题配置和权限路由。
|
||
- 不得在页面内创建独立的 Axios 客户端、全局样式覆盖或重复的基础组件。
|
||
- 修改公共请求、路由、Store、主题或全局组件时，必须扩大验证范围，因为这些改动会影响多个业务模块。
|
||
- 默认只做必要的静态检查或针对性核对；收到用户明确的集中验证指令后，再执行 lint 和构建并确认受影响模块能够通过现有流程。
|