# 中后台前端页面设计规范

> 基于 itfx-front 项目现有技术栈与实现，整理的一套通用、可直接落地的前端设计规范。  
> 后续开发须遵循本规范，确保视觉与交互一致性。

---

## 一、技术栈约定

| 类别 | 技术选型 | 版本/说明 |
|------|----------|-----------|
| 框架 | Vue 3 | 使用 Composition API、`<script setup>` |
| UI 库 | Arco Design Vue | 主 UI 框架，优先使用 |
| 辅助 UI | Element Plus | 仅在特殊场景使用 |
| 表格 | vxe-table / Handsontable | 见「表格」章节 |
| 构建 | Vite | 6.x |
| 状态 | Pinia | |
| 国际化 | vue-i18n | |
| 样式 | Less + UnoCSS + 全局 CSS 变量 | |
| 路由 | vue-router | 4.x |

---

## 二、布局规范

### 2.1 整体结构

```
a-layout (垂直)
├── TopNav（顶部导航，fixed）
├── a-layout-content
│   ├── paddingTop: 顶部导航高度 + Tab 栏高度（可选）
│   └── PageLayout（router-view + keep-alive）
└── Footer（可选）
```

**约定：**

- 主内容背景色：`#f0f3f4`
- 页面容器使用 `[class$='-container']`，统一 `padding: 16px`
- 内容区域使用 `overflow: hidden`、`height: 100%` 保证高度正确

### 2.2 页面内容结构

单页内容推荐结构：

```html
<div class="xxx-container" style="background-color: #fff;">
  <!-- 1. 页面头部操作区（可选） -->
  <div class="page-header">
    <a-space>...</a-space>
    <a-space>...</a-space>
  </div>

  <!-- 2. 表格工具栏 -->
  <div class="table-toolbar">
    <div class="toolbar-left">主操作、批量操作</div>
    <div class="toolbar-right">分页控制等</div>
  </div>

  <!-- 3. 表格/表单内容 -->
  ...
</div>
```

### 2.3 工具栏布局

- 使用 `table-toolbar` 作为表格上方工具栏
- 左侧 `toolbar-left`：新增、删除、导出等主操作
- 右侧 `toolbar-right`：分页、筛选等
- 使用 `a-space :size="8"` 或 `display: flex; gap: 8px` 控制按钮间距

### 2.4 响应式断点（Less）

```less
@screen-xs: 480px;   // 手机
@screen-sm: 576px;   // 平板
@screen-md: 768px;   // 小屏
@screen-lg: 992px;   // 桌面
@screen-xl: 1200px;  // 大屏
@screen-xxl: 1600px; // 超大屏
```

---

## 三、色彩规范

### 3.1 主题色（CSS 变量）

通过 `:root` 统一管理，运行时由 `themeColor` 工具更新：

```css
:root {
  --app-primary-color: #2D8C8C;
  --app-primary-color-hover: #2A7F7F;
  --app-primary-color-light: #e6f7f7;
  --app-navbar-bg: #2D8C8C;
  --app-sidebar-bg: #2D8C8C;
  --app-button-gap: 8px; /* 相邻按钮间距 */
}
```

**约定：**

- 主色：`var(--app-primary-color)` 或 `#2D8C8C`
- Hover 色：`var(--app-primary-color-hover)`
- 浅底（选中背景）：`var(--app-primary-color-light)`
- 页面背景：`var(--color-bg-1)`（Arco）
- 内容区背景：`#fff` 或 `#f0f3f4`

### 3.2 组件配色

- 主按钮、Switch、Tabs 指示线、菜单选中：使用主题色
- 日期选择器、Input focus：`border-color: var(--app-primary-color)`
- 链接激活态：`color: var(--app-primary-color)`

---

## 四、字体规范

### 4.1 字体栈

```css
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC",
  "Microsoft YaHei", Inter, Roboto, "Helvetica Neue", Arial, sans-serif;
```

代码字体：

```css
font-family: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono",
  "Courier New", monospace;
```

### 4.2 字号与行高

- 全局基准字号：`14px`
- 表单、按钮、输入框：`14px`
- 日期选择器、部分紧凑区域：`12px`（如 `.notice` 内）
- 菜单文字：`12px`，`font-weight: bold`

---

## 五、组件规范

### 5.1 按钮

- 高度：`32px`，`border-radius: 4px`
- 图标按钮：`32px × 32px` 正方形
- **相邻按钮间距**：统一 `8px`
  - 使用 `a-space :size="8"` 或 `gap: 8px` / `gap: var(--app-button-gap)`
  - 适用于工具栏、表格操作列、弹窗底部按钮组
- 主操作使用 `type="primary"`

### 5.2 输入类（Input / Select / Picker）

- 统一高度：`32px`（Input）、`28px`（Picker）
- `border-radius: 4px`
- Focus / Hover 使用主题色 border 与 shadow

### 5.3 卡片 / 弹窗 / 下拉

- `border-radius: 8px`（Card、Modal、Popover、Dropdown、Drawer、Table、Tag、Alert、Message、Notification）

