# 平台参数管理 — 功能上线说明

## 概述

绘画/视频平台的模型参数配置已从**前端代码硬编码**迁移至**管理后台数据库管理**。新增模型或修改参数无需前端发版，在管理后台配置即可生效。

## 变更内容

### 1. 新增数据库表

`suanli.model_param_configs` — 模型参数配置表

| 字段 | 类型 | 说明 |
|------|------|------|
| `model_id` | CHAR(36) | 关联模型 UUID |
| `platform_id` | CHAR(36) | 关联平台 UUID（如 ai_painting_talk / ai_video_talk） |
| `input_type` | VARCHAR(32) | text（文生图）/ image（图片编辑） |
| `max_images` | INT | 最大上传图片数，0=不支持 |
| `prompt_placeholder` | VARCHAR(500) | 提示词输入框占位文本 |
| `params` | JSON | 参数列表，每项含 name/ui/label/default/options 等 |

唯一约束：`(model_id, platform_id)` — 同一模型在同一平台下仅一份配置。

### 2. 新增后端接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/suanli/v1/admin/model-params` | 列表（分页，支持 `?platform_id=` 筛选） |
| GET | `/suanli/v1/admin/model-params/:id` | 详情 |
| POST | `/suanli/v1/admin/model-params` | 新建 |
| PUT | `/suanli/v1/admin/model-params/:id` | 更新 |
| DELETE | `/suanli/v1/admin/model-params/:id` | 删除 |
| GET | `/suanli/v1/models/:modelId/config` | **公共 API**，供客户端拉取参数 schema |

公共 API 响应示例（含各 ui 类型的完整结构）：

```json
{
  "code": 0,
  "data": {
    "inputType": "text",
    "maxImages": 0,
    "promptPlaceholder": "描述你想生成的画面。",
    "params": [
      { "name": "prompt", "ui": "textarea", "label": "提示词", "required": true, "default": "" },
      { "name": "aspectRatio", "ui": "proportion", "label": "比例", "default": "1:1", "options": ["1:1","16:9","9:16","custom"] },
      { "name": "resolution", "ui": "resolution", "label": "分辨率", "default": "2k", "options": ["1k","2k","4k"] },
      {
        "name": "size", "ui": "dimension", "label": "尺寸", "default": "1024*1024",
        "dimension": {
          "separator": "*",
          "width": { "min": 512, "max": 2048 },
          "height": { "min": 512, "max": 2048 }
        }
      },
      { "name": "quality", "ui": "select", "label": "画质", "default": "medium", "options": ["low","medium","high"] },
      { "name": "imageNum", "ui": "quantity", "label": "生成张数", "default": 1, "options": [1, 2, 3, 4, 5, 6] },
      { "name": "imageUrls", "ui": "imageUpload", "label": "参考图", "required": true, "maxCount": 10 }
    ]
  }
}
```

### 3. 管理后台页面

路径：侧边栏 → **平台参数管理** → **模型参数配置**

- 进入页面后需先选择平台，才会显示该平台下已配置的模型参数
- 新建时：选择平台 → 手动填入模型 UUID（从模型管理页复制）→ 配置参数 JSON → 保存
- params 字段提供 JSON 编辑器和格式化按钮

## params 字段说明

`ui` 值与前端控件映射：

| ui | 控件 | 必需字段 | 说明 |
|----|------|---------|------|
| `textarea` | 文本输入框 | name, default | 提示词 |
| `proportion` | 比例选择器 | options | `options` 含 `custom` 时允许自定义宽高 |
| `resolution` | 分辨率选择器 | options | 与 proportion 共用弹窗 |
| `dimension` | 组合尺寸 | `dimension: { separator, width: {min,max}, height: {min,max} }` | 单字段 `"W*H"` 格式，前端根据 separator 生成 parse/format |
| `dimensionWidth` / `dimensionHeight` | 分离尺寸 | min, max | 两个独立字段，共享比例锁。必须传 min/max 作为输入校验边界 |
| `select` | 下拉选择 | options | 通用 |
| `quantity` | 生成数量 | options（**数字数组**） | `options` 必须为数字类型 `[1,2,3]`，前端 `Math.max()` 计算上限 |
| `imageUpload` | 图片上传 | maxCount | 控制上传数量上限。顶层 `maxImages` 仅作 fallback |
| `number` | 数字输入 | min, max | 自定义宽高（如 Flux 的 customWidth/customHight），支持 `showWhen` 条件显示 |
| `hidden` | 不渲染 | default | 静默写入默认值 |

**`inputType` 枚举值**：`text`（文生图）/ `image`（图生图/图片编辑）/ `both`（同时支持，可传图也可不传）

**条件显示**：`"showWhen": { "aspectRatio": "custom" }` 使参数仅在比例为自定义时显示。

**字段类型速查**：

| 字段 | 类型 | 适用 ui | 前端读取位置 |
|------|------|---------|-------------|
| `name` | string | 全部 | 各处以 `p.name` 查找 |
| `ui` | string | 全部 | `getDimConfig`、controls `show()` |
| `default` | any | 全部 | `syncDefaults` |
| `options` | array | proportion/resolution/select/quantity | 控件 props、`Math.max` |
| `min` / `max` | number | dimensionWidth/dimensionHeight/number | `getDimConfig` 校验边界 |
| `maxCount` | number | imageUpload | `imageUploadLimit` |
| `dimension.separator` | string | dimension | `syncDefaults` 解析 W*H |
| `dimension.width.min/max` | number | dimension | `getDimConfig` 宽度校验 |
| `dimension.height.min/max` | number | dimension | `getDimConfig` 高度校验 |
| `showWhen` | object | 任意 | 条件显示（需前端改造） |

## 已配置数据

`ai_painting_talk`（AI绘画new）平台下 8 个模型已完成参数配置：

| 模型 | 输入类型 | 参数数 |
|------|---------|--------|
| Flux 2 | text | 5 |
| Z-Image Turbo | text | 3 |
| 即梦4.6 | text | 4 |
| 通义万相2.0 | text | 3 |
| GPT-Image-2 | text | 4 |
| Nano Pro | image | 4 |
| 通义万相2.0 Pro | image | 4 |
| GPT-Image-2 I2I | image | 5 |

`ai_video_talk`（AI视频new）暂未配置。

## 客户端接入

AI_Painting_V2.0 前端可调用 `GET /suanli/v1/models/{modelId}/config` 获取参数配置，替代当前的本地 JS 硬编码和远程 JSON 拉取。接入后删除：

- `src/platforms/painting/models/` 目录
- `src/utils/modelConfig.js`
- `src/utils/createTask.js`

## 注意事项

- 参数配置**不同步到转发层**，仅用于驱动前端 UI 渲染，不影响任务执行
- 模型 ID 为 UUID 格式，需从「模型管理」页面复制
- 直接操作数据库（手动 SQL 插入/更新）不会触发任何副作用，安全