:::tip 本章概要
代码生成器 JSON 配置文件的格式说明，包括模块名称、字段属性等配置项的详细解释。
:::

# 配置文件详解

代码生成器支持通过 JSON 配置文件驱动生成。配置文件可通过 CLI `--output` 导出，也可手动编写，然后用 `--config` 加载生成。

## 导出配置

```bash
# 从数据库表解析并导出
python generator.py django_example --dry-run --output config.json

# 生成代码的同时保存配置
python generator.py django_example --output config.json
```

## 使用配置生成

```bash
python generator.py --config config.json
```

跳过表解析，直接从配置文件读取生成参数。适用于：
- 微调字段配置后重新生成
- 表结构已不存在但配置保留
- 跨项目复用配置

## 配置文件结构

```json
{
    "app_name": "example",
    "module_comment": "案例",
    "model_name": "example",
    "model_class_name": "Example",
    "route_prefix": "example",
    "business_description": "标识系统中的案例数据",
    "business_description_detail": "包含案例名称, 案例图片等属性",
    "permission_prefix": "sys:example",
    "primary_key": "id",
    "display_field": "name",
    "display_field_camel": "name",
    "table_name": "example",
    "table_prefix": ["django_"],
    "remove_prefix": true,
    "menu_group": "tool",
    "parent_menu_id": 322,
    "menu_sort": 5,
    "has_sort": true,
    "has_status": true,
    "has_unique_code": false,
    "has_export": false,
    "has_image_field": true,
    "has_rich_text_field": false,
    "fields": [...]
}
```

## 顶层配置项

### 基础信息

| 字段 | 类型 | 必填 | 说明 |
|:----|:----|:----|:----|
| `app_name` | str | 是 | 模块名（小写下划线），用于目录名和文件名 |
| `module_comment` | str | 是 | 模块中文名，用于注释和菜单名 |
| `model_name` | str | 否 | 模型名，默认同 `app_name` |
| `model_class_name` | str | 是 | 模型类名（帕斯卡命名） |
| `route_prefix` | str | 否 | URL 路由前缀，默认同 `app_name`（下划线转斜杠） |
| `business_description` | str | 否 | 业务简要描述 |
| `business_description_detail` | str | 否 | 业务详细描述 |

### 权限和标识

| 字段 | 类型 | 必填 | 说明 |
|:----|:----|:----|:----|
| `permission_prefix` | str | 否 | 权限前缀，默认 `sys:{app_name}` |
| `display_field` | str | 否 | 显示字段，默认 `name` |
| `display_field_camel` | str | 否 | 显示字段驼峰命名 |
| `primary_key` | str | 否 | 主键字段，默认 `id` |

### 表信息

| 字段 | 类型 | 必填 | 说明 |
|:----|:----|:----|:----|
| `table_name` | str | 否 | 数据库表名（去前缀） |
| `table_prefix` | list | 否 | 表前缀列表，如 `["django_"]` |
| `remove_prefix` | bool | 否 | 是否移除前缀，默认 `true` |

### 菜单配置

| 字段 | 类型 | 必填 | 说明 |
|:----|:----|:----|:----|
| `menu_group` | str | 否 | 菜单分组，默认 `tool` |
| `parent_menu_id` | int | 否 | 父级菜单 ID |
| `menu_sort` | int | 否 | 菜单排序，默认 `5` |

### 功能标识

| 字段 | 类型 | 默认值 | 说明 |
|:----|:----|:----|:----|
| `has_sort` | bool | `false` | 有排序字段 |
| `has_status` | bool | `false` | 有状态字段 |
| `has_unique_code` | bool | `false` | 有唯一编码字段 |
| `has_export` | bool | `false` | 有导出功能 |
| `has_image_field` | bool | `false` | 有图片字段 |
| `has_rich_text_field` | bool | `false` | 有富文本字段 |

### 字段列表

| 字段 | 类型 | 必填 | 说明 |
|:----|:----|:----|:----|
| `fields` | list | 是 | 字段配置列表 |

## 字段配置项

每个字段对象包含：

### 基础属性

| 字段 | 类型 | 必填 | 说明 |
|:----|:----|:----|:----|
| `name` | str | 是 | 字段名（snake_case） |
| `comment` | str | 否 | 字段注释 |
| `purpose` | str | 否 | 字段用途说明 |
| `type` | str | 是 | Django 字段类型 |
| `type_display` | str | 否 | 类型中文显示 |
| `max_length` | int | 否 | 最大长度 |

### 约束属性

| 字段 | 类型 | 默认值 | 说明 |
|:----|:----|:----|:----|
| `nullable` | bool | `false` | 是否可空 |
| `required` | bool | `true` | 是否必填（与 nullable 相反） |
| `is_unique` | bool | `false` | 是否唯一 |
| `db_index` | bool | `false` | 是否有索引 |
| `default` | any | `null` | 默认值 |

### 展示控制

