# 10.3 Web 管理界面

:::tip 概述
代码生成器提供 Web 管理界面，通过可视化操作完成代码生成，无需命令行。支持表选择、配置生成选项、预览代码和一键生成。界面位于「开发工具 → 代码生成」菜单。
:::

## 操作流程

```text
1. 登录管理后台
2. 进入「开发工具 → 代码生成」菜单
3. 查看可生成的数据库表列表（自动读取当前数据库的所有表）
4. 选择目标表，点击「配置」
5. 配置生成选项（模板类型、生成菜单、覆盖文件等）
6. 点击「预览」查看生成代码（不写入文件，可安全查看）
7. 确认无误后点击「生成」创建文件
8. 检查 routes/api.php 中的路由（通常已自动插入）
9. 在菜单管理中配置菜单权限
10. 重新登录或刷新前端动态菜单，新模块即可使用
```

## 界面说明

### 表列表页

进入「开发工具 → 代码生成」后，首先进入表列表页：

| 列 | 说明 |
|----|------|
| 表名 | 数据库表名（不含前缀） |
| 表注释 | 表的 COMMENT 字段（显示为中文说明） |
| 引擎 | 存储引擎（InnoDB / MyISAM） |
| 行数 | 表中的数据行数 |
| 操作 | 配置 / 预览 / 生成 |

### 配置弹窗

点击「配置」按钮后，可设置以下生成选项：

| 配置项 | 参数名 | 说明 | 示例 |
|--------|--------|------|------|
| 表名 | `tableNames` | 选择要生成的表（自动带入，格式 `"表名\|注释"`） | `["laravel_example\|案例演示"]` |
| 模板类型 | `templateType` | `ui` 普通列表 或 `ui2` 树形（含 parent_id 时自动切换） | `ui` |
| 生成菜单 | `generateMenu` | 是否自动创建菜单和权限节点 | `true` |
| 覆盖文件 | `overwrite` | 是否覆盖已存在的文件 | `false` |

### 预览功能

点击「预览」按钮，可查看即将生成的所有文件代码：

- 预览模式**不会写入文件**，可安全查看
- 支持切换查看不同文件（Controller / Service / Model / Request / API / Vue / columns.ts / querySchemas.ts）
- 确认无误后再点击「生成」实际创建文件

### 批量生成

在表列表页勾选多张表，点击「批量生成」：

- 批量生成会为每张表分别生成完整的 CRUD 模块（含文件、菜单、字典、路由）
- 单张表失败不影响其它表继续生成
- 生成结果会显示每张表的成功/失败状态和文件统计

## 配置选项详解

### 模块名（自动推导）

模块名由表名去掉前缀自动推导，影响以下内容：

| 影响范围 | 规则 | 示例（模块名=example） |
|----------|------|----------------------|
| 后端路由前缀 | `/api/{模块名}/` | `/api/example/page` |
| 前端 API 文件 | `ui/src/api/{app}/{模块名}.ts` | `ui/src/api/tool/example.ts` |
| 前端视图目录 | `ui/src/views/{app}/{模块名}/` | `ui/src/views/tool/example/` |
| 权限码前缀 | `sys:{模块名}:` | `sys:example:page` |
| 字典编码前缀 | `{模块名}_{字段名}` | `example_status` |

### 树形结构（自动检测）

当表中包含 `parent_id` 或 `pid` 字段时，引擎自动切换为 `ui2/` 树形模板：

- 前端使用 Tree + Table 左右布局
- 支持拖拽排序、展开/折叠
- 自动处理父子关系的新增和编辑
- 树形模板不生成 `columns.ts` 和 `querySchemas.ts`
- 注册路由时不含 `page` 路由

### 导入导出（默认生成）

默认生成 `import()` 和 `export()` 方法：

- 后端基于 `ExcelService` 实现分批导入导出
- 枚举字段自动做正向/反向映射（值 ↔ 文本，反向映射用 `DictCacheService::getValue()`）
- 前端生成导入/导出按钮

### 字典自动创建

带选项（choices）的字段会自动创建字典：

- 在 `laravel_dict` 和 `laravel_dict_item` 表中创建记录（`create_user = 'system'`）
- Service 中自动生成 `$serializeMaps` 映射
- 查询时自动补 `{字段名}Text` 翻译字段（`HasSerializeMaps` Trait）
- 幂等：字典编码已存在则跳过

### 路由自动注册

在 `routes/api.php` 中自动插入 CRUD 路由组（`GeneratorService::registerRoute()`）：

- 包含 list / detail / add / update / delete / batchDelete / import / export
- 非树形结构额外包含 page 路由
- 插入位置为文件末尾中间件组闭合 `});` 之前，分组注释取表注释（如 `// --- 案例演示 ---`），表注释为空时回退模块名
- 幂等：同模块路由已存在则跳过（以路由路径判断）

## API 接口

| 方法 | 路径 | 权限码 | 说明 |
|------|------|--------|------|
| GET | `/api/generator/page` | sys:generator:page | 获取可生成的表列表（分页） |
| GET | `/api/generator/preview` | sys:generator:generate | 预览生成代码（不写入文件） |
| POST | `/api/generator/generate` | sys:generator:generate | 一键生成（写入文件） |
| POST | `/api/generator/batchGenerate` | sys:generator:generate | 批量生成（多表） |

