# AGENTS.md

本文件用于指导 Codex (Codex.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 批量导入失败文件下载规范

- 所有批量导入功能如果存在部分数据无法导入、校验失败或后端处理异常，前端必须支持自动下载后端返回的导入失败 Excel。
- 失败 Excel 的字段顺序必须与原导入模板保持一致，并在最后一列追加“导入失败原因”。
- 前端上传接口需支持 `blob` 响应；Avue 默认上传无法可靠处理文件流时，应使用 `httpRequest` 或独立 API 方法自定义上传。
- 前端需根据响应 `content-type` 或 Blob 类型区分 JSON 成功响应与 Excel 文件流：成功时提示并刷新列表，失败文件流时下载失败明细并提示“部分数据导入失败，已下载失败明细”。
- 批量导入失败明细文件命名统一包含业务名称、`导入失败明细` 和时间戳，例如 `货物类型导入失败明细YYYY-MM-DD HH:mm:ss.xlsx`。
- 批量导入的前端预校验与后端导入校验必须与新增、编辑表单校验保持一致，包括必填、长度、格式、枚举范围、父子级联关系和金额/日期等业务规则；新增、编辑校验调整时，必须同步更新导入校验。

### 3.5 认证机制

- OAuth2：`Basic` 头传递 `clientId:clientSecret`（Base64 编码）
- Token：请求头 `Blade-Auth: bearer {token}`，支持 AES 加密模式
- 存储：`saber3-access-token` / `saber3-refresh-token`（通过 `utils/auth.js` 管理）
- 401 自动刷新 Token，并发请求排队等待；登录密码使用 SM2 国密加密

### 3.6 路由系统

- 静态路由：`router/page/` + `router/views/`
- 动态路由：`avue-router.js` 将后端菜单数据转换为 Vue Router 路由
- 多级路由自动扁平化为二级，支持 keep-alive 跨层级缓存
- 外部链接自动转换为 iframe 路由，支持 Token 透传

### 3.7 权限控制

- 路由守卫：`permission.js` 控制登录态、锁屏、标签页
- 按钮权限：`store.getters.permission`，格式 `{module}_{action}`（如 `dict_add`）
- 管理员判断：`userInfo.authority.includes('admin')`

### 3.8 多租户

通过 `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`），而非硬编码值
- 系统主色调统一使用 `#409eff`，涉及主题变量、Element Plus 主题覆盖、按钮/链接/选中态等品牌色场景均应保持一致
- 各页面搜索栏多行展示时，行与行之间的垂直间距统一为 `8px`
- 搜索组件 label 宽度统一不小于 `160px`，label 文本不得换行。
- 搜索组件内部 padding 统一为上、左右 `12px`，底部 `4px`。
- 搜索组件需展示轻量阴影，统一使用 `0 2px 8px rgba(0, 0, 0, 0.06)`，不得被局部卡片去样式规则覆盖。
- 表格线条颜色需统一使用 `#EFF1F7`，包括表格外边框、单元格分割线和固定列边线。
- 表格偶数行需统一使用 `#FAFAFA` 背景色，固定列单元格必须与对应行背景保持一致。
- 表格操作列同时展示“查看、编辑、删除”等三个按钮时，操作列宽度统一不小于 `220px`；操作列最大按钮数量超过 3 个时，操作列宽度统一加宽到不小于 `320px`；最大按钮数量超过 4 个时，仍按 `320px` 保持列宽，并从第 5 个按钮开始换行展示，禁止出现按钮裁切或显示不全。
- 表格操作列按钮统一仅展示文字，禁止配置 `icon` / `:icon` 或在操作按钮、操作下拉项中嵌入图标；顶部工具栏按钮不受此条限制。
- 纯文字操作入口统一使用 `<el-link>`，禁止使用带 `text` 属性的 `<el-button>`；提交、确认、上传等具有明确命令语义或需要加载状态的按钮可继续使用 `<el-button>`。
- 所有表格操作列中的文字链接统一保持 `8px` 间距；操作按钮超过操作列可用宽度时必须自动换行，禁止链接连续粘连或被裁切。Avue 自定义 `#menu` 插槽和手写 `el-table-column` 操作列均适用。
- `.avue-crud__header` 顶部间距统一为 `12px`。
- 分页组件整体靠右展示，必须展示接口返回的数据总条数，`X条/页` 的页容量选择器必须放在总条数右侧。
- `.basic-container__card` 的直接子级 `.el-card__body` 内边距统一去除，保持 `padding: 0`
- 所有 CRUD 页面搜索栏需与下方表格拆分为独立区域，两者垂直间距统一为 `8px`。
- 所有 CRUD 页面搜索栏操作按钮（搜索、清空等）需在搜索表单下方独占一行并放置在最右侧；搜索条件超过一行时必须显示“展开/折叠”，默认折叠且仅展示一行搜索条件；一行布局默认展示 4 个筛选项，Avue 配置统一使用 `searchIndex: 4`。
- 所有 CRUD 页面中新增、批量导入等顶部按钮组行不需要背景色，应保持透明背景。
- 所有 CRUD 页面顶部工具栏的“新增/新建”主操作按钮统一使用蓝底白字的实心主按钮（`type="primary"` 且不使用 `plain`），视觉标准与“新建运单”一致；批量导入、导出等辅助工具按钮仍使用描边样式。
- 所有 `.basic-container__card` 内的 Avue 内层 `el-card` 需去卡片化，仅保留外层容器卡片样式，禁止出现二级卡片边框、阴影或额外内边距。

### 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 列配置查找）

### 4.7 表单校验规范

- 金额类字段必须增加非负校验，禁止提交小于 0 的金额。
- 经纬度字段必须增加范围校验：经度范围为 -180 到 180，纬度范围为 -90 到 90。
- 备注类字段必须限制最多 200 个字，超过限制时应在前端阻止提交并给出明确提示。

### 4.8 表单布局规范

- 新增、编辑弹窗中的表单 `label` 默认必须位于控件左侧，Avue 配置统一使用 `labelPosition: 'right'` 与 `labelWidth: 'auto'`，Element Plus 表单统一使用 `label-position="right"` 与 `label-width="auto"`。
- 新增、编辑弹窗中的表单 `label` 宽度必须以当前视觉列内最长 `label` 为准；多列表单需按列分别计算 label 宽度，禁止用整张表单的最长 label 统一挤压所有列。
- 所有新增、编辑弹窗中的表单 `label` 文本必须右对齐，确保同一列内控件起始位置一致。
- 新增、编辑弹窗标题左侧必须展示 `4px` 宽的主色竖条，竖条与标题文本间距统一为 `8px`。
- 复杂布局弹窗中的自定义分区标题、明细表格标题、步骤区标题等承担弹窗内容标题作用时，也必须沿用 `4px` 主色竖条与 `8px` 标题间距；可使用全局 `.dialog-section-title` 或等效局部样式实现。
- 新增、编辑弹窗中的表单项上下间距统一为 `16px`，弹窗内表单布局不得叠加 `.el-col` 与 `.el-form-item` 的额外下边距。
- 所有新增、编辑弹窗中的备注字段（如果有）必须单独占一整行展示，禁止与其他字段并列；Avue 配置可使用 `span: 24` 或等效布局实现。
- 新增、编辑弹窗底部按钮顺序统一为“取消、提交”，取消按钮在左，提交按钮在右。
- 使用 Avue 配置、Element Plus 表单或自定义弹窗表单时均需遵守该规则；若局部组件因特殊结构无法自动对齐，应通过 `src/utils/dialog-form-label.js` 的全局增强、局部样式或 `formslot` 保证 `label` 左侧展示、按列统一宽度、文本右对齐。

### 4.9 审计字段展示规范

- 列表、详情、导出预览等用户可见场景禁止直接展示 `createUser`、`updateUser` 等用户 ID 字段。
- 后端 VO 应额外返回 `createUserName`、`updateUserName` 等姓名字段；前端 Avue 列优先绑定姓名字段。
- “更新人”列统一使用 `prop: 'updateUserName'`，并通过 `src/utils/audit.js` 中的 `formatUpdateUserName(row)` 做兼容兜底。
- 表单提交仍保留后端审计字段机制，前端不得手动提交或覆盖 `createUser`、`updateUser`。

### 4.10 表格排序规范

- 表格的排序默认按照创建时间降序；分页列表应由后端默认按 `create_time DESC` 返回，前端不得在无明确业务要求时覆盖为其它默认排序。

### 4.11 搜索顺序规范

- 当用户已明确列出筛选字段时，搜索栏必须严格按照用户给出的字段清单和顺序展示；不得自行新增、保留、推断或迁移未列出的筛选项。
- 新增/编辑表单字段、表格列字段和搜索筛选字段必须分开理解；除非用户明确要求同步，禁止把表单字段或表格字段擅自加入搜索栏。
- Avue 搜索栏的字段展示顺序按 `searchOrder` **倒序** 渲染，配置时数值越大越靠前。

### 4.12 日期区间搜索规范

- 当同一业务维度的筛选条件是开始/结束日期或时间，并且接口按区间查询时，前端搜索栏必须合并为一个 `searchRange: true` 的区间字段展示。
- 区间字段在页面层统一归一化为后端所需的起止参数，禁止同时保留两个独立的“开始/结束”搜索项。
- 若用户已明确要求展示区间样式，必须严格按区间控件实现，不得退回为两个普通日期控件。
- 修改搜索项顺序时必须同步调整 `searchOrder`，不要依赖 `column` 数组前后位置来控制搜索栏顺序。
- `searchIndex: 4` 仅控制首屏展示数量，不影响 `searchOrder` 的优先级。

---

## 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. 交流语言

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