234 lines
14 KiB
Plaintext
234 lines
14 KiB
Plaintext
---
|
||
description: 萧康云医管理后台（Vben Admin v5 + Vue 3 + TS + Ant Design Vue）代码规范
|
||
alwaysApply: true
|
||
---
|
||
|
||
# 基础规范（所有项目通用）
|
||
|
||
1. 写代码的时候要补充详细的中文注释（每个方法是干嘛的，为什么要这样写），如果是工作区，则所有项目都适用该规则
|
||
2. 注意不要生成太多的空行，上一部分代码和下一部分代码中间的空行不要大于 2 行
|
||
3. 有封装好的方法、组件需要复用，不要重复造轮子
|
||
4. 小程序端的抽屉全部需要用 page-container 来防止用户意外退出页面（记得使用 v-if 而不是 v-show）
|
||
5. 数据库的（created_at、updated_at、deleted_at）统一使用时间戳，不要使用字符串，并且我在查询器中一级格式化成字符串了，无需再次格式化
|
||
|
||
# 全局架构规范
|
||
|
||
## 目录结构规范
|
||
|
||
- 业务页面统一放在 `apps/web-antd/src/views/<端>/<模块>/`（端：system / business / doctor 等）
|
||
- 标准 CRUD 模块目录结构：
|
||
|
||
```
|
||
views/<端>/<模块>/
|
||
├── index.vue # 列表页（Page + Grid + Modal）
|
||
├── api/index.ts # 本模块 API（CRUD）
|
||
├── config/
|
||
│ ├── table.ts # vxe-grid 列定义 + proxyConfig
|
||
│ ├── search.ts # 顶部搜索表单 schema
|
||
│ └── form.ts # 新增/编辑弹窗 form schema
|
||
├── components/
|
||
│ └── modal.vue # 新增/编辑弹窗
|
||
└── utils/ # 模块工具（可选）
|
||
```
|
||
|
||
- 全局复用组件放 `apps/web-antd/src/components/`
|
||
- 表单内可用组件放 `apps/web-antd/src/components/form/components/`，文件名 kebab-case，自动注册为 schema 的 `component` 名（PascalCase 引用）
|
||
|
||
## 强制复用封装（禁止重复造轮子）
|
||
|
||
- 表格统一用 `useVbenVxeGrid`（来自 `#/adapter/vxe-table`），**不要直接 new VxeGrid**
|
||
- 表单统一用 `useVbenForm`（来自 `#/adapter/form`），**不要直接写 `<Form>` + 手动校验**
|
||
- 弹窗统一用 `useVbenModal`（来自 `@vben/common-ui`），**不要用原生 `<Modal>`**
|
||
- 页面外壳统一用 `<Page>` 组件（来自 `@vben/common-ui`）
|
||
- HTTP 请求统一用 `requestClient`（来自 `#/api/request`），**禁止直接 axios / fetch**
|
||
- 行操作和工具栏按钮统一用 `<TableAction>` 组件（来自 `#/components/table-action`）
|
||
- 业务选择器（员工、医生、门店、推广员、地区等）必须复用 `#/components/form/components/*-picker.vue`，不要重写
|
||
|
||
## API 层规范
|
||
|
||
- API 文件统一放在 `<模块>/api/index.ts`
|
||
- 函数命名约定：`get{Entity}List` / `get{Entity}Option` / `get{Entity}Info` / `create{Entity}` / `update{Entity}` / `delete{Entity}`
|
||
- URL 使用 kebab-case，统一前缀变量 `const prefix = 'xxx/'`，**URL 末尾不补 `/`**
|
||
- GET 用 `params`，POST 用 `data`，例如：
|
||
|
||
```ts
|
||
import { requestClient } from '#/api/request';
|
||
const prefix = 'oa-robot/';
|
||
export async function getOaRobotList(data: any) {
|
||
return requestClient.get<any>(`${prefix}list`, { params: data });
|
||
}
|
||
```
|
||
|
||
## 字段命名对齐后端
|
||
|
||
- 数据库字段在前端 schema 的 `field` / `fieldName` 中保持 snake_case（如 `created_at`、`store_id`、`platform_code`），**不要转换为 camelCase**
|
||
- 时间戳字段（`created_at` 等）后端查询器已格式化为字符串，前端**无需再次格式化**
|
||
- TS 变量用 camelCase，常量用 UPPER_SNAKE_CASE，类型用 PascalCase
|
||
|
||
## 表单校验
|
||
|
||
- 必填用字符串规则 `rules: 'required'`（选择项用 `'selectRequired'`），规则定义在 `#/adapter/form.ts` 的 `defineRules`
|
||
- 校验调用统一用 `formApi.validate().then(e => { if (e.valid) {...} })`
|
||
- 必填字段在 schema 中加 `rules: 'required'`，禁止散落 `validator` 写法
|
||
|
||
## 字典/枚举管理
|
||
|
||
- 模块内建 `config/constants.ts`，导出 `{ label, value }[]` 数组，禁止在 schema 中散落字面量
|
||
- 例如：
|
||
|
||
```ts
|
||
export const OA_MESSAGE_TYPE_OPTIONS = [
|
||
{ label: '文本', value: 'text' },
|
||
{ label: 'Markdown', value: 'markdown' },
|
||
];
|
||
```
|
||
|
||
## 路由规范
|
||
|
||
- 业务路由通过后端动态菜单驱动（`xk_menu` 表），**不要在前端 `router/routes/modules/` 静态注册业务路由**
|
||
- `defineOptions({ name: 'PascalCaseName' })` 必须与 `xk_menu.name` 字段一致
|
||
|
||
## Tab 用法
|
||
|
||
- 统一用 antd 原生 `Tabs` + `Tabs.TabPane`，**不要找 Vben 自封装的 Tabs**
|
||
- Tab 选中状态持久化走 `localStorage`（参考 `system-config/index.vue` 的 `TAB_STORAGE_KEY` 模式）
|
||
|
||
## 抽屉用法（小程序端，admin 不涉及）
|
||
|
||
- 小程序端的抽屉用 `page-container` + `v-if`（不是 `v-show`）防止用户意外退出页面
|
||
|
||
## 中文注释
|
||
|
||
- 每个 `<script setup>` 顶部说明模块用途
|
||
- 每个主要函数（特别是有业务逻辑的）必须有中文注释
|
||
- 复杂的 schema 字段配置要注释意图
|
||
|
||
## 空行控制
|
||
|
||
- 上一部分代码和下一部分代码中间空行不超过 2 行
|
||
|
||
## Vben 组件使用规范
|
||
|
||
### VbenModal（来自 @vben/common-ui）
|
||
|
||
- 创建弹窗必须用 `useVbenModal`，禁止直接用 antd `Modal` 或原生 `<dialog>`
|
||
- 抽离弹窗内容到子组件时，外层用 `connectedComponent` 参数连接，内外组件共享 `modalApi`
|
||
- 底部按钮扩展 slot 优先级：`prepend-footer`（取消按钮左侧）> `center-footer`（取消/确定之间）> `append-footer`（确定右侧）
|
||
- **严禁覆盖 `#footer` slot**，会丢失默认的取消/确定按钮和 loading 行为
|
||
- 表单提交 loading 走 `modalApi.setState({ confirmLoading: true })`，禁止自己写 button loading
|
||
- 提交防抖/防重复用 `modalApi.lock()` / `unlock()`（>5.5.3），禁止手动 disabled
|
||
- 拖拽开 `draggable: true`，需要拖出可视区时同时开 `overflow: true`
|
||
- 数据回填走 `modalApi.setData()` + `onOpenChange(isOpen) { const data = modalApi.getData() }`
|
||
|
||
### VbenDrawer（来自 @vben/common-ui）
|
||
|
||
- 创建抽屉必须用 `useVbenDrawer`，禁止直接用 antd `Drawer`
|
||
- 底部按钮扩展 slot 与 Modal 一致：`prepend-footer` / `center-footer` / `append-footer`
|
||
- **同样严禁覆盖 `#footer` slot**
|
||
- 关闭前校验用 `onBeforeClose`（>5.5.2 支持 Promise），禁止自己拦截
|
||
- 提交防抖/防重复用 `drawerApi.lock()` / `unlock()`（>5.5.3）
|
||
- 小程序端的「抽屉」概念与此无关，小程序端按现有规则用 `page-container`
|
||
|
||
### VbenVxeTable（来自 #/adapter/vxe-table）
|
||
|
||
- 表格必须用 `useVbenVxeGrid`，禁止直接 `new VxeGrid` 或 antd `Table`
|
||
- 远程数据加载走 `gridOptions.proxyConfig.ajax.query`，**禁止自己 fetch 后 `data = []` 赋值**
|
||
- query 接口返回结构必须匹配适配器配置：`{ items: [], total: number }`（在 `apps/web-antd/src/adapter/vxe-table.ts` 的 `response` 字段统一配置）
|
||
- 分页参数从 `{ page }` 解构取：`page.currentPage` / `page.pageSize`，禁止自己读 URL
|
||
- 刷新表格用 `gridApi.query()`（保留当前页）或 `gridApi.reload()`（回到第一页），禁止整页 `window.location.reload()`
|
||
- 工具栏按钮插 slot：`toolbar-actions`（标题左侧）、`toolbar-tools`（工具按钮左侧），禁止改 vxe-grid 内部模板
|
||
- 表格 loading 用 `gridApi.setLoading(bool)`，禁止自己遮罩
|
||
- 搜索表单由 `formOptions` 配置（底层是 Vben Form），开关走 `gridOptions.toolbarConfig.search = true`
|
||
- 自定义列渲染走 `slots: { default: 'action' }` + Grid 子组件内 `<template #action="{ row }">`，禁止 column 渲染函数里写 JSX
|
||
|
||
### VbenForm（来自 #/adapter/form）
|
||
|
||
- 表单必须用 `useVbenForm`，禁止直接 `<form>` 或 antd `Form`
|
||
- 动态修改 schema 必须用 `formApi.updateSchema([...])`，**vben form 没有 `setComponentProps` 这个方法**（这是已踩过的坑）
|
||
- 取值/赋值用 `formApi.getValues()` / `formApi.setValues(obj)`，禁止自己 `v-model` 收集
|
||
- 校验用 `formApi.validate().then(e => { if (e.valid) {...} })` 或 `formApi.validateAndSubmitForm()`
|
||
- 必填规则用字符串 `'required'` / `'selectRequired'`，规则在 `#/adapter/form.ts` 的 `defineRules` 注册
|
||
- schema 中字段名（`fieldName`）必须与后端字段 snake_case 对齐，禁止前端 camelCase
|
||
- 密码/敏感字段用 `VbenInputPassword` 组件，禁止用 `VbenInput` 配 `type="password"`
|
||
- 单选/多选选项来自接口时，必须在弹窗/页面 `onMounted` 或 `onOpenChange` 里拉取后通过 `updateSchema` 注入，禁止写死常量
|
||
|
||
# 专项模块规范
|
||
|
||
## OA 通知模块前端规则
|
||
|
||
### 组件与封装复用
|
||
|
||
- 所有 OA 配置入口（系统配置 tab、CRUD 页面、员工 OA 账号弹窗）必须复用 `Tabs.TabPane`、`useVbenVxeGrid`、`useVbenModal`、`useVbenForm`，禁止用原生 antd 表格/表单
|
||
|
||
### 平台动态化（禁止写死）
|
||
|
||
- **平台列表必须从接口 `oa-platform/list` 动态拉取**，禁止在前端写死 `['work_wechat', 'dingtalk', 'feishu']` 常量数组
|
||
- 系统配置 tab 中的平台开关行、机器人表单中的平台下拉、场景表单中的机器人分组，都要走接口动态渲染
|
||
- 平台编码统一为字符串 snake_case（如 `work_wechat`、`dingtalk`、`feishu`），与后端 `xk_oa_platform.platform_code` 字段对齐
|
||
|
||
### 系统配置 tab 交互
|
||
|
||
- 系统配置 tab 中的「总开关关闭」必须禁用下方所有平台子开关（视觉上置灰），禁止总开关关闭时仍能切换子开关
|
||
- 平台子开关切换必须立即调 `oa-platform/update-enabled` 接口，**禁止依赖保存按钮批量提交**（避免总开关与子开关状态不一致）
|
||
- 系统配置页的总开关走现有 `getSystemConfigList` / `saveSystemConfig` 接口（config_key = `oa_notify_enabled`），**禁止新建专用接口**
|
||
|
||
### 表单字段约定
|
||
|
||
- @ 人配置必须按平台分组（用 Tabs 或 Collapse 分组），员工必须从 `xk_admin` 表选择（复用员工 picker 组件）
|
||
- OA 机器人表单中的 webhook、secret 字段必须用密码型输入框（`InputPassword`），禁止明文展示
|
||
- OA 场景表单中的机器人多选必须按平台分组展示（用 `Tabs` 或 `Collapse` 分组）
|
||
|
||
### 消息类型全量支持（数据库驱动 schema）
|
||
|
||
- 场景弹窗每个平台 Tab 内的消息类型选项**必须**通过 `GET /oa-scene/message-types` 接口动态拉取，
|
||
按 `platform_code` 过滤当前平台支持的所有 `message_type`
|
||
- 每个消息类型对应的 payload 表单**必须**按后端返回的 `payload_schema`（JSON 字符串）动态渲染，
|
||
禁止前端写死 schema（数据库可启停类型，前端硬编码会不同步）
|
||
- payload 字段渲染规则（与后端 `payload_schema` 约定）：
|
||
- `Textarea`：多行文本
|
||
- `Input` / `InputNumber`：单行文本/数字
|
||
- `RadioGroup` / `Select`：选项组
|
||
- `GalleryPickLink`：素材库选择器，透传 `props.acceptTypes: number[]` 过滤文件类型
|
||
- `TemplateCardEditor`：企微模板卡片专用编辑器（用 `views/system/oa-scene/components/template-card-form.vue`）
|
||
- 提交结构：`message_config: { platform_code: { message_type, payload } }`
|
||
|
||
### image-gallery-picker 文件类型过滤
|
||
|
||
- `image-gallery-picker.vue` 和 `gallery-pick-link.vue` 都支持 `acceptTypes?: number[]` prop
|
||
- 取值对应 `xk_file_type.value`：1=图片、2=视频、3=音频、6=文件 等
|
||
- 不传 `acceptTypes` 时显示全部类型（默认行为，保持向后兼容）
|
||
- 传数组时只展示匹配类型 tab，且自动锁定到第一个匹配类型
|
||
- OA 场景中图片字段必须传 `[1]`、语音字段传 `[3]`、文件字段传 `[6]`，避免用户选错类型
|
||
|
||
### 通用拖拽可视化编辑器（`components/oa-template-card-editor/`）
|
||
|
||
- 任何「左侧组件库 → 右侧画布拖拽组装 → 自动生成 JSON」的需求，**必须复用此通用组件**，禁止重复造轮子
|
||
- schema 驱动：新增块类型只需扩展 `BlockSchema[]` 配置，禁止改组件内部
|
||
- SortableJS 用法参照 `views/system/role/components/quick-nav-transfer.vue`（动态 import `sortablejs/modular/sortable.complete.esm.js`）
|
||
- 双向绑定走 `v-model`（`modelValue` + `update:modelValue`），禁止内部直接修改 props
|
||
- OA 场景中的企微模板卡片必须用 `views/system/oa-scene/components/template-card-form.vue`（在通用编辑器之上做 OA 封装）
|
||
|
||
### 测试发送（全类型循环）
|
||
|
||
- OA 机器人 modal 的「测试发送」必须循环跑该平台支持的所有消息类型（单平台最多 8 种）
|
||
- 后端返回 `results` 数组，前端必须遍历分类型展示成功/失败（不要只展示第一条）
|
||
- 测试按钮 loading 用独立状态（不要复用 modal 的 `confirmLoading`）
|
||
- 测试发送结果以列表形式展示在表单下方，每种类型显示状态/耗时/错误信息
|
||
- 测试发送支持两套入口（共用 `testSendOaRobot` API）：
|
||
- **表单弹窗内测试**（modal.vue）：用于「保存前验证密钥」，直接传 webhook_url/secret（不带 id）
|
||
- **行级测试**（独立组件 `test-send-modal.vue`）：用于列表中已有机器人，仅传 `id`，后端自动取已加密密钥
|
||
- 行级测试弹窗入参：`test_content` + `test_at_all` 开关 + `test_mobiles` 手机号多选
|
||
- 飞书 webhook 不支持手机号 @，前端必须在飞书平台下隐藏手机号字段并提示用户（仅 @all 有效）
|
||
|
||
### 群聊绑定（按平台过滤的 N:N 多选）
|
||
|
||
- 「OA群聊管理」是独立菜单（pid=232 OA 通知父级下，菜单 id=233，路由 `/system/oa-chat`）
|
||
- 群聊管理页结构必须与 `oa-robot` 一致：`index.vue + api/index.ts + config/{table,search,form}.ts + components/modal.vue`
|
||
- 机器人表单中的「绑定群聊」字段必须用 `Checkbox.Group`：
|
||
- 群聊列表通过 `getOaChatListByPlatform()` 一次性拉取全量（按平台分组的对象）
|
||
- 前端按当前 `platform_code` 过滤展示（平台切换时自动过滤掉不属于当前平台的勾选）
|
||
- 平台切换通过 `componentProps.onChange` 监听（vben form 字段值变化无现成 watch，必须通过 schema 注入 onChange 回调）
|
||
- 编辑场景下，机器人详情接口返回 `chat_ids: number[]`，前端 `selectedChatIds` 直接回显
|
||
- 提交时把 `chat_ids` 数组合并到 payload（后端 `OaRobotController::notRequest` 已包含该字段）
|
||
- 列表展示用后端拼接好的 `chat_names` 字符串（按「、」拼接），详情接口才返回 `chat_ids` 数组
|