298 lines
18 KiB
Markdown
298 lines
18 KiB
Markdown
# 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` 或在操作按钮、操作下拉项中嵌入图标；顶部工具栏按钮不受此条限制。
|
||
- `.avue-crud__header` 顶部间距统一为 `12px`。
|
||
- 分页组件整体靠右展示，必须展示接口返回的数据总条数，`X条/页` 的页容量选择器必须放在总条数右侧。
|
||
- `.basic-container__card` 的直接子级 `.el-card__body` 内边距统一去除，保持 `padding: 0`
|
||
- 所有 CRUD 页面搜索栏需与下方表格拆分为独立区域，两者垂直间距统一为 `8px`。
|
||
- 所有 CRUD 页面搜索栏操作按钮（搜索、清空等）需在搜索表单下方独占一行并放置在最右侧；搜索条件超过一行时必须显示“展开/折叠”，默认折叠且仅展示一行搜索条件；一行布局默认展示 4 个筛选项，Avue 配置统一使用 `searchIndex: 4`。
|
||
- 所有 CRUD 页面中新增、批量导入等顶部按钮组行不需要背景色，应保持透明背景。
|
||
- 所有 `.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. 交流语言
|
||
|
||
与用户交互时全程使用中文。若需临时切换语言，须明确告知。
|