:::tip 演示模式
预览接口（preview）标注了 `#[DemoAllow]`，演示环境下也可使用（且本身是 GET 请求）。生成接口（generate / batchGenerate）为写操作，演示环境下会被 `DemoMiddleware` 拦截（`config('app.demo_mode')` 开启时）。
:::

### 请求参数

```json
{
  "tableNames": ["laravel_example|案例演示"],
  "templateType": "ui",
  "generateMenu": true,
  "overwrite": false
}
```

| 参数 | 类型 | 必填 | 说明 | 默认值 |
|------|------|------|------|--------|
| `tableNames` | string[] | 是 | 表名数组，格式为 `"表名\|注释"` | - |
| `templateType` | string | 否 | 模板类型：`ui`（普通列表）或 `ui2`（树形） | `ui` |
| `generateMenu` | bool | 否 | 是否自动创建菜单和权限节点 | `true` |
| `overwrite` | bool | 否 | 是否覆盖已存在的文件 | `false` |

:::info 树形结构自动切换
当表中包含 `parent_id` 或 `pid` 字段时，即使传入 `templateType: "ui"`，也会自动切换为 `ui2` 树形模板。
:::

### 请求示例

```bash
# -----------------------------------------------------------------------------
# 预览生成代码（不写入文件）
# -----------------------------------------------------------------------------
# GET /api/generator/preview
# Content-Type: application/json
# Authorization: Bearer <token>
curl -X GET http://localhost:8000/api/generator/preview \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "tableNames": ["laravel_example|案例演示"],
    "templateType": "ui"
  }'
```

### 响应示例

```json
{
  "code": 0,
  "ok": true,
  "msg": "操作成功",
  "data": {
    "files": [
      {
        "path": "app/Http/Controllers/Api/ExampleController.php",
        "content": "<?php\nnamespace App\\Http\\Controllers\\Api;\n// ...",
        "exists": false,
        "type": "backend"
      },
      {
        "path": "app/Services/ExampleService.php",
        "content": "<?php\nnamespace App\\Services;\n// ...",
        "exists": false,
        "type": "backend"
      },
      {
        "path": "ui/src/views/tool/example/columns.ts",
        "content": "import { h } from 'vue';\n// ...",
        "exists": false,
        "type": "frontend"
      }
    ],
    "vars": {
      "app_name": "tool",
      "module_name": "example",
      "module_comment": "案例",
      "model_class_name": "Example",
      "template_type": "ui",
      "is_tree": false
    }
  }
}
```

:::tip 响应结构说明
- `files`：待生成文件数组，每项含 `path`（相对路径）、`content`（渲染后内容）、`exists`（是否已存在）、`type`（backend/frontend）
- `vars`：模板变量，供调试和导出配置使用
- 一键生成接口的 `msg` 为多行统计消息：📄 文件（生成/跳过/失败数量）、📋 菜单、📖 字典、🔀 路由
:::

## 生成后操作清单

```bash
# -----------------------------------------------------------------------------
# 第 1 步：检查生成的文件
# -----------------------------------------------------------------------------
ls app/Http/Controllers/Api/Example*      # 控制器
ls app/Services/Example*                  # 业务服务
ls app/Models/Example*                    # 数据模型
ls app/Http/Requests/Example*             # FormRequest 验证器
ls ui/src/api/tool/example*               # 前端 API
ls ui/src/views/tool/example/             # 前端页面（含 index.vue / edit.vue / detail.vue / columns.ts / querySchemas.ts）

# -----------------------------------------------------------------------------
# 第 2 步：检查 routes/api.php 中的路由（通常已自动插入，带 // --- 案例演示 --- 表注释）
# -----------------------------------------------------------------------------
grep -n "// --- 案例演示 ---" routes/api.php

# -----------------------------------------------------------------------------
# 第 3 步：在菜单管理中配置菜单权限
# -----------------------------------------------------------------------------
# 菜单已自动创建：案例（路径：/tool/example，组件：tool/example/index）
# 权限节点已自动创建：sys:example:page / list / detail / add / update / delete / batchDelete / import / export
# 只需为角色勾选相应权限

# -----------------------------------------------------------------------------
# 第 4 步：根据业务需求调整 Service 属性配置
# -----------------------------------------------------------------------------
# 可调整：fileFields（文件字段）、serializeMaps（字典映射）、
#         pageLikeFields（模糊查询）、uniqueFields（唯一校验）等
```

:::warning 生产环境注意
- 路由写入后，若执行过 `php artisan route:cache`，需重新缓存
- 新菜单需重新登录（刷新 Redis 中的 JWT 权限缓存）或刷新动态菜单后生效
:::

## 与 CLI 命令对比

| 特性 | Web 界面 | CLI 命令 |
|------|----------|----------|
| 使用方式 | 浏览器可视化操作 | 命令行 |
| 适用场景 | 日常开发、单表生成 | 批量生成、CI/CD 集成 |
| 预览功能 | ✅ 支持（不写入文件） | ✅ 支持（--dry-run） |
| 批量生成 | ✅ 支持（多选表） | ✅ 支持（--batch） |
| 配置选项 | 更多（树形、导入导出等） | 基础配置 |
| 权限限制 | 受权限和演示模式限制 | 不受限制 |
| 导出配置 | ❌ 不支持 | ✅ 支持（--output） |

## 相关文档

- [10.1 概述与架构](/zh/generator/overview.html)
- [10.2 CLI 命令行使用](/zh/generator/cli.html)
- [10.4 表结构解析引擎](/zh/generator/parser.html)
- [10.8 实战案例](/zh/generator/demo.html)