8.7 KiB
8.7 KiB
Repository Guidelines
本仓库为基于 Vite + Vue 3 + TypeScript 的前端项目，依赖 Ant Design Vue、Pinia、Axios 等。统一使用 UTF-8 编码。
项目结构与模块组织
- 源码：
src/（components/、pages/、services/、apis/、stores/、hooks/、assets/） - 静态资源：
public/ - 接口模拟：
mocks/（本地联调示例数据） - 文档：
docs/ - 配置：
vite.config.ts、tsconfig*.json、eslint.config.js
构建、测试与本地运行
- 本地开发：
pnpm start或npm run start（启动 Vite 开发服务器） - 生产构建：
pnpm build或npm run build（先 TypeCheck 再打包） - 本地预览：
pnpm preview或npm run preview - 代码检查：
npx eslint . --ext .ts,.vue - 样式检查：
npx stylelint "src/**/*.{vue,scss,css}" - 格式化：
npx prettier -w .
代码风格与命名约定
- TypeScript + Vue SFC，缩进 2 空格；单引号；必须分号；
max-len120。 - 组件命名采用帕斯卡命名（例：
RobotLabels.vue）；忽略名：index.vue、exception.vue。 - 导入排序使用
eslint-plugin-simple-import-sort。 - 样式使用 SCSS，按
stylelint推荐与 Recess Order。
测试规范
当前未集成单测框架。建议后续采用 Vitest + Vue Test Utils，测试文件命名 *.spec.ts，位置 src/**/__tests__/ 或与源码同级。
提交与合并请求
- 提交遵循 Conventional Commits：
feat|fix|refactor(scope?): 简要中文描述。- 示例：
feat(editor): 新增导入场景模态框
- 示例：
- PR 需包含：变更说明、影响范围、操作步骤/截图（UI 变更）、关联 Issue、风险与回滚方案。
- 在提交前确保：通过构建与 ESLint/Stylelint/Prettier 检查。
安全与配置提示
- 后端地址与令牌从环境变量读取：
ENV_HTTP_BASE、ENV_DEV_TOKEN、ENV_DEV_TENANT_ID（见src/services/http.ts）。请在.env.development/.env.production配置。 - 避免将敏感信息写入仓库；调试日志仅限开发环境。
-Always reply to me in Chinese 文件编码使用 UTF‑8
web-amr 项目 AI 编程指导（Vue 3 + Vite + TS + Ant Design Vue + Pinia）
本指南用于约束 AI 在本项目中新增功能/修复 Bug 的方式，目标是：代码优雅、可维护、可读、符合主流 Vue 生态实践，并与仓库现有风格一致。
1. 总体原则
-
先理解再动手
- 先搜索仓库已有实现（同类页面/组件/Store/接口封装），优先复用现成模式。
- 不引入新范式/新库，除非明确要求；避免“为了重构而重构”。
-
最小必要改动（Minimal Diff）
- 只改与需求直接相关的文件和逻辑。
- 不随意改命名、格式、结构；不顺手修“无关的”问题。
-
分层清晰、职责单一
- UI 逻辑、业务逻辑、数据访问、状态管理分离。
- 一个文件/组件只负责一类事情。
-
可读性优先于“聪明”
- 选择易懂的实现而非炫技。
- 复杂逻辑拆分为可测试的小函数/Hook/Store action。
2. 项目结构与放置规范
- 页面：
src/pages/**- 每个页面一个文件夹，包含
index.vue、子组件、局部 hooks、局部类型。
- 每个页面一个文件夹，包含
- 组件：
src/components/**- 复用组件放这里；页面私有组件放页面目录内。
- 状态：
src/stores/**（Pinia）- 全局/跨页面状态必须放 Store。
- 接口：
src/apis/**：接口定义、类型、路径、参数；src/services/**：Axios 实例、拦截器、通用请求工具。
- Hooks：
src/hooks/**- 复用的组合式逻辑；页面私有 hooks 放页面目录。
- 静态资源：
src/assets/**、public/**
放置判定：
跨页面复用 → components/stores/hooks/apis；仅当前页面使用 → 页面目录内。
3. Vue 组件设计（主流实践）
-
Composition API +
<script setup lang="ts">- 使用
ref/reactive/computed/watch等组合式 API。 - 逻辑块按：
props -> emits -> state -> computed -> watchers -> methods -> lifecycle顺序组织。
- 使用
-
组件拆分规则
- 当组件出现以下任一情况必须拆分：
- 文件 > 200 行且含多个业务区域；
- 同一文件里出现多个“独立区域”的 UI/逻辑；
- 有可复用的表单、表格、弹窗、卡片、列表项等。
- 拆分后：父组件负责数据/状态/事件串联，子组件负责局部展示与交互。
- 当组件出现以下任一情况必须拆分：
-
Props/Emits 约束
- Props 必须有 TS 类型且语义清晰；不要透传大对象导致耦合。
- 子组件通过
emit通知父组件，不直接改父组件状态。
-
避免反模式
- 不在模板中写复杂表达式（>1 行逻辑移到 computed）。
- 不在组件内手动维护“全局状态影子副本”。
- 不把 API 请求散落在多个子组件中。
4. 状态管理（Pinia）
-
什么时候用 Store
- 跨组件/跨页面共享；
- 需要缓存/持久化；
- 逻辑复杂、含多处读写；
- 与权限、用户、全局配置、设备/机器人状态相关。
-
Store 设计
state：只放数据，不放派生值。getters：派生/只读视图。actions：异步与业务逻辑（含 API 调用、数据归一化）。- 禁止在组件里复制一份全局状态再手动同步。
-
调用方式
- 页面进入时
store.actionFetch()拉取，组件只消费 store。 - 需要局部临时状态（表单草稿、展开折叠）放组件内。
- 页面进入时
5. 接口与数据层
-
接口位置
- 接口定义放
src/apis/**，按领域/模块拆文件。 - 组件/页面不直接写 URL 字符串或 Axios 逻辑。
- 接口定义放
-
类型先行
- 所有请求/响应必须有 TS 类型；
- 类型从后端字段映射后再进入 UI（必要时做
transform）。
-
错误与边界处理
- 接口失败要有可预期的 UI 反馈（message/notification/empty）。
- 不吞异常；在 action 层统一 try/catch。
6. 类型与可维护性
- 组件 props、emits、store state/action、API 入参/出参必须显式类型。
- 避免
any；需要时用更窄的unknown+ 类型守卫。 - 公共类型放
src/apis/types或模块types.ts。 - 复杂对象优先
interface/type命名清晰。
7. UI 与 Ant Design Vue 规范
- 组件命名、用法遵循 Ant Design Vue 官方 API。
- 表单使用
a-form/a-form-item+ 规则校验，不手写校验状态。 - 表格分页、排序、筛选走 Ant 事件与参数，不做自定义混乱实现。
- 弹窗/抽屉优先抽成可复用组件。
8. 样式与布局
- 统一 SCSS，缩进 2 空格。
- 样式尽量局部作用（
scoped或 BEM 风格）。 - 不在模板内写行内样式，除非是动态且非常简单。
- 顺序遵循 Recess/Stylelint 推荐（位置/盒模型/排版/视觉/动画）。
9. 性能与体验
- 列表/表格大数据注意：分页、虚拟滚动（如已有方案则复用）。
- 计算量大逻辑放
computed，避免频繁watch。 - 路由懒加载、组件按需引入遵循现有配置。
- 避免无意义的深拷贝和 watch 深度监听。
10. 代码风格（必须遵守）
- UTF-8 编码；TS + Vue SFC；2 空格缩进；单引号；必须分号；
max-len 120。 - 导入排序使用
eslint-plugin-simple-import-sort，不要手动乱序。 - 组件命名帕斯卡；公共组件文件名语义化。
- 禁止一字母变量名（循环计数 i/j/k 除外）。
11. 提交前自检清单（AI 输出代码前需自查）
- 是否复用/延续了仓库已有模式？
- 是否把共享状态放进 Pinia，而非组件“手动同步”？
- 是否按职责拆分组件，父管业务/子管展示？
- API 是否全部走
apis/services，且有类型？ - 代码是否仅包含本需求相关改动？
- ESLint/Stylelint/Prettier 风格是否一致？
12. AI 禁止事项（Hard Don’ts）
- 不引入新状态库/新架构（除非明确要求）。
- 不在组件中复制全局状态再手动维护一致性。
- 不把业务逻辑硬塞进模板/样式/子组件里。
- 不做无关重构、无关格式化、无关命名调整。
- 不输出“看似能跑但难维护”的临时方案。
13. 推荐的开发步骤（AI 应遵循）
- 明确需求与边界 → 列出影响的页面/Store/API。
- 搜索现有相似实现 → 决定复用与扩展点。
- 先设计数据流/状态流 → 再落地 UI 与组件拆分。
- 先写 types + apis + store actions → 再写页面/组件。
- 最后补齐异常处理、空态、加载态与交互细节。