# AI 服务输入输出约定

## 输入

`POST /api/v1/apps:generate`（可由网关转到 FastAPI）

| 字段 | 必填 | 说明 |
|------|------|------|
| prompt | 是 | 用户自然语言需求 |
| excel | 否 | xlsx/xls/csv |
| images[] | 否 | 页面截图/手绘线框，最多 10 |
| storage_mode | 否 | 默认 `schema_per_app` |

Excel 解析侧建议先产出中间结构再喂给 LLM：

```json
{
  "sheets": [
    {
      "name": "Sheet1",
      "headers": ["SKU", "商品名称", "仓库", "数量", "单价", "状态", "更新时间"],
      "sample_rows": [
        ["A-1001", "无线鼠标", "华东仓", 120, 59.9, "在售", "2026-07-01 10:00:00"]
      ],
      "inferred_types": {
        "SKU": "string",
        "数量": "int",
        "单价": "decimal"
      }
    }
  ]
}
```

## 输出

```json
{
  "draft": { "...": "AppBlueprint" },
  "warnings": [
    "列「备注」样本过少，已标为可空 text",
    "截图中有图表区域，已生成 dashboard 草案"
  ],
  "confidence": 0.86,
  "require_confirm": true
}
```

规则：

- `draft` 必须能通过 `app-blueprint.schema.json`
- `confidence < 0.75` ⇒ `require_confirm=true`（前端禁止一键跳过）
- 字段名、表名由 AI 生成后，**发布前中台会再次规范化/重写**
- 不得在输出中包含数据库连接串、密码、任意 SQL

## 系统提示词要点（实现时使用）

1. 只输出符合 Schema 的 JSON（可包在 draft 字段）  
2. 一表对应 Excel 主 sheet；多 sheet 才多 entity（≤ 20）  
3. 优先 enum：当某列 distinct 值 ≤ 20 且稳定  
4. 页面至少包含一个 `list`；若用户提到统计再加 `dashboard`  
5. API operations 默认 `list/get/create/update/delete/**import**/**export**`；列表页 `layout.actions` 默认含 `import`（及 `export`）。**不要**因需求未提「导入」而省略。仅当用户明确禁止导入/导出时才去掉对应 op/action  
6. `security.visibility` 默认 `private`，`row_policies` 默认 `tenant_isolated`  

## 与中台的分工

```text
AI：理解意图，填蓝图
中台：校验、改写标识符、建表、挂路由、强制租户隔离
前端：确认页编辑蓝图 → publish → 用 blueprint 渲染
```