| 字段 | 类型 | 默认值 | 说明 |
|:----|:----|:----|:----|
| `in_form` | bool | `true` | 出现在表单中 |
| `in_list` | bool | `true` | 出现在列表中 |
| `editable` | bool | `true` | 可编辑 |
| `filterable` | bool | `false` | 作为查询条件 |
| `filter_type` | str | `模糊查询` | 筛选类型（`精确匹配`/`模糊查询`） |
| `searchable` | bool | `false` | 可搜索 |

### 功能标识

| 字段 | 类型 | 默认值 | 说明 |
|:----|:----|:----|:----|
| `is_image` | bool | `false` | 图片字段 |
| `is_rich_text` | bool | `false` | 富文本字段 |

### 选项属性

| 字段 | 类型 | 说明 |
|:----|:----|:----|
| `choices` | list | `[[value, label], ...]` 元组列表 |
| `min_value` | int | 最小值 |
| `max_value` | int | 最大值 |

## 完整示例

```json
{
    "app_name": "example",
    "module_comment": "案例",
    "model_name": "example",
    "model_class_name": "Example",
    "route_prefix": "example",
    "business_description": "标识系统中的案例数据",
    "business_description_detail": "包含案例名称, 案例图片, 案例类型等属性",
    "permission_prefix": "sys:example",
    "primary_key": "id",
    "display_field": "name",
    "display_field_camel": "name",
    "table_name": "example",
    "table_prefix": ["django_"],
    "remove_prefix": true,
    "menu_group": "tool",
    "parent_menu_id": 322,
    "menu_sort": 5,
    "has_sort": true,
    "has_status": true,
    "has_unique_code": false,
    "has_export": false,
    "has_image_field": true,
    "has_rich_text_field": false,
    "fields": [
        {
            "name": "name",
            "comment": "案例名称",
            "purpose": "存储案例名称信息",
            "type": "CharField",
            "type_display": "字符串",
            "max_length": 100,
            "nullable": false,
            "required": true,
            "is_unique": false,
            "db_index": true,
            "default": null,
            "in_form": true,
            "in_list": true,
            "filterable": true,
            "filter_type": "模糊查询",
            "editable": true,
            "searchable": true,
            "is_image": false,
            "is_rich_text": false
        },
        {
            "name": "avatar",
            "comment": "案例图片",
            "purpose": "存储案例图片信息",
            "type": "CharField",
            "type_display": "字符串",
            "max_length": 255,
            "nullable": true,
            "required": false,
            "in_form": true,
            "in_list": true,
            "filterable": false,
            "is_image": true,
            "is_rich_text": false
        },
        {
            "name": "type",
            "comment": "案例类型：1-类型1 2-类型2 3-类型3 4-类型4",
            "type": "IntegerField",
            "type_display": "整数",
            "nullable": false,
            "required": true,
            "in_form": true,
            "in_list": true,
            "filterable": true,
            "filter_type": "精确匹配",
            "choices": [[1, "类型1"], [2, "类型2"], [3, "类型3"], [4, "类型4"]],
            "min_value": 1,
            "max_value": 4
        },
        {
            "name": "status",
            "comment": "案例状态：1-正常 2-禁用",
            "type": "IntegerField",
            "type_display": "整数",
            "nullable": false,
            "required": true,
            "in_form": true,
            "in_list": true,
            "filterable": true,
            "filter_type": "精确匹配",
            "choices": [[1, "正常"], [2, "禁用"]],
            "min_value": 1,
            "max_value": 2
        },
        {
            "name": "sort",
            "comment": "排序",
            "type": "IntegerField",
            "type_display": "整数",
            "nullable": false,
            "required": true,
            "in_form": true,
            "in_list": true,
            "filterable": false
        }
    ]
}
```

## 字段类型映射

`type` 必须是以下值之一：

| 合法值 | 对应 Django 模型字段 |
|:----|:----|
| `CharField` | CharField（需配合 `max_length`） |
| `TextField` | TextField |
| `IntegerField` | IntegerField |
| `DateTimeField` | DateTimeField |
| `DateField` | DateField |
| `FloatField` | FloatField |
| `DecimalField` | DecimalField |
| `BooleanField` | BooleanField |

`filter_type` 必须是以下值之一：`精确匹配` / `模糊查询`

## 常用微调场景

### 修改模块中文名

```json
{
    "module_comment": "培训记录"
}
```

### 隐藏字段（不出现在列表/表单）

```json
{
    "name": "internal_code",
    "in_form": false,
    "in_list": false
}
```

### 添加自定义字段

在 `fields` 数组中追加新的字段配置。

### 修改筛选类型

```json
{
    "name": "name",
    "filterable": true,
    "filter_type": "精确匹配"
}
```

### 添加选项

```json
{
    "name": "level",
    "choices": [[1, "初级"], [2, "中级"], [3, "高级"]],
    "min_value": 1,
    "max_value": 3
}
```

## 总结

配置文件为 JSON 格式，包含模块名称、表名、字段属性等信息。支持字段级别的精细配置（是否可搜索、是否在列表显示等），可通过 CLI 导出或手动编写。