TakeoutSaaS.TenantUI/CLAUDE.md

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 租户管理前端系统。