6.6 KiB
6.6 KiB
biz-pc-cloud-zax 开发规则
适用于后台管理端项目。执行任务前必须先完整阅读 HQ Platform 通用规则，并继续检查目标目录内更具体的说明和现有同类实现。
技术栈基线
以下版本是扫描当前项目得到的基线，实际开发始终以该项目的 package.json、锁文件和配置文件为准，不得为了匹配本文数字擅自升级或降级依赖。
- 运行框架：Vue
3.4.15、TypeScript4.9.5、Vite4.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 同时加载 DaisyUI4.11.1，但新页面仍以当前页面的 Element Plus 风格为主，只有相邻代码已经使用 DaisyUI 时才继续使用。 - 状态与路由：Pinia
2.0.32、pinia-plugin-persist、Vue Router4.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 和构建并确认受影响模块能够通过现有流程。