# 6.19 案例演示模块

:::tip 概述
案例演示模块（goframe_example，tool 域）是官方完整样板：七件套 + 状态切换 + Excel 导入导出 + 文件字段 + 字典填充，前端五件套齐备。第 3 章模块开发实战全程以它为参照。
:::

## 接口清单

```text
七件套 + PUT /api/example/status（sys:example:status）
  + POST /api/example/import（sys:example:import）
  + GET  /api/example/export（sys:example:export）
sys:example:{page|list|detail|add|update|delete|batchDelete|status|import|export}
```

## 后端声明（真实代码，摘自 internal/logic/example.go）

```go
// exampleSerializeMaps 枚举字段到字典编码的映射
// {field}Text 由基座自动填充
var exampleSerializeMaps = map[string]string{
	"status": "example_status",
}

// exampleSpec 案例演示模块声明
//
// 采用声明式实现：查询、输出与规则均在声明中定义，方法仅做委托
var exampleSpec = ModuleSpec[v1.ExampleItem, v1.ExampleItem, v1.ExampleDetailRes]{
	Model:         dao.Example.Ctx,
	LikeFields:    []string{"name"},
	EqFields:      []string{"type", "status"},
	OrderBy:       "sort, id",
	SerializeMaps: exampleSerializeMaps,
	FileFields: []string{
		"avatar",
	},
	FileSaveDir: "example",
	ToData:      exampleToData,
}
```

覆盖的基座能力：Like/Eq 筛选、默认排序、字典文本填充、单文件字段两段式、全量表单转换。

## 扩展方法（手写示范）

+ **Status**：非标准方法手写实现（dao 直接 Update 单列）
+ **Import**：excel.ReadSheet 逐行校验写入，返回成功/失败统计与逐行原因
+ **Export**：`exampleSpec.applyFilters` 与列表同套筛选 → DictGetText 枚举转文本 → excel.WriteSheet

完整代码见 [3.10 完整代码清单](../guide/code-list)。

## 前端五件套（ui/src/views/tool/example/）

| 文件 | 职责 |
|------|------|
| index.vue | 列表页（分页表格 + querySchemas 筛选 + 增删改入口） |
| edit.vue | 新增/编辑弹窗表单 |
| detail.vue | 详情视图 |
| columns.ts | 表格列配置（图片列 ElAvatar 渲染示范） |
| querySchemas.ts | 筛选表单配置（Input/Select 示范） |

接口模块：`ui/src/api/tool/example.ts`（getExamplePage/exampleAdd…）。

## 学习路径建议

```text
1. 跑通页面：登录 → 工具 → 案例演示 → 增删改查/导入导出全流程点一遍
2. 对照后端：api/v1/example.go（gmeta+gvalid）→ logic/example.go（spec+委托）
   → controller/service（透传/接口）→ dao/example.go（钩子+Ctx）
3. 改一个字段：加 remark 列 → 四处补齐（3.3 改字段实战）
4. 仿写新模块：以 example 为骨架手动写一遍，或用生成器产出后对照差异
```

## 生成器视角

example 也是生成器产物的示范形态（ModuleSpec 基座风格的完整可用实现）。生成器对含枚举注释/图片列的表会产出同样的模式：

```sh
go run ./cmd/generator -tables "goframe_example|案例演示表"   # 产出与 example 同构的全套文件
```