# CLAUDE.md 本文件用于指导 Claude Code (claude.ai/code) 在 Saber3 代码仓库中工作时的行为规范。 > 本规范适用于 Saber3 前端工程的所有开发任务，为强制性条款。除非用户显式豁免，任何条目都不得忽视或删减。 > > 作为 AI 助手参与本项目开发时，你必须： > - 每次输出前深度理解 BladeX 微服务架构体系、Saber3 前端工程结构和 Vue 3 技术栈特征 > - 当回答依赖外部知识时，先查询 Vue 3、Element Plus、Avue、Vite 等官方文档 > - 若需求含糊，先复述已知信息并列出关键澄清问题 > - 面对复杂需求，先拆分为可管理的子任务 > > 所有开发内容必须建立在深度思考过的基础之上，禁止机械生成与错误填充。 > 如果你已了解所有规范，请在用户第一次对话时说明："我已充分了解 BladeX 微服务平台开发规范。" --- ## 1. 项目概览 **Saber3** 是 BladeX 微服务平台的官方前端工程，基于 Vue 3 生态构建的企业级后台管理系统。 ### 1.1 技术栈 | 技术 | 版本 | 用途 | | ------------------ | -------- | ------------------ | | Vue | ^3.5.13 | 核心框架 | | Element Plus | ^2.10.1 | UI 组件库 | | @smallwei/avue | ^3.7.2 | 增强型 CRUD 组件库 | | Vue Router | ^4.3.2 | 路由管理 | | Vuex | ^4.1.0 | 状态管理 | | Axios | ^1.8.3 | HTTP 客户端 | | Vite | ^5.4.19 | 构建工具 | | vue-i18n | ^11.1.3 | 国际化 | | Sass | ^1.85.1 | CSS 预处理器 | | crypto-js / sm-crypto | - | 加密（AES / SM2） | --- ## 2. 项目架构 ``` Saber3/ ├── src/ │ ├── main.js # 应用入口（全局组件注册、插件挂载） │ ├── permission.js # 路由守卫（鉴权、标签页、锁屏） │ ├── axios.js # HTTP 拦截器（Token 刷新、加密、错误处理） │ ├── api/ # API 接口层（按业务模块组织） │ ├── views/ # 业务页面（按模块目录组织） │ ├── option/ # Avue 表格/表单配置（与 views/api 同构路径） │ ├── const/ # 常量定义 │ ├── config/ # 全局配置 │ │ ├── website.js # 核心配置（认证、菜单、水印、OAuth2、设计器） │ │ └── env.js # 环境变量（API 基础地址） │ ├── store/ # Vuex 状态管理（user/common/tags/logs/dict） │ ├── router/ # 路由系统 │ │ ├── avue-router.js # 动态路由核心（菜单→路由、keep-alive 扁平化） │ │ ├── page/ # 页面级路由（登录、锁屏、错误页） │ │ └── views/ # 视图路由（首页、控制台等） │ ├── components/ # 全局公共组件 │ ├── mixins/ # 混入（crud.js 等） │ ├── utils/ # 工具函数（auth/crypto/validate/util...） │ ├── lang/ # 国际化（zh/en） │ ├── styles/ # 全局样式 & 多主题 │ ├── mac/ # macOS 风格主题 │ └── page/ # 页面布局框架（主布局、登录、锁屏） ├── vite/ # Vite 插件配置 ├── vite.config.mjs # Vite 主配置 └── package.json ``` ### 2.1 路径别名 `@` → `./src`、`~` → `./`、`components` → `./src/components`、`styles` → `./src/styles`、`utils` → `./src/utils` --- ## 3. 核心机制 ### 3.1 Avue 组件代码生成（Skill 调用） 当涉及 `avue-crud`、`avue-form`、`avue-tree` 等 Avue 组件的代码生成或配置时，**优先调用 `avue-design` Skill**。该 Skill 覆盖 Avue 全部组件类型，支持 Options API 和 Composition API 两种代码风格。 **触发场景**：用户要求创建 CRUD 表格、Avue 表单、树组件、数据展示页面，或提到 avue、crud 表格、动态表单、JSON 配置表单等关键词。 ### 3.2 Avue Option 配置 Avue 表格/表单配置独立存放于 `src/option/` 目录，与 `views` 和 `api` 保持同构的模块路径映射。 ### 3.3 API 接口规范 - 所有 API 通过 `src/axios.js` 封装的 Axios 实例发起，按业务模块组织于 `src/api/` - 命名约定：列表 `getList(current, size, params)`、详情 `getDetail(id)`、新增 `add(row)`、更新 `update(row)`、删除 `remove(ids)`、树形 `getXxxTree()` - 后端微服务前缀：`/blade-system/`、`/blade-resource/`、`/blade-flow/`、`/blade-desk/`、`/blade-log/`、`/blade-develop/` ### 3.4 认证机制 - OAuth2：`Basic` 头传递 `clientId:clientSecret`（Base64 编码） - Token：请求头 `Blade-Auth: bearer {token}`，支持 AES 加密模式 - 存储：`saber3-access-token` / `saber3-refresh-token`（通过 `utils/auth.js` 管理） - 401 自动刷新 Token，并发请求排队等待；登录密码使用 SM2 国密加密 ### 3.5 路由系统 - 静态路由：`router/page/` + `router/views/` - 动态路由：`avue-router.js` 将后端菜单数据转换为 Vue Router 路由 - 多级路由自动扁平化为二级，支持 keep-alive 跨层级缓存 - 外部链接自动转换为 iframe 路由，支持 Token 透传 ### 3.6 权限控制 - 路由守卫：`permission.js` 控制登录态、锁屏、标签页 - 按钮权限：`store.getters.permission`，格式 `{module}_{action}`（如 `dict_add`） - 管理员判断：`userInfo.authority.includes('admin')` ### 3.7 多租户 通过 `website.tenantMode` 控制开关，管理组租户编号 `000000`，后端自动通过请求头传递租户信息。 --- ## 4. 开发规范 ### 4.1 双 API 风格共存 项目同时支持 **Options API**（主流，绝大多数现有页面）和 **Composition API**（新组件可选）。 **选择原则**： - 修改现有页面：保持该页面原有风格，不混用 - 新建 CRUD 页面：调用 `avue-design` Skill 生成，或参考现有页面手动编写 - 新建复杂交互页面：可使用 Composition API + `