# 3.1 概述与目标

:::tip 概述
本章以项目内置的 **example（案例演示，`gin_example`）** 模块为例，从数据库建表到前端页面联调，完整演示开发全流程。学完本章后，你将掌握新增业务模块的标准步骤。
:::

## 开发流程总览

```text
┌──────────┐
│ 1. 建表   │  创建 gin_ 前缀表（含公共审计字段）
└────┬─────┘
     │
     ▼
┌──────────┐
│ 2. dto   │  internal/model/dto/{module}.go —— 请求/响应契约 + 校验标签
└────┬─────┘
     │
     ▼
┌──────────┐
│ 3. repo  │  internal/repository/{module}.go —— XxxRepo + Base，统一 Ctx(ctx)
└────┬─────┘
     │
     ▼
┌──────────┐
│ 4. service│ internal/service/{module}.go —— sXxx + ModuleSpec 声明 + 手写逻辑
└────┬─────┘
     │
     ▼
┌──────────┐
│ 5. handler│ internal/handler/{module}.go —— 极薄委托，签名固定
└────┬─────┘
     │
     ▼
┌──────────┐
│ 6. 路由   │  router.go 注册表加一条 Bind 声明（RouteSpec 表）
└────┬─────┘
     │
     ▼
┌──────────┐
│ 7. 菜单   │  配置菜单与权限节点（或直接用代码生成器代劳）
└────┬─────┘
     │
     ▼
┌──────────┐
│ 8. 前端   │  ui/src/api + ui/src/views（详见第 9 章）
└──────────┘
```

第 2～6 步也可以交给 [第 10 章 代码生成器](/zh/generator/overview.html) 自动完成——生成器产物与手写规约完全一致，本章教你读懂并手工掌握每一步。

## 开发约定

| 约定 | 说明 | 示例 |
|------|------|------|
| 表名 | `gin_` 前缀 + 小写下划线 | `gin_example` |
| 字段名 | 小写下划线 | `create_user`、`sort` |
| 主键 | 统一 `id`，自增 | `id INT PRIMARY KEY AUTO_INCREMENT` |
| 四件套 | dto / repository / service / handler 同名成套 | `example.go` × 4 |
| 服务实例 | `type sXxx struct{}` + init 注册 | `var Example *sExample` |
| 权限码 | `sys:模块名:操作` | `sys:example:page` |
| 路由风格 | 动词命名、全小驼峰方法 | `GET /api/example/page` |
| 日志文案 | `模块名-动作描述` | `案例演示-查询分页记录` |

## 本章示例覆盖场景

`gin_example` 是代码生成器的参考模板，涵盖标准 CRUD 的全部典型场景：

- 分页列表（名称模糊、类型/状态等值过滤、字典显示名回填）
- 全量列表（limit 上限）
- 详情查询
- 新增 / 修改（含单图字段 temp 转正）
- 单列状态更新（手写逻辑）
- 删除 / 批量删除（软删除）
- Excel 导入（multipart 文件 + 逐行校验）
- Excel 导出（条件过滤 + 字典翻译 + 文件 URL 返回）
- 权限控制与操作日志（RouteSpec 声明驱动）

## 涉及文件

```text
internal/model/dto/example.go            # 契约层
internal/repository/example.go           # 数据访问层
internal/service/example.go              # 业务层（ModuleSpec 声明）
internal/handler/example.go              # 接口层
internal/router/router.go                # RouteSpec 注册表
ui/src/api/tool/example.ts               # 前端 API 模块
ui/src/views/tool/example/               # 前端页面
```