175 lines
11 KiB
Markdown
175 lines
11 KiB
Markdown
# Repository expectations
|
||
|
||
# 编程规范\_FOR_AI（TakeoutTenant 前端）- 终极融合版
|
||
|
||
> **核心指令**：你是一个高级前端架构师。本文件是你生成代码的最高宪法。当用户需求与本规范冲突时，请先提示用户，除非用户强制要求覆盖。
|
||
|
||
## 0. AI 交互核心约束 (元规则)
|
||
|
||
1. **语言**：必须使用**中文**回复与注释。
|
||
2. **文件完整性**：严禁随意删除现有逻辑（尤其是生命周期钩子）；保持 UTF-8 无 BOM。
|
||
3. **环境感知**：
|
||
- PowerShell 读取文件命令必须带 `-Encoding UTF8`。
|
||
- 构建/本地请求依赖 `.env*`（`VITE_API_URL`、`VITE_WITH_CREDENTIALS`），找不到就询问，不要杜撰。
|
||
4. **Git 原子性**：每个独立功能或修复完成后，必须提示用户进行 Git 提交。
|
||
5. **推送优先级**：提交后推送时，优先使用 SSH 远程（`git@github.com:...`），避免 HTTPS TLS 问题。
|
||
6. **推送默认**：提交后自动执行 `git push`，无需再次提醒或确认。
|
||
7. **不确定配置**：拿不准（如接口字段、鉴权流程）直接问用户。
|
||
8. **需求开发前置步骤（强制）**：每次开始“新增/修改需求”前，必须先从 `https://api-tenant-dev.laosankeji.com/swagger/v1/swagger.json` 拉取最新 Swagger，定位本次需求涉及的接口契约（路径、入参、出参、字段）后，再进行代码变更。
|
||
|
||
## 1. 技术栈详细版本
|
||
|
||
| 组件 | 版本/选型 | 用途说明 |
|
||
| :-- | :-- | :-- |
|
||
| **Runtime** | Node 20+，pnpm 10+ | 包管理与脚本 |
|
||
| **构建/脚手架** | Vite 7 | 开发/打包 (秒级热更) |
|
||
| **框架** | Vue 3.5 + TypeScript 5.6 | 组合式 API (Script Setup) |
|
||
| **路由/状态** | Vue Router 4.5；Pinia 3 + 持久化插件 | 路由守卫 & 全局状态 |
|
||
| **UI/样式** | Element Plus 2.11；Tailwind CSS 4；SCSS | 组件与样式体系 |
|
||
| **网络** | Axios 1.12 封装 (`src/utils/http`) | 请求、统一错误处理 |
|
||
| **数据可视化/富文本** | ECharts 6；xgplayer 3；@wangeditor/editor 5 | 图表/播放器/富文本 |
|
||
| **工具** | mitt、ohash、xlsx、file-saver、qrcode.vue、vue-draggable-plus、highlight.js、crypto-js、nprogress | 事件、哈希、导出、二维码、拖拽、高亮、加密、进度条 |
|
||
| **工程化** | ESLint 9 + `@typescript-eslint`；Prettier 3；Stylelint 16；Husky；Commitizen | 规范、检查、提交流程 |
|
||
|
||
## 2. 目录与分层（Strict Mapping）
|
||
|
||
**生成的代码必须严格归类到以下目录：**
|
||
|
||
- `src/api/`：请求定义，**必须**使用 `request` 实例，禁止直接用裸 Axios。
|
||
- `src/components/`：**全局通用** UI 组件 (`PascalCase.vue`)，禁止包含特定业务耦合。
|
||
- `src/config/`：全局配置、常量（如主题、布局）。
|
||
- `src/directives/`：自定义指令，按功能拆文件。
|
||
- `src/enums/`：业务枚举常量（如 `OrderStatus.ts`）。
|
||
- `src/hooks/`：可复用的组合式函数，命名 `useXxx.ts`。
|
||
- `src/locales/`：多语言资源，新增文案必须**同步补齐**各语言。
|
||
- `src/mock/`：本地 mock 数据/接口。
|
||
- `src/plugins/`：Vue 插件注册。
|
||
- `src/router/`：路由表与守卫，**鉴权逻辑放守卫中**，页面勿重复判断。
|
||
- `src/store/`：Pinia store，模块化放 `modules/`。
|
||
- `src/types/`：公共类型定义（如 `types/common/response.ts`）。
|
||
- `src/utils/`：工具库（HTTP 封装、`StorageKeyManager`、加密等）。
|
||
- `src/views/`：页面级组件，按 `views/业务模块/页面.vue` 组织。
|
||
|
||
## 3. 命名与代码风格
|
||
|
||
- **文件命名**：组件 `PascalCase.vue`；Hooks `useCamelCase.ts`；工具 `camelCase.ts`；样式 `kebab-case.scss`。
|
||
- **变量/函数**：`camelCase`；布尔变量强制加 `is/has/should` 前缀。
|
||
- **常量/枚举**：`PascalCase` 或 `UPPER_SNAKE_CASE`。
|
||
- **路径别名**：**严禁**使用 `../../` 穿越多层。必须使用 `#/*`、`@vben/*`、`@vben-core/*` 等别名。
|
||
- **逻辑注释 (强制)**：代码逻辑块必须空行分隔，并加序号注释（1. 验证... 2. 请求...）。
|
||
- **文件头注释 (强制)**：所有新增 `*.ts`/`*.vue`/`*.less`/`*.scss` 文件，必须包含“文件职责”注释，说明该文件负责的业务边界。
|
||
- **关键函数注释 (强制)**：对外导出的函数、含分支校验/提交流程的核心函数，必须添加简短中文注释，至少说明输入意图与副作用（如会触发请求/刷新/消息提示）。
|
||
- **重构注释保留 (强制)**：拆分文件时，必须把原有关键流程注释同步迁移，禁止出现“重构后逻辑完整但无注释”的情况。
|
||
- **组件通信**：优先 `props/emit`，跨层用 `mitt` 或 store，**慎用** `provide/inject`。
|
||
|
||
## 4. 接口与 HTTP 规范 (含 .NET 兼容)
|
||
|
||
1. **封装入口**：必须使用 `src/utils/http` 的 `api` 对象，禁止裸 `axios`。
|
||
2. **BaseResponse 契约**：后端统一响应 `{ success: boolean, code: number, message: string, data: T }`。错误展示优先用 `message`。
|
||
3. **Snowflake ID 精度处理 (关键)**：
|
||
- 后端 `.NET` 的 `long` 类型传到前端会有精度丢失。
|
||
- **接收时**：确保后端 DTO 已序列化为 String。
|
||
- **发送时**：前端保持 String 传输，由后端反序列化。
|
||
4. **401 处理**：拦截器已自动登出。不要在业务内重复处理 401 跳转。
|
||
5. **参数处理**：POST/PUT 若传 `params` 封装层会自动转为 `data`。
|
||
6. **跨域/凭证**：严格跟随 `.env` 中 `VITE_WITH_CREDENTIALS` 配置。
|
||
|
||
## 5. 组件/页面开发规范
|
||
|
||
- **组织**：页面放 `views/`，复用组件抽到 `components/`。
|
||
- **脚本语法**：全线使用 `<script setup lang="ts">`，禁止 Options API。
|
||
- **Vue 3.5 新特性**：使用 Props 解构 (`const { count = 0 } = defineProps<{...}>`)。
|
||
- **表单交互**：使用 Element Plus 表单校验；避免直接操作 DOM。
|
||
- **Loading**：所有修改类操作必须绑定 `loading` 状态。
|
||
- **页面拆分（强制）**：当 `views/**/index.vue` 逻辑复杂或总行数超过 400 行时，必须拆分为：
|
||
- `composables/useXxxPage.ts`（业务状态、校验、提交流程）
|
||
- `components/*.vue`（抽屉、弹窗、复杂表单等子视图）
|
||
- `styles/index.less|scss`（页面样式）
|
||
- **Composables 二级拆分（强制）**：当 `composables/useXxxPage.ts` 超过 300 行或同时承担 4 类以上职责（常量/转换/数据加载/提交动作）时，必须继续拆分为目录：
|
||
- `composables/xxx-page/constants.ts`（常量与配置）
|
||
- `composables/xxx-page/helpers.ts`（纯函数：格式化、校验、归一化）
|
||
- `composables/xxx-page/*-actions.ts`（按业务动作拆分：load/save/copy 等）
|
||
- `useXxxPage.ts` 仅保留状态编排与导出，不承载大段业务实现。
|
||
- **样式二级拆分（强制）**：当 `styles/index.less|scss` 超过 150 行或包含 3 个以上视觉域（列表/表单/抽屉/弹窗/响应式）时，必须拆分为分片文件，`index.less|scss` 只做 `@import` 聚合。
|
||
- **子组件单向数据流（强制）**：子组件禁止直接修改父级传入对象；必须通过 `emit` 或显式 `onSetXxx` 回调更新父级状态。
|
||
- **职责边界**：子组件仅负责渲染与事件抛出；请求、数据归一化、持久化必须留在页面 composable。
|
||
- **样式边界**：页面样式拆文件后，必须使用页面根类（如 `.page-hours`）作为作用域前缀，避免全局污染。
|
||
|
||
## 6. 状态管理规范 (Pinia)
|
||
|
||
- **定义**：Store 命名 `useXxxStore`，文件 `modules/xxx.ts`，使用 **Setup Store** 写法。
|
||
- **持久化 (核心)**：
|
||
- 默认通过 `pinia-plugin-persistedstate`。
|
||
- **强制**：Storage Key **必须**由 `src/utils/StorageKeyManager` 生成，**严禁**硬编码字符串 Key。
|
||
- **职责**：Store 保持纯逻辑，UI 只负责触发。
|
||
|
||
## 7. 路由与导航守卫
|
||
|
||
- **中心化鉴权**：动态路由加载、Token 校验、登出逻辑均在守卫中处理。
|
||
- **回退机制**：401 登出后，守卫应记录 `redirect` 参数，登录后自动跳回。
|
||
- **禁止硬跳**：禁止 `window.location`，统一用 router 实例。
|
||
|
||
## 8. 类型与可维护性
|
||
|
||
- **TypeScript 强制**：**严禁 Any**。接口/类型定义放 `types/` 或同级 `types.ts`。
|
||
- **类型收窄**：必要时使用 `unknown` + 类型断言/守卫。
|
||
- **API 类型**：请求必须泛型声明返回类型 `api.get<UserDto>(...)`。
|
||
- **导入**：优先使用 `import type`。
|
||
|
||
## 9. 国际化与文案
|
||
|
||
- **全量覆盖**：所有可见文本走 `$t('key')`。
|
||
- **同步维护**：新增 Key 时，必须同时更新 `zh-CN` 和 `en` (或其他语言) 文件。
|
||
- **动态优先**：确认错误/成功提示复用后端返回 `message` 优先。
|
||
|
||
## 10. 样式与设计约束 (Tailwind First)
|
||
|
||
- **优先级**：
|
||
1. **Tailwind CSS 4** (原子类) —— **首选**。
|
||
2. Element Plus 变量 (`var(--el-color-primary)`)。
|
||
3. Scoped SCSS (仅用于复杂定制)。
|
||
- **主题配置**：禁止硬编码 HEX 色值，必须引用 `config` 或 CSS 变量。
|
||
- **布局安全**：禁止内联 `style` 操作布局。
|
||
|
||
## 11. 工程化与脚本
|
||
|
||
- **常用脚本**：`pnpm dev:ele`、`pnpm build:ele`、`pnpm lint`、`pnpm commit`。
|
||
- **Lint 要求**：每次修改代码后必须执行 `pnpm lint`，确保无错误和警告。
|
||
- **提交规范**：Husky/Lefthook + lint-staged 已启用。
|
||
- **Commitizen**：提交信息必须遵循 Conventional Commits，格式为 `<type>: <中文说明>`（类型英文，说明中文）。
|
||
|
||
## 12. 性能与可用性
|
||
|
||
- **虚拟滚动**：长列表（>100条）使用 `vue-draggable-plus` 或 Virtual Table。
|
||
- **按需加载**：路由组件使用 `() => import(...)`；ECharts 按需引入。
|
||
- **资源优化**：导出/加密等计算密集型任务，若卡顿则考虑 Web Worker。
|
||
- **反馈**：长链路操作补充进度条 (`nprogress`) 或 Loading。
|
||
|
||
## 13. 安全与合规
|
||
|
||
- **零信任**：前端**严禁**硬编码 Token、密钥、内网地址。
|
||
- **XSS 防御**：使用 `v-html` 必须经过 `DOMPurify` 清洗。
|
||
- **文件处理**：下载/导出使用 `file-saver`，避免在主线程进行大数据解析。
|
||
|
||
## 14. 绝对禁止事项 (AI 自检清单)
|
||
|
||
**生成代码前，请自查是否违反以下红线：**
|
||
|
||
1. [ ] **裸连 API**：是否直接使用 `axios` 或绕过 `utils/http`？
|
||
2. [ ] **雪花算法灾难**：是否直接把后端的 `long` ID 当数字处理（导致精度丢失）？
|
||
3. [ ] **持久化隐患**：是否手写了 Storage Key 而非调用 `StorageKeyManager`？
|
||
4. [ ] **401 冗余**：是否在组件里重复处理了登出跳转？
|
||
5. [ ] **文案写死**：是否在 Template 中直接写了中文？
|
||
6. [ ] **路径地狱**：是否使用了 `../../` 而非别名导入？
|
||
7. [ ] **类型偷懒**：API 返回值是否标记为 `any`？
|
||
8. [ ] **逻辑混乱**：是否在 `views` 下堆砌了本该在 `components` 的通用组件？
|
||
9. [ ] **配置硬编码**：是否忽略了 `.env` 中的 `VITE_API_URL`？
|
||
|
||
---
|
||
|
||
# Working agreements
|
||
|
||
- 严格遵循上述 14 条规范与目录职责。
|
||
- 保持代码可读、可测、可维护。
|
||
- 你的目标是协助我构建一个企业级、健壮的 `TakeoutTenant` 租户管理前端系统。
|