# 1.4 新手入门指南

:::tip 概述
本节面向第一次接触本项目的开发者，给出一条最短路径：跑起来 → 看懂一个请求 → 改一个字段 → 开发一个新模块。全程约 1 小时。
:::

## 学习路径总览

```mermaid
graph TD
    A[克隆代码] --> B[初始化数据库]
    B --> C[启动后端 :8000]
    C --> D[启动前端 :9100]
    D --> E[登录 admin/123456]
    E --> F[读懂一个请求的完整链路]
    F --> G[照着 example 模块仿写]
    G --> H[用生成器生成新模块]
    H --> I[阅读第 3 章模块开发实战]

    style A fill:#e8f5e9
    style E fill:#e8f5e9
    style I fill:#fff3e0
```

## 第一步：跑起来

```sh
# 1. 导入数据库（MySQL）
#    库名：easygoadmin.goframe.elevue（注意库名含点）
mysql -uroot -p easygoadmin.goframe.elevue < document/mysql/easygoadmin.goframe.elevue.sql

# 2. 检查 manifest/config/config.yaml（数据库/Redis 连接信息）

# 3. 启动后端
go build -o bin/admin-server.exe main.go && ./bin/admin-server.exe

# 4. 启动前端（新终端）
cd ui && pnpm install && pnpm dev
```

访问前端页面，使用 **admin / 123456** 登录（超管，角色 `ROLE_SUPER_ADMIN`）。

## 第二步：读懂一个请求的完整链路

以「用户管理 → 列表页」为例，一个 `GET /api/user/page` 请求经过：

```text
前端 useHttp.get('/user/page')
  → axios 拦截器（带 Authorization: Bearer xxx）
    → 中间件链：CORS → Response → RateLimit → Demo → JWT → Tenant → OperationLog
      → Bind 包装层：读 gmeta 元数据 → HasPerm("sys:user:page") 权限校验
        → 参数解析（gvalid 校验）→ CUser.Page
          → service.User().Page
            → logic.sUser.Page → userSpec.Page（ModuleSpec 流水线）
              → dao.User.Ctx(ctx)（自动注入 del_flag=0 + tenant_id）
                → 数据库
  ← 统一信封 {"code":0,"ok":true,"msg":"操作成功","data":{records:[…],total:…}}
  ← OperationLog 中间件异步落库（GET 查询默认记录）
```

建议打断点或加日志逐层跟踪一次，比读十遍文档更有效。

## 第三步：改一个字段感受全流程

以「职级管理」为例，给 `goframe_level` 表加一个 `remark` 备注字段：

```sql
ALTER TABLE goframe_level ADD COLUMN remark varchar(255) DEFAULT '' COMMENT '备注';
```

然后：

```sh
# 刷新 dao（entity/do 同步更新）
gf gen dao -c hack/config.yaml
```

手工补齐四处：`api/v1/level.go` 的 Req/Res 结构体加 `Remark` 字段 → `logic/level.go` 的 ToData 加映射 → 前端 `querySchemas.ts`/`edit.vue`/`columns.ts` 加展示项 → `go build ./...` 重启。

这个过程就是日常开发的最小闭环。熟练后大部分此类变更可以用生成器的覆盖模式批量完成。

## 第四步：看懂 example 模块

`internal/logic/example.go` 是官方完整样板，演示了基座的全部常用声明：

+ 筛选（LikeFields/EqFields）
+ 字典文本（SerializeMaps → {field}Text）
+ 状态切换（Status 方法）
+ Excel 导入导出（Import/Export + ChunkQuery）
+ 前端五件套（`ui/src/views/tool/example/`：index/edit/detail/columns/querySchemas）

第 3 章模块开发实战全程以它为参照。

## 第五步：跑一遍生成器

用库中真实存在的 `goframe_example` 表练手（命令可直接执行）：

```sh
# 预览（不落盘，查看将产出的文件与内容）
go run ./cmd/generator -tables "goframe_example|案例演示表" -preview

# 生成（example 已完整实现——将演示幂等保护：文件全跳过、菜单/字典/路由查重命中）
go run ./cmd/generator -tables "goframe_example|案例演示表"

go build ./...   # 编译并重启
```

开发**新模块**时同样命令把表名换成你的表（如 `"goframe_xxx|中文名"`），生成后在「角色管理」为角色勾选新模块的权限节点。登录后在「系统管理 → 代码生成」页面也能操作（Web 界面）。完整实战见 [10.8 实战案例](./generator/demo)。

## 新手常见误区

:::warning 注意
1. **不要运行 `gf gen service`**——service 接口文件是手工重组维护的，整体运行会覆盖。
2. **不要绕过 dao 直连 `g.DB()`**——会绕过全局钩子（软删/租户/审计全部失效）。
3. **不要手写 del_flag/tenant_id 条件**——`dao.{X}.Ctx(ctx)` 已自动注入。
4. **不要在事务内做 HTTP/文件 IO**——bcrypt 等 CPU 操作也要在事务外预计算。
5. **前端登录读 `data.access_token`**（下划线命名），这是 OAuth2 惯例例外，勿改驼峰。
:::

## 常用命令速查

项目根目录执行（Windows 环境无 make，可直接用等价 go/gf 命令；Makefile 提供 run/build/test/vet/fmt/gen/clean 目标供类 Unix 环境使用）：

```sh
# 编译与运行
go build ./...                                  # 全量编译
go build -o bin/admin-server.exe main.go        # 编译产物
./bin/admin-server.exe                          # 运行（:8000）
go run main.go                                  # 开发直接运行

# 质量门禁
go test ./...                                   # 测试（sqlite 集成 + hooks MySQL 集成）
go vet ./...                                    # 静态检查
gofmt -l .                                      # 格式检查（无输出=通过）

# 表结构变更后刷新 dao（service 手维护，勿运行 gf gen service）
gf gen dao -c hack/config.yaml

# 代码生成（文件+菜单+字典+路由，幂等）
go run ./cmd/generator -tables "goframe_example|案例演示表"              # 一键生成
go run ./cmd/generator -tables "goframe_example|案例演示表" -preview     # 仅预览
go run ./cmd/generator -tables "goframe_example|案例演示表" -batch       # 批量统计

# 整库迁移（五方言互迁，含结构+注释+索引+数据+序列）
go run ./cmd/migrator -src-type=mysql -src-host=127.0.0.1 -src-hostport=3306 \
  -src-database=easygoadmin.goframe.elevue -src-username=root -src-password=root \
  -dst-type=pgsql -dst-host=127.0.0.1 -dst-hostport=5432 \
  -dst-database=easygoadmin.goframe.elevue -dst-username=postgres -dst-password=123456 \
  -drop-target-first
```

```sh
# 前端（ui/ 目录）
pnpm install          # 安装依赖
pnpm dev              # 开发服务器
pnpm build            # 生产构建
pnpm type:check       # vue-tsc 类型检查
pnpm lint:eslint      # ESLint 修复

# Windows 重启（端口 8000）
netstat -ano | findstr ":8000" | findstr LISTENING
taskkill /F /PID <pid>
```

## 下一步阅读

+ 想快速搭环境：第 2 章「快速入门」
+ 想开发业务模块：第 3 章「模块开发实战」
+ 想理解设计原理：第 4 章「架构设计」
+ 想偷懒用生成器：第 10 章「代码生成器」