### 5.4 Pro 系列组件

| 组件 | 用途 |
|------|------|
| FormPro | 配置驱动表单，itemList + comp + compProps |
| TablePro | VxeGrid 封装，tableConfig + api + formConfig |
| CustomList | 自定义列 + TablePro，支持列管理 |
| HandsontablePro | 类 Excel 表格 |
| ModalPro | 弹窗，配合 useModal |
| DrawerPro | 抽屉 |
| SelectPro | 增强选择器 |
| JsonEditorPro / JsonDiffPro | JSON 编辑与对比 |
| CodeMirror | 代码编辑 |

**约定：**

- 增强型封装统一使用 `Pro` 后缀
- 优先使用 Pro 组件，减少重复造轮子

### 5.5 消息与确认

- 使用 `$baseMessage`、`$baseConfirm`（如有）
- 或 Arco 的 `Message`、`Modal.confirm`、`a-popconfirm`

---

## 六、表单规范

### 6.1 布局

- 表单类型：`horizontal`、`vertical`、`inline`
- 标签列：`label-col-props="{ span: 6 }"`（或 5）
- 内容列：`wrapper-col-props="{ span: 16 }"`（或 19）
- FormPro：`labelColProps: { span: 5 }`、`wrapperColProps: { span: 19 }`、`rowGutter: 20`、`defaultSpan: 6`

### 6.2 FormPro 配置示例

```ts
itemList: [
  {
    comp: 'AInput',
    field: 'name',
    label: '名称',
    required: true,
    span: 6,
    rules: [{ required: true, message: '请输入名称' }],
    compProps: { placeholder: '请输入' },
  },
  {
    comp: 'ASelect',
    field: 'status',
    label: '状态',
    compProps: { options: [...], placeholder: '请选择' },
  },
]
```

### 6.3 校验

- 使用 Arco Form 的 `rules`
- 提交前调用 `formRef.validate()` 统一校验
- 必填项使用 `required: true` 并配置 `message`

---

## 七、表格规范

### 7.1 组件选择

| 场景 | 组件 | 说明 |
|------|------|------|
| 常规 CRUD 列表 | TablePro | 带搜索表单、分页、API 集成 |
| 自定义列 + 列管理 | CustomList | 包裹 TablePro |
| 类 Excel 编辑 | HandsontablePro | 单元格编辑、复制粘贴 |
| 简单列表（角色、菜单等） | a-table | Arco 原生 |

### 7.2 TablePro 配置

- `tableConfig`：columns、toolbarConfig 等
- `api`：分页接口，参数含 `pageIndex`、`pageSize`、表单值
- `formConfig`：搜索区域
- `columnConfig.useKey: true`、`resizable: true`
- `showOverflow: 'tooltip'`

### 7.3 分页

- 可选 pageSize：`10 / 30 / 50 / 100`（按需裁剪）
- 默认 pageSize：`30`
- 接口参数：`pageIndex`、`pageSize`；返回：`totalCount`、`items` 或 `data.list`

### 7.4 操作列

- 编辑、删除、分配等使用 `a-button type="text" size="small"`
- 删除使用 `a-popconfirm`
- 操作按钮需权限控制（见「权限」）

---

## 八、交互规范

### 8.1 弹窗 / 抽屉

- 使用 `ModalPro` + `useModal()` 管理显隐与数据
- 标准流程：`openModal(true, data)` → 编辑 → `setLoading(true)` → 提交 → 成功 → `closeModal()`、刷新列表
- 弹窗宽度：常规 `600px`，复杂表单 `800px` 或更高

### 8.2 加载与空态

- 表格：`loading` 状态
- 弹窗提交：`confirm-loading`
- 空数据：使用 Arco `Empty` 或统一空态组件

### 8.3 按钮顺序

- 主操作（确定、保存）在右侧
- 取消 / 重置在左侧
-  destructive 操作（删除）单独放置，并加确认

---

## 九、权限规范

### 9.1 权限格式

`Module.Resource.Action`，如：

- `Rbac.Roles.Create`
- `Rbac.Users.Update`
- `Api.Interfaces.Query`
- `Track.Orders.Query`

### 9.2 使用方式

**模板：**

```vue
<a-button
  v-if="hasPermission('Rbac.Roles.Create')"
  type="primary"
  @click="handleAdd"
>
  新增
</a-button>
```

**路由：**

```ts
{
  path: '/system/roles',
  meta: { permission: 'Rbac.Roles.Query' },
}
```

**工具函数：**

```ts
import { hasPermission, hasAnyPermission, hasAllPermissions, hasRole } from '@/utils/rbac-permission';
```

### 9.3 菜单

- 菜单基于 RBAC `menus` 与 `userMenuIdSet` 过滤
- 无权限的菜单项不展示

---

## 十、命名规范

### 10.1 文件与目录

