b2894lxlx/tms-erp-web
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
master
tms-erp-web/AGENTS.md
b2894lxlx f9f8221870 1、完善项目 
2、完善合同
3、完善费用项
4、司机管理对接OCR
5、完善运输计划
6、完善临时额度
2026-08-04 12:17:49 +08:00

18 KiB
Raw Permalink Blame History

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. 常用命令

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: 新增功能、优化增强
🐛 :bug: 修复 Bug
⚡ :zap: 性能优化、问题修复
🎉 :tada: 重大版本发布
💄 :lipstick: 样式调整
♻️ :recycle: 代码重构
🔧 :wrench: 配置修改
📝 :memo: 文档更新
🔥 :fire: 删除代码/文件

9. 交流语言

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