签入版本

EasyGoAdmin_Gin_NaiveVue/zh/guide/overview.md

@@ -1,88 +1,89 @@
 # 3.1 概述与目标
 
 :::tip 概述
-本章以项目内置的 **example（案例演示）** 模块为例，从数据库建表到前端页面联调，手把手演示开发全流程。学完本章后，您将掌握新增业务模块的标准步骤。
+本章以项目内置的 **example（案例演示，`gin_example`）** 模块为例，从数据库建表到前端页面联调，完整演示开发全流程。学完本章后，你将掌握新增业务模块的标准步骤。
 :::
 
 ## 开发流程总览
 
 ```text
 ┌──────────┐
-│ 1. 建表   │  创建数据库表（含公共字段）
+│ 1. 建表   │  创建 gin_ 前缀表（含公共审计字段）
 └────┬─────┘
      │
      ▼
 ┌──────────┐
-│ 2. Model  │  创建数据模型（继承 BaseModel）
+│ 2. dto   │  internal/model/dto/{module}.go —— 请求/响应契约 + 校验标签
 └────┬─────┘
      │
      ▼
 ┌──────────┐
-│ 3. Validate│ 创建验证器 + Logic 配置 validateClass
+│ 3. repo  │  internal/repository/{module}.go —— XxxRepo + Base，统一 Ctx(ctx)
 └────┬─────┘
      │
      ▼
 ┌──────────┐
-│ 4. Logic  │  创建逻辑层（配置属性 + 钩子）
+│ 4. service│ internal/service/{module}.go —— sXxx + ModuleSpec 声明 + 手写逻辑
 └────┬─────┘
      │
      ▼
 ┌──────────┐
-│ 5. Controller│ 创建控制器（注解 + 异常处理）
+│ 5. handler│ internal/handler/{module}.go —— 极薄委托，签名固定
 └────┬─────┘
      │
      ▼
 ┌──────────┐
-│ 6. Route  │  注册路由
+│ 6. 路由   │  router.go 注册表加一条 Bind 声明（RouteSpec 表）
 └────┬─────┘
      │
      ▼
 ┌──────────┐
-│ 7. Menu   │  配置菜单权限（可选）
+│ 7. 菜单   │  配置菜单与权限节点（或直接用代码生成器代劳）
 └────┬─────┘
      │
      ▼
 ┌──────────┐
-│ 8. Frontend│ 前端 API + 页面（[详见第 9 章](/zh/frontend/overview.html)）
+│ 8. 前端   │  ui/src/api + ui/src/views（详见第 9 章）
 └──────────┘
 ```
 
+第 2～6 步也可以交给 [第 10 章 代码生成器](/zh/generator/overview.html) 自动完成——生成器产物与手写规约完全一致，本章教你读懂并手工掌握每一步。
+
 ## 开发约定
 
 | 约定 | 说明 | 示例 |
 |------|------|------|
-| 表名 | `think_` 前缀 + 小写下划线 | `think_example` |
-| 字段名 | 小写下划线 | `create_time`、`user_id` |
-| 主键 | 统一使用 `id`，INT 自增 | `id INT PRIMARY KEY AUTO_INCREMENT` |
-| Model | 继承 `BaseModel`，类名与表名对应 | `class Example extends BaseModel` |
-| Logic | 继承 `BaseLogic` 或 `BaseTenantLogic` | `class ExampleLogic extends BaseLogic` |
-| Controller | 继承 `BaseController` | `class ExampleController extends BaseController` |
-| 权限码 | `sys:模块名:操作` | `sys:example:add` |
-| 路由 | RESTful 风格 | `GET /api/example/page` |
+| 表名 | `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` |
+| 日志文案 | `模块名-动作描述` | `案例演示-查询分页记录` |
 
-## 本章示例
+## 本章示例覆盖场景
 
-本章以项目内置的 **example（案例演示）** 模块为例，完整演示从建表到联调的全过程。该模块是代码生成器的参考模板，涵盖了标准 CRUD 的所有典型场景：
+`gin_example` 是代码生成器的参考模板，涵盖标准 CRUD 的全部典型场景：
 
-- 分页列表（支持名称模糊搜索、类型和状态精确过滤）
-- 全量列表
+- 分页列表（名称模糊、类型/状态等值过滤、字典显示名回填）
+- 全量列表（limit 上限）
 - 详情查询
-- 新增（含头像上传）
-- 修改
-- 删除 / 批量删除
-- Excel 导入导出
-- 权限控制（#[Permission] 注解）
-- 操作日志（#[Log] 注解）
-- 枚举显示名翻译（type / status 字典映射）
+- 新增 / 修改（含单图字段 temp 转正）
+- 单列状态更新（手写逻辑）
+- 删除 / 批量删除（软删除）
+- Excel 导入（multipart 文件 + 逐行校验）
+- Excel 导出（条件过滤 + 字典翻译 + 文件 URL 返回）
+- 权限控制与操作日志（RouteSpec 声明驱动）
 
 ## 涉及文件
 
 ```text
-app/model/Example.php                # 数据模型
-app/validate/ExampleValidate.php     # 验证器
-app/logic/ExampleLogic.php           # 业务逻辑
-app/controller/ExampleController.php # 控制器
-route/app.php                        # 路由（第371行）
-ui/src/api/tool/example.ts           # 前端 API 模块
-ui/src/views/tool/example/           # 前端页面
-```
+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/               # 前端页面
+```