# 3.9 前端联调指引

:::tip 概述
前端每个列表模块由三件套组成：`api/{域}/{模块}.ts`（接口）、`views/{域}/{模块}/columns.ts`（表格列）、`views/{域}/{模块}/querySchemas.ts`（筛选表单）。三者与后端 gmeta/Req 字段严格对齐，本节以 example 模块真实代码演示。
:::

## 接口模块（真实代码，摘自 ui/src/api/tool/example.ts）

```ts
import { http } from '@/utils/http/axios';

/**
 * 案例演示模块接口
 *
 * 提供案例演示的增删改查及导入导出接口调用。
 */

/**
 * 获取案例演示分页列表
 *
 * @param params 查询参数，包含 pageNo、pageSize 及业务筛选条件
 * @returns 分页结果，含 records、total、size、current、pages
 */
export function getExamplePage(params?: Record<string, any>) {
  return http.request({
    url: '/example/page',
    method: 'GET',
    params,
  });
}

/**
 * 根据 ID 获取案例演示详情
 *
 * @param id 案例演示ID
 * @returns 案例演示详情数据
 */
export function getExampleDetail(id) {
  return http.request({
    url: '/example/detail/' + id,
    method: 'get',
  });
}

/**
 * 添加案例演示
 *
 * @param data 案例演示数据
 * @returns 新记录的 ID
 */
export function exampleAdd(data: any) {
  return http.request({
    url: '/example/add',
    method: 'POST',
    data,
  });
}
```

要点：url 不含 `/api`（axios baseURL 已是 `/api`）；GET 用 `params`、写操作用 `data`；路径与后端 gmeta path 逐条对齐。

## 筛选表单（真实代码，摘自 views/tool/example/querySchemas.ts）

```ts
import { FormSchema } from '@/components/Form/index';

/**
 * 案例演示查询表单配置
 *
 * 定义列表页搜索区域的表单项，字段来自 filter_fields，
 * 按字段类型自动选择组件：
 * - 字符型用 Input；
 * - 带选项的字段用 Select；
 * - 纯数字字段用 InputNumber；
 * - 日期字段用 DatePicker。
 */
export const schemas: FormSchema[] = [
  {
    // 案例名称
    field: 'name',
    component: 'Input',
    label: '案例名称',
    componentProps: {
      placeholder: '请输入案例名称',
      clearable: true,
    },
  },
  {
    // 案例类型
    field: 'type',
    component: 'Select',
    label: '案例类型',
    componentProps: {
      placeholder: '请输入案例类型',
      clearable: true,
      // 选项列表：值用于查询，标签用于展示
      options: [
        { label: '类型1', value: 1 },
        { label: '类型2', value: 2 },
        { label: '类型3', value: 3 },
        { label: '类型4', value: 4 },
      ],
    },
  },
];
```

## 筛选对齐三件套（2026-10-14 定稿）

```text
前端 querySchemas.ts 每个输入框
  ↔ XxxPageReq 同名驼峰字段
    ↔ logic spec 声明

字符串 Input   → LikeFields（逐列模糊，值取 req 同名字段）
Select/InputNumber → EqFields（等值，零值跳过）
关键词框       → KeywordFields（能力保留在基座，模块按需声明）
```

example 对应关系：`querySchemas` 的 `name`（Input）↔ `ExamplePageReq.Name` ↔ `LikeFields: []string{"name"}`；`type/status`（Select）↔ EqFields。**导出统一走 `spec.applyFilters` 与列表同套筛选**（导出=所见）。

## 表格列（真实代码，摘自 views/tool/example/columns.ts）

```ts
import { h } from 'vue';
import { ElAvatar, ElTag } from 'element-plus';

/**
 * 案例演示表格列配置
 *
 * 定义列表页表格的显示列，包含多选框、ID、各业务字段及审计字段。
 * 字段按类型自动选择渲染方式：图片用 ElAvatar、选项用 ElTag、
 * 链接用 a 标签，其余为普通文本。
 */
export const columns = [
  {
    type: 'selection', // 多选框列
  },
  {
    label: 'ID',
    prop: 'id',
    fixed: 'left',
    width: 50,
  },
  {
    label: '案例图片',
    prop: 'avatar',
    minWidth: 120,
    // 图片渲染：以方形头像形式展示
    render(record) {
      return h(ElAvatar, {
        size: 48,
        src: record.row.avatar,
        shape: 'square',
        fit: 'fill',
      });
    },
  },
  // …
];
```

枚举列显示 `{field}Text`（如 `statusText`，由后端字典填充），保证文案唯一真相在字典管理页。

## 页面文件组织

```text
views/tool/example/
├── index.vue        # 列表页（分页表格 + querySchemas 筛选区 + 增删改入口）
├── edit.vue         # 新增/编辑弹窗表单
├── detail.vue       # 详情视图
├── columns.ts       # 表格列配置
└── querySchemas.ts  # 筛选表单配置
```

## 联调自检清单

+ [ ] api 模块 url 与后端 gmeta path 一致（无 `/v1`，baseURL 补 `/api`）
+ [ ] querySchemas field 名与 XxxPageReq json 字段驼峰一致
+ [ ] 字符串筛选项后端已声明 LikeFields，Select/InputNumber 已声明 EqFields
+ [ ] 枚举列展示 {field}Text；字典编码与 spec SerializeMaps 一致
+ [ ] 文件字段读侧已由基座补完整 URL，直接绑定展示组件
+ [ ] 前端按钮已加权限指令（对齐 gmeta permission）