hotime/docs/CodeGen_使用说明.md

# HoTime 代码生成器使用说明

`code` 包提供了 HoTime 框架的自动代码生成功能，能够根据数据库表结构自动生成 CRUD 接口代码和配置文件。

## 目录

- [功能概述](#功能概述)
- [配置说明](#配置说明)
- [使用方法](#使用方法)
- [生成规则](#生成规则)
- [自定义规则](#自定义规则)
- [生成的代码结构](#生成的代码结构)

---

## 功能概述

代码生成器可以：

1. **自动读取数据库表结构** - 支持 MySQL 和 SQLite
2. **生成 CRUD 接口** - 增删改查、搜索、分页
3. **生成配置文件** - 表字段配置、菜单配置、权限配置
4. **智能字段识别** - 根据字段名自动识别类型和权限
5. **支持表关联** - 自动识别外键关系

---

## 配置说明

在 `config.json` 中配置代码生成：

```json
{
    "codeConfig": [
        {
            "table": "admin",
            "config": "config/admin.json",
            "configDB": "config/adminDB.json",
            "rule": "config/rule.json",
            "name": "",
            "mode": 0
        }
    ]
}
```

### 配置项说明

| 配置项 | 必须 | 说明 |
|--------|------|------|
| `table` | ✅ | 用户表名，用于权限控制的基准表 |
| `config` | ✅ | 接口描述配置文件路径 |
| `configDB` | ❌ | 数据库结构配置输出路径，有则每次自动生成 |
| `rule` | ❌ | 字段规则配置文件，无则使用默认规则 |
| `name` | ❌ | 生成代码的包名和目录名，空则使用内嵌模式 |
| `mode` | ❌ | 0=内嵌代码模式，1=生成代码模式 |

### 运行模式

- **mode=0（内嵌模式）**：不生成独立代码文件，使用框架内置的通用控制器
- **mode=1（生成模式）**：为每张表生成独立的 Go 控制器文件

---

## 使用方法

### 1. 基础配置

```json
{
    "mode": 2,
    "codeConfig": [
        {
            "table": "admin",
            "config": "config/admin.json",
            "rule": "config/rule.json",
            "mode": 0
        }
    ]
}
```

### 2. 启动应用

```go
package main

import (
    . "code.hoteas.com/golang/hotime"
    . "code.hoteas.com/golang/hotime/common"
)

func main() {
    app := Init("config/config.json")
    
    // 代码生成器在 Init 时自动执行
    // 会读取数据库结构并生成配置
    
    app.Run(Router{
        // 路由配置
    })
}
```

### 3. 开发模式

在 `config.json` 中设置 `"mode": 2`（开发模式）时：

- 自动读取数据库表结构
- 自动生成/更新配置文件
- 自动生成代码（如果 codeConfig.mode=1）

---

## 生成规则

### 默认字段规则

代码生成器内置了一套默认的字段识别规则：

| 字段名 | 列表显示 | 新增 | 编辑 | 详情 | 类型 |
|--------|----------|------|------|------|------|
| `id` | ✅ | ❌ | ❌ | ✅ | number |
| `name` | ✅ | ✅ | ✅ | ✅ | text |
| `status` | ✅ | ✅ | ✅ | ✅ | select |
| `create_time` | ❌ | ❌ | ❌ | ✅ | time |
| `modify_time` | ✅ | ❌ | ❌ | ✅ | time |
| `password` | ❌ | ✅ | ✅ | ❌ | password |
| `image/img/avatar` | ❌ | ✅ | ✅ | ✅ | image |
| `file` | ❌ | ✅ | ✅ | ✅ | file |
| `content/info` | ❌ | ✅ | ✅ | ✅ | textArea |
| `parent_id` | ✅ | ✅ | ✅ | ✅ | number |
| `parent_ids/index` | ❌ | ❌ | ❌ | ❌ | index |
| `delete` | ❌ | ❌ | ❌ | ❌ | - |

### 数据类型映射

数据库字段类型自动映射：

| 数据库类型 | 生成类型 |
|------------|----------|
| `int`, `integer`, `float`, `double`, `decimal` | number |
| `char`, `varchar`, `text`, `blob` | text |
| `date`, `datetime`, `time`, `timestamp`, `year` | time |

### 字段备注解析

支持从数据库字段备注中提取信息：

```sql
-- 字段备注格式: 标签名:选项1-名称1,选项2-名称2 {提示信息}
-- 例如:
status TINYINT COMMENT '状态:0-禁用,1-启用 {用户账号状态}'
```

生成的配置：

```json
{
    "name": "status",
    "label": "状态",
    "type": "select",
    "ps": "用户账号状态",
    "options": [
        {"name": "禁用", "value": "0"},
        {"name": "启用", "value": "1"}
    ]
}
```

---

## 自定义规则

### rule.json 配置

创建 `config/rule.json` 自定义字段规则：

```json
[
    {
        "name": "id",
        "list": true,
        "add": false,
        "edit": false,
        "info": true,
        "must": false,
        "strict": true,
        "type": ""
    },
    {
        "name": "status",
        "list": true,
        "add": true,
        "edit": true,
        "info": true,
        "must": false,
        "strict": false,
        "type": "select"
    },
    {
        "name": "user.special_field",
        "list": true,
        "add": true,
        "edit": true,
        "info": true,
        "type": "text",
        "strict": true
    }
]
```

### 规则字段说明

| 字段 | 说明 |
|------|------|
| `name` | 字段名，支持 `表名.字段名` 格式精确匹配 |
| `list` | 是否在列表中显示 |
| `add` | 是否在新增表单中显示 |
| `edit` | 是否在编辑表单中显示 |
| `info` | 是否在详情中显示 |
| `must` | 是否必填 |
| `strict` | 是否严格匹配字段名（false 则模糊匹配） |
| `type` | 字段类型（覆盖自动识别） |

### 字段类型

| 类型 | 说明 |
|------|------|
| `text` | 普通文本输入 |
| `textArea` | 多行文本 |
| `number` | 数字输入 |
| `select` | 下拉选择 |
| `time` | 时间选择器 |
| `unixTime` | Unix 时间戳 |
| `image` | 图片上传 |
| `file` | 文件上传 |
| `password` | 密码输入 |
| `money` | 金额（带格式化） |
| `index` | 索引字段（不显示） |
| `tree` | 树形选择 |
| `form` | 表单配置 |
| `auth` | 权限配置 |

---

## 生成的代码结构

### 内嵌模式 (mode=0)

不生成代码文件，使用框架内置控制器，只生成配置文件：

```
config/
├── admin.json      # 接口配置
├── adminDB.json    # 数据库结构配置（可选）
└── rule.json       # 字段规则
```

### 生成模式 (mode=1)

生成独立的控制器代码：

```
admin/              # 生成的包目录
├── init.go         # 包初始化和路由注册
├── user.go         # user 表控制器
├── role.go         # role 表控制器
└── ...             # 其他表控制器
```

### 生成的控制器结构

```go
package admin

var userCtr = Ctr{
    "info": func(that *Context) {
        // 查询单条记录
    },
    "add": func(that *Context) {
        // 新增记录
    },
    "update": func(that *Context) {
        // 更新记录
    },
    "remove": func(that *Context) {
        // 删除记录
    },
    "search": func(that *Context) {
        // 搜索列表（分页）
    },
}
```

---

## 配置文件结构

### admin.json 示例

```json
{
    "name": "admin",
    "label": "管理平台",
    "menus": [
        {
            "label": "系统管理",
            "name": "sys",
            "icon": "Setting",
            "menus": [
                {
                    "label": "用户管理",
                    "table": "user",
                    "auth": ["show", "add", "delete", "edit", "info", "download"]
                },
                {
                    "label": "角色管理",
                    "table": "role",
                    "auth": ["show", "add", "delete", "edit", "info"]
                }
            ]
        }
    ],
    "tables": {
        "user": {
            "label": "用户",
            "table": "user",
            "auth": ["show", "add", "delete", "edit", "info", "download"],
            "columns": [
                {"name": "id", "type": "number", "label": "ID"},
                {"name": "name", "type": "text", "label": "用户名"},
                {"name": "status", "type": "select", "label": "状态", 
                 "options": [{"name": "禁用", "value": "0"}, {"name": "启用", "value": "1"}]}
            ],
            "search": [
                {"type": "search", "name": "keyword", "label": "请输入关键词"},
                {"type": "search", "name": "daterange", "label": "时间段"}
            ]
        }
    }
}
```

---

## 外键关联

### 自动识别

代码生成器会自动识别 `_id` 结尾的字段作为外键：

```sql
-- user 表
CREATE TABLE user (
    id INT PRIMARY KEY,
    name VARCHAR(50),
    role_id INT,        -- 自动关联 role 表
    org_id INT          -- 自动关联 org 表
);
```

生成的配置会包含 `link` 和 `value` 字段：

```json
{
    "name": "role_id",
    "type": "number",
    "label": "角色",
    "link": "role",
    "value": "name"
}
```

### 树形结构

`parent_id` 字段会被识别为树形结构的父级关联：

```json
{
    "name": "parent_id",
    "type": "number",
    "label": "上级",
    "link": "org",
    "value": "name"
}
```

---

## 权限控制

### 数据权限

配置 `flow` 实现数据权限控制：

```json
{
    "flow": {
        "order": {
            "table": "order",
            "stop": false,
            "sql": {
                "user_id": "id"
            }
        }
    }
}
```

- `stop`: 是否禁止修改该表
- `sql`: 数据过滤条件，`user_id = 当前用户.id`

### 操作权限

每张表可配置的权限：

| 权限 | 说明 |
|------|------|
| `show` | 查看列表 |
| `add` | 新增 |
| `edit` | 编辑 |
| `delete` | 删除 |
| `info` | 查看详情 |
| `download` | 下载导出 |

---

## 最佳实践

### 1. 开发流程

1. 设置 `config.json` 中 `mode: 2`（开发模式）
2. 设计数据库表结构，添加字段备注
3. 启动应用，自动生成配置
4. 检查生成的配置文件，按需调整
5. 生产环境改为 `mode: 0`

### 2. 字段命名规范

```sql
-- 推荐的命名方式
id              -- 主键
name            -- 名称
status          -- 状态（自动识别为 select）
create_time     -- 创建时间
modify_time     -- 修改时间
xxx_id          -- 外键关联
parent_id       -- 树形结构父级
avatar          -- 头像（自动识别为 image）
content         -- 内容（自动识别为 textArea）
```

### 3. 自定义扩展

如果默认规则不满足需求，可以：

1. 修改 `rule.json` 添加自定义规则
2. 使用 `mode=1` 生成代码后手动修改
3. 在生成的配置文件中直接调整字段属性

---

## 相关文档

- [快速上手指南](QUICKSTART.md)
- [HoTimeDB 使用说明](HoTimeDB_使用说明.md)
- [Common 工具类使用说明](Common_工具类使用说明.md)