zcui/saber3/CLAUDE.md

# 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 + `<script setup>`
- 同一文件中禁止混用两种风格

### 4.2 命名规范

| 类型           | 命名方式                   | 示例                          |
| -------------- | -------------------------- | ----------------------------- |
| 页面文件       | kebab-case                 | `notice.vue`                  |
| 组件文件       | kebab-case 目录 + main.vue | `basic-container/main.vue`    |
| API / Option / 工具文件 | camelCase         | `dict.js`、`dictbiz.js`       |
| 变量 / 函数    | camelCase                  | `dictValue`、`handleDelete`   |
| Vuex mutations | UPPER_SNAKE                | `SET_IS_MENU`、`ADD_TAG`      |
| Vuex actions   | PascalCase                 | `FedLogOut`、`RefreshToken`   |

### 4.3 代码格式（Prettier）

`printWidth: 100` / `tabWidth: 2` / `semi: true` / `singleQuote: true` / `arrowParens: "avoid"`

### 4.4 样式规范

- 全局 SCSS 变量通过 `styles/variables.scss` 定义，Vite 自动注入所有组件
- 编写样式优先使用已有变量和 mixin（`styles/mixin.scss`），而非硬编码值

### 4.5 全局注册组件

在 `main.js` 中全局注册，可直接在模板中使用：`<basic-container>`、`<basic-block>`、`<highlight>`、`<code-editor>`、`<cron-editor>`、`<flow-design>`、`<flow-design-step>`、`<third-register>`、`<code-setting>`、`<form-setting>`、`<tenant-package>`、`<tenant-datasource>`

### 4.6 全局属性（Options API 中通过 `this` 访问）

`this.website`（全局配置）、`this.$dayjs`（日期库）、`this.getScreen`（屏幕尺寸）、`this.findColumn`（Avue 列配置查找）

---

## 5. 新功能开发流程

### 5.1 新增标准 CRUD 页面

1. **调用 `avue-design` Skill** 生成标准 CRUD 页面代码（推荐）
2. 或手动创建：API 文件 `src/api/{module}/{name}.js` → Option 配置 `src/option/{module}/{name}.js` → Vue 页面 `src/views/{module}/{name}.vue`
3. 后端配置菜单后，动态路由自动生效

### 5.2 开发前必做

1. 先看同模块已有实现，模仿其结构与风格
2. 优先使用 `src/components/`、`src/utils/` 中的现有实现，禁止重复造轮子
3. 若需引入新包，先确认不与已有依赖冲突

### 5.3 开发后验证

1. 若引入新依赖：`pnpm install` → `pnpm run build` → 确认构建通过
2. 构建通过后：`pnpm run dev` → 确认开发服务器正常启动
3. 功能测试交由用户执行，除非用户明确要求，不撰写示例代码或额外文档

---

## 6. 常用命令

```bash
pnpm run dev          # 启动开发服务器（端口 2888）
pnpm run build        # 构建（开发环境）
pnpm run build:prod   # 构建（生产环境，Terser 压缩、删除 console/debugger）
pnpm run serve        # 预览构建产物
```

---

## 7. 自主学习与风格一致性

1. 风格不确定时，主动查阅当前模块现有代码并模仿，避免破坏一致性
2. 新模块参考：`src/views/system/dict.vue`（Options API）、`src/views/desk/notice-composition.vue`（Composition API）
3. 若现有模块已满足需求，禁止自写替代实现
4. 若确需新实现，须在 commit 信息中说明已检索过的相关组件、现有实现不足的原因、新实现的范围

---

## 8. Git 提交规范

当需要提交代码时，优先使用 **`/blade-commit`** skill，它会自动分析变更内容并生成符合项目规范的 Gitmoji 提交信息。

项目采用 **Gitmoji** 风格，中文描述：

| Emoji      | 代码         | 场景             |
| ---------- | ------------ | ---------------- |
| :sparkles: | `:sparkles:` | 新增功能、优化增强 |
| :bug:      | `:bug:`      | 修复 Bug         |
| :zap:      | `:zap:`      | 性能优化、问题修复 |
| :tada:     | `:tada:`     | 重大版本发布     |
| :lipstick: | `:lipstick:` | 样式调整         |
| :recycle:  | `:recycle:`  | 代码重构         |
| :wrench:   | `:wrench:`   | 配置修改         |
| :memo:     | `:memo:`     | 文档更新         |
| :fire:     | `:fire:`     | 删除代码/文件    |

---

## 9. 交流语言

与用户交互时全程使用中文。若需临时切换语言，须明确告知。