230 lines
8.7 KiB
Markdown
230 lines
8.7 KiB
Markdown
# 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-len` 120。
|
||
- 组件命名采用帕斯卡命名（例：`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. 总体原则
|
||
|
||
1. **先理解再动手**
|
||
- 先搜索仓库已有实现（同类页面/组件/Store/接口封装），优先复用现成模式。
|
||
- 不引入新范式/新库，除非明确要求；避免“为了重构而重构”。
|
||
|
||
2. **最小必要改动（Minimal Diff）**
|
||
- 只改与需求直接相关的文件和逻辑。
|
||
- 不随意改命名、格式、结构；不顺手修“无关的”问题。
|
||
|
||
3. **分层清晰、职责单一**
|
||
- UI 逻辑、业务逻辑、数据访问、状态管理分离。
|
||
- 一个文件/组件只负责一类事情。
|
||
|
||
4. **可读性优先于“聪明”**
|
||
- 选择易懂的实现而非炫技。
|
||
- 复杂逻辑拆分为可测试的小函数/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 组件设计（主流实践）
|
||
|
||
1. **Composition API + `<script setup lang="ts">`**
|
||
- 使用 `ref/reactive/computed/watch` 等组合式 API。
|
||
- 逻辑块按：`props -> emits -> state -> computed -> watchers -> methods -> lifecycle` 顺序组织。
|
||
|
||
2. **组件拆分规则**
|
||
- 当组件出现以下任一情况必须拆分：
|
||
- 文件 > 200 行且含多个业务区域；
|
||
- 同一文件里出现多个“独立区域”的 UI/逻辑；
|
||
- 有可复用的表单、表格、弹窗、卡片、列表项等。
|
||
- 拆分后：父组件负责**数据/状态/事件串联**，子组件负责**局部展示与交互**。
|
||
|
||
3. **Props/Emits 约束**
|
||
- Props 必须有 TS 类型且语义清晰；不要透传大对象导致耦合。
|
||
- 子组件通过 `emit` 通知父组件，不直接改父组件状态。
|
||
|
||
4. **避免反模式**
|
||
- 不在模板中写复杂表达式（>1 行逻辑移到 computed）。
|
||
- 不在组件内手动维护“全局状态影子副本”。
|
||
- 不把 API 请求散落在多个子组件中。
|
||
|
||
---
|
||
|
||
## 4. 状态管理（Pinia）
|
||
|
||
1. **什么时候用 Store**
|
||
- 跨组件/跨页面共享；
|
||
- 需要缓存/持久化；
|
||
- 逻辑复杂、含多处读写；
|
||
- 与权限、用户、全局配置、设备/机器人状态相关。
|
||
|
||
2. **Store 设计**
|
||
- `state`：只放数据，不放派生值。
|
||
- `getters`：派生/只读视图。
|
||
- `actions`：异步与业务逻辑（含 API 调用、数据归一化）。
|
||
- **禁止在组件里复制一份全局状态再手动同步。**
|
||
|
||
3. **调用方式**
|
||
- 页面进入时 `store.actionFetch()` 拉取，组件只消费 store。
|
||
- 需要局部临时状态（表单草稿、展开折叠）放组件内。
|
||
|
||
---
|
||
|
||
## 5. 接口与数据层
|
||
|
||
1. **接口位置**
|
||
- 接口定义放 `src/apis/**`，按领域/模块拆文件。
|
||
- 组件/页面不直接写 URL 字符串或 Axios 逻辑。
|
||
|
||
2. **类型先行**
|
||
- 所有请求/响应必须有 TS 类型；
|
||
- 类型从后端字段映射后再进入 UI（必要时做 `transform`）。
|
||
|
||
3. **错误与边界处理**
|
||
- 接口失败要有可预期的 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 应遵循）
|
||
|
||
1. 明确需求与边界 → 列出影响的页面/Store/API。
|
||
2. 搜索现有相似实现 → 决定复用与扩展点。
|
||
3. 先设计数据流/状态流 → 再落地 UI 与组件拆分。
|
||
4. 先写 types + apis + store actions → 再写页面/组件。
|
||
5. 最后补齐异常处理、空态、加载态与交互细节。
|