| 类型 | 规范 | 示例 |
|------|------|------|
| 页面组件 | `index.vue` 置于功能目录下 | `views/api/upstreamInterface/index.vue` |
| 子组件 | PascalCase 或 kebab-case | `ServiceProviderInterfaceModal.vue`、`AccountList.vue` |
| 布局组件 | kebab-case | `top-nav`、`tab-bar`、`page-layout` |
| 共享组件 | PascalCase | `FormPro`、`TablePro`、`CustomList` |
| API 模块 | camelCase 或 PascalCase | `interface-serviceProvider`、`TrackOrder` |
| Store 模块 | kebab-case | `rbac-user`、`tab-bar`、`app` |
| 国际化 | `zh-CN.ts`、`en-US.ts` | `locale/zh-CN.ts` |

### 10.2 代码命名

| 类型 | 规范 |
|------|------|
| 变量 / 方法 | camelCase |
| 常量 | UPPER_SNAKE_CASE 或 camelCase |
| 类型 / 接口 | PascalCase |
| 组件名 | PascalCase |

### 10.3 路由

- path：camelCase，如 `/api/upstreamInterface`、`/track/kpiEarlyWarningConfig`
- name：PascalCase，如 `InterfaceDetailTest`

### 10.4 国际化 Key

- 格式：`模块.资源.键` 或 `common.xxx`
- 示例：`system.role.actions.add`、`common.search`、`common.reset`

---

## 十一、国际化规范

### 11.1 结构

- 根：`src/locale/zh-CN.ts`、`en-US.ts`
- 按页面拆分：`views/xxx/locale/zh-CN.ts`，在根 locale 中合并

### 11.2 使用

```vue
<template>{{ t('common.search') }}</template>
<script setup>
const { t } = useI18n();
</script>
```

### 11.3 必备 Key

- `common.search`、`common.reset`、`common.add`、`common.delete`、`common.editSuccess`、`common.addSuccess`、`common.saveSuccess`
- `common.selectPlaceholder`、`common.actions`、`common.viewDetail`

---

## 十二、API 与请求规范

### 12.1 分页接口

**请求：**

```ts
{
  pageIndex: number;
  pageSize: number;
  // 其它搜索参数
}
```

**响应：**

```ts
{
  totalCount: number;
  items: T[];  // 或 data.list
}
```

### 12.2 错误处理

- 使用统一的 axios 拦截器（如 `rbac-error-handler`）
- 401 自动跳转登录；其它错误统一提示

---

## 十三、样式约定

### 13.1 作用域

- 组件内使用 `scoped`
- 覆盖第三方样式时使用 `:deep()` 或全局类

### 13.2 容器类

- 页面根容器：`xxx-container`（如 `role-page`、业务相关命名），保证 `padding: 16px`
- 表格工具栏：`table-toolbar`、`toolbar-left`、`toolbar-right`

### 13.3 按钮间距

- 相邻 `arco-btn` 之间：`margin-left: 8px`（全局已统一）
- 使用 `a-space :size="8"` 包裹一组按钮

---

## 十四、检查清单（新页面开发）

- [ ] 使用 `xxx-container` 或等效布局结构
- [ ] 工具栏使用 `table-toolbar`、`toolbar-left`、`toolbar-right`
- [ ] 按钮、输入框符合全局样式（高度、圆角）
- [ ] 使用主题色变量，不硬编码 `#2D8C8C`
- [ ] 弹窗 / 抽屉使用 ModalPro / DrawerPro + useModal
- [ ] 表单使用 FormPro 或统一 label/span
- [ ] 表格优先 TablePro / CustomList / HandsontablePro
- [ ] 分页 10/30/50/100，默认 30
- [ ] 操作按钮按权限使用 `hasPermission`
- [ ] 路由 meta 配置 `permission`
- [ ] 文案通过 i18n，不写死中文
- [ ] 命名符合本规范（文件、路由、变量、i18n key）

---

## 附录：常用代码片段

### 页面头部 + 权限按钮

```vue
<div class="page-header">
  <a-space>
    <a-button
      v-if="hasPermission('Module.Resource.Create')"
      type="primary"
      @click="handleAdd"
    >
      <template #icon><icon-plus /></template>
      {{ t('common.add') }}
    </a-button>
  </a-space>
  <a-space>
    <a-button @click="loadData">
      <template #icon><icon-refresh /></template>
    </a-button>
  </a-space>
</div>
```

### 表格操作列（编辑 / 删除）

```vue
<template #action="{ record }">
  <div class="action-buttons">
    <a-button
      v-if="hasPermission('Module.Resource.Update')"
      type="text"
      size="small"
      @click="handleEdit(record)"
    >
      <IconEdit />
    </a-button>
    <a-popconfirm
      v-if="hasPermission('Module.Resource.Delete')"
      :content="t('common.deleteConfirm')"
      @ok="handleDelete(record.id)"
    >
      <a-button type="text" size="small">
        <IconDelete />
      </a-button>
    </a-popconfirm>
  </div>
</template>
```

### FormPro 查询表单

```vue
<FormPro
  ref="formProRef"
  :item-list="formItemList"
  :button-config="{ showBtn: true }"
  @submit="handleSearch"
  @reset="handleReset"
/>
```

---

*文档版本：1.0 | 更新日期：2025-03-21*