184 lines
5.0 KiB
Markdown
184 lines
5.0 KiB
Markdown
# 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）
|