签入版本

2026-10-20 21:53:26 +08:00
parent 5cc3da657c
commit b33799aa63
427 changed files with 32547 additions and 1 deletions
@@ -0,0 +1,80 @@
+# 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 同构的全套文件
+```