80 lines
2.6 KiB
Markdown
80 lines
2.6 KiB
Markdown
# 应用蓝图落地说明（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 内字段；多余字段校验失败
|