# 应用蓝图落地说明（v1）

用户上传「描述/图片 + Excel」后，系统只围绕一份 **AppBlueprint JSON** 工作：AI 生成 → 校验 → 用户确认 → 中台执行建库/挂 API/渲染页面。

## 目录

| 路径 | 作用 |
|------|------|
| `schema/app-blueprint.schema.json` | 蓝图 JSON Schema（契约） |
| `examples/inventory-ledger.blueprint.json` | 完整示例（库存台账） |
| `openapi/dynamic-crud.openapi.yaml` | 动态 API 形状（按蓝图挂载） |
| `platform/execution-steps.md` | 中台执行步骤与安全闸门 |
| `ai/prompt-contract.md` | AI 服务输入输出约定 |

## 主链路

```text
1) 上传 excel + prompt/image
2) FastAPI：解析 Excel + 多模态理解 → 产出 blueprint draft
3) 用 JSON Schema 校验；置信度 < 0.75 强制人工确认
4) 用户确认/改字段
5) go-zero：
   - 分配 schema_name / database
   - CREATE TABLE（白名单 DDL）
   - 注册元数据
   - 按 apis 挂动态 CRUD
   - 可选导入 Excel 行
6) 前端：按 pages[] 渲染，不落不可控源码
```

## 服务边界

### AI 服务（FastAPI）

- **能做**：推断实体、字段类型、页面布局、图表建议
- **不能做**：直接连业务库执行 SQL、注册网关路由、写连接串

输出：`AppBlueprint` draft + `warnings[]`

### 中台（go-zero）

- **能做**：租户鉴权、DDL 执行、元数据落库、动态 API、审计
- **不能做**：信任模型原文；必须 Schema 校验 + 标识符白名单

### 前端渲染器

输入：`GET /api/v1/apps/{slug}/blueprint`  
按 `pages[].type` 渲染 list/form/dashboard。

## 动态 API（示例应用）

确认并发布后，库存示例会得到：

```http
GET    /api/v1/apps/inventory_ledger/inventory_items
GET    /api/v1/apps/inventory_ledger/inventory_items/{id}
POST   /api/v1/apps/inventory_ledger/inventory_items
PATCH  /api/v1/apps/inventory_ledger/inventory_items/{id}
DELETE /api/v1/apps/inventory_ledger/inventory_items/{id}
POST   /api/v1/apps/inventory_ledger/inventory_items:import
GET    /api/v1/apps/inventory_ledger/inventory_items:export
```

所有请求强制：`Authorization` + 租户上下文；`row_policies=tenant_isolated` 由服务端注入，客户端不可关。

## 本地快速校验示例

用任意 JSON Schema 校验器验证示例：

```bash
# 需本机有 ajv-cli 或等价工具
npx --yes ajv-cli validate -s blueprint/schema/app-blueprint.schema.json -d blueprint/examples/inventory-ledger.blueprint.json
```

## 版本策略

- `version: "1.0"` 固定本契约
- 不兼容变更升 `1.1` / `2.0`，旧应用蓝图可继续读取
- AI 与中台只认 Schema 内字段；多余字段校验失败