# 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. 最后补齐异常处理、空态、加载态与交互细节。