chore: initial commit of ai site platform
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
39
blueprint/openapi/README.md
Normal file
39
blueprint/openapi/README.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# API 契约（唯一）
|
||||
|
||||
- **运行时契约**：`GET /api/v1/meta/openapi.yaml`（与代码同嵌入）
|
||||
- **目录清单**：`GET /api/v1/meta/apis`
|
||||
- **源文件**：`platform/internal/handler/openapi.yaml` + `platform/internal/apidef/catalog.go`
|
||||
|
||||
## 动词
|
||||
|
||||
| 方法 | 用途 |
|
||||
|------|------|
|
||||
| GET | 读取 |
|
||||
| POST | 创建，或无幂等动作（login / import / publish / generate） |
|
||||
| PUT | 更新 |
|
||||
| DELETE | 删除 |
|
||||
|
||||
禁止再用 PATCH 作为更新主路径；禁止为行业场景新增平行 CRUD。
|
||||
|
||||
## 动态业务数据
|
||||
|
||||
仅：
|
||||
|
||||
```http
|
||||
GET|POST /api/v1/apps/{slug}/{resource}
|
||||
GET|PUT|DELETE /api/v1/apps/{slug}/{resource}/{id}
|
||||
POST /api/v1/apps/{slug}/{resource}/import
|
||||
GET /api/v1/apps/{slug}/{resource}/export
|
||||
GET /api/v1/apps/{slug}/{resource}/aggregate
|
||||
```
|
||||
|
||||
字段由蓝图定义，平台不做行业写死接口。
|
||||
|
||||
## AI（不重复实现）
|
||||
|
||||
经网关 `/ai` 前缀：
|
||||
|
||||
```http
|
||||
POST /ai/api/v1/apps/generate
|
||||
GET /ai/api/v1/llm/providers
|
||||
```
|
||||
326
blueprint/openapi/dynamic-crud.openapi.yaml
Normal file
326
blueprint/openapi/dynamic-crud.openapi.yaml
Normal file
@@ -0,0 +1,326 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: AI建站 Platform API
|
||||
version: 1.0.0
|
||||
description: |
|
||||
通用中台契约。业务行数据仅通过 apps/{slug}/{resource} CRUD 传输；
|
||||
行业字段由蓝图定义，不在此增加行业专用路由。
|
||||
动词约定：GET 读 / POST 创建或动作 / PUT 更新 / DELETE 删除。
|
||||
servers:
|
||||
- url: http://127.0.0.1:8180
|
||||
paths:
|
||||
/api/v1/meta/apis:
|
||||
get:
|
||||
operationId: listApis
|
||||
summary: API 目录
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
/api/v1/meta/openapi.yaml:
|
||||
get:
|
||||
operationId: getOpenAPI
|
||||
summary: OpenAPI 原文
|
||||
responses:
|
||||
"200":
|
||||
description: YAML
|
||||
/api/v1/auth/register:
|
||||
post:
|
||||
operationId: authRegister
|
||||
summary: 注册
|
||||
responses:
|
||||
"201": { description: Created }
|
||||
/api/v1/auth/login:
|
||||
post:
|
||||
operationId: authLogin
|
||||
summary: 登录
|
||||
responses:
|
||||
"200": { description: OK }
|
||||
/api/v1/auth/token:
|
||||
post:
|
||||
operationId: authToken
|
||||
summary: 服务签发 JWT
|
||||
responses:
|
||||
"200": { description: OK }
|
||||
|
||||
/api/v1/apps/{slug}/publish:
|
||||
post:
|
||||
operationId: publishApp
|
||||
summary: 发布蓝图
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Slug"
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
responses:
|
||||
"200": { description: OK }
|
||||
/api/v1/apps/{slug}/blueprint:
|
||||
get:
|
||||
operationId: getBlueprint
|
||||
summary: 读取蓝图
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Slug"
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
responses:
|
||||
"200": { description: OK }
|
||||
/api/v1/apps/{slug}/agent-capsule:
|
||||
get:
|
||||
operationId: getAgentCapsule
|
||||
summary: 智能体胶囊
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Slug"
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
responses:
|
||||
"200": { description: OK }
|
||||
|
||||
/api/v1/apps/{slug}/{resource}:
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Slug"
|
||||
- $ref: "#/components/parameters/Resource"
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
get:
|
||||
operationId: listRows
|
||||
summary: 列表
|
||||
parameters:
|
||||
- name: page
|
||||
in: query
|
||||
schema: { type: integer, minimum: 1, default: 1 }
|
||||
- name: page_size
|
||||
in: query
|
||||
schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
|
||||
- name: sort
|
||||
in: query
|
||||
schema: { type: string }
|
||||
- name: filter.*
|
||||
in: query
|
||||
description: 如 filter.status=在售，键须在蓝图 allowed_filters
|
||||
schema: { type: string }
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/PageResult"
|
||||
post:
|
||||
operationId: createRow
|
||||
summary: 创建
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
responses:
|
||||
"201":
|
||||
description: Created
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Row"
|
||||
|
||||
/api/v1/apps/{slug}/{resource}/{id}:
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Slug"
|
||||
- $ref: "#/components/parameters/Resource"
|
||||
- $ref: "#/components/parameters/Id"
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
get:
|
||||
operationId: getRow
|
||||
summary: 详情
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Row"
|
||||
"404":
|
||||
$ref: "#/components/responses/NotFound"
|
||||
put:
|
||||
operationId: updateRow
|
||||
summary: 更新
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Row"
|
||||
delete:
|
||||
operationId: deleteRow
|
||||
summary: 删除
|
||||
responses:
|
||||
"204": { description: No Content }
|
||||
|
||||
/api/v1/apps/{slug}/{resource}/import:
|
||||
post:
|
||||
operationId: importRows
|
||||
summary: 导入
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Slug"
|
||||
- $ref: "#/components/parameters/Resource"
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
multipart/form-data:
|
||||
schema:
|
||||
type: object
|
||||
required: [file]
|
||||
properties:
|
||||
file: { type: string, format: binary }
|
||||
responses:
|
||||
"200": { description: OK }
|
||||
|
||||
/api/v1/apps/{slug}/{resource}/export:
|
||||
get:
|
||||
operationId: exportRows
|
||||
summary: 导出
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Slug"
|
||||
- $ref: "#/components/parameters/Resource"
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
- name: format
|
||||
in: query
|
||||
schema: { type: string, enum: [xlsx, csv], default: xlsx }
|
||||
responses:
|
||||
"200": { description: 文件流 }
|
||||
|
||||
/api/v1/apps/{slug}/{resource}/aggregate:
|
||||
get:
|
||||
operationId: aggregateRows
|
||||
summary: 聚合
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Slug"
|
||||
- $ref: "#/components/parameters/Resource"
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
- name: group_by
|
||||
in: query
|
||||
schema: { type: string }
|
||||
- name: sum
|
||||
in: query
|
||||
schema: { type: string }
|
||||
responses:
|
||||
"200": { description: OK }
|
||||
|
||||
/api/v1/audit/logs:
|
||||
get:
|
||||
operationId: listAuditLogs
|
||||
summary: 审计日志
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
responses:
|
||||
"200": { description: OK }
|
||||
|
||||
/api/v1/storage:
|
||||
post:
|
||||
operationId: uploadObject
|
||||
summary: 上传
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
multipart/form-data:
|
||||
schema:
|
||||
type: object
|
||||
required: [file]
|
||||
properties:
|
||||
file: { type: string, format: binary }
|
||||
responses:
|
||||
"200": { description: OK }
|
||||
|
||||
/api/v1/storage/{tenant}/{day}/{name}:
|
||||
get:
|
||||
operationId: downloadObject
|
||||
summary: 下载
|
||||
parameters:
|
||||
- $ref: "#/components/parameters/Authorization"
|
||||
- name: tenant
|
||||
in: path
|
||||
required: true
|
||||
schema: { type: string }
|
||||
- name: day
|
||||
in: path
|
||||
required: true
|
||||
schema: { type: string }
|
||||
- name: name
|
||||
in: path
|
||||
required: true
|
||||
schema: { type: string }
|
||||
responses:
|
||||
"200": { description: 文件流 }
|
||||
|
||||
/api/v1/apps/generate:
|
||||
post:
|
||||
operationId: generateBlueprint
|
||||
summary: 生成蓝图（AI 服务，经网关 /ai 前缀）
|
||||
description: 实际请求 /ai/api/v1/apps/generate；勿在 platform 重复实现。
|
||||
requestBody:
|
||||
content:
|
||||
multipart/form-data:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
prompt: { type: string }
|
||||
excel: { type: string, format: binary }
|
||||
images: { type: string, format: binary }
|
||||
responses:
|
||||
"200": { description: OK }
|
||||
|
||||
/api/v1/llm/providers:
|
||||
get:
|
||||
operationId: listLlmProviders
|
||||
summary: LLM 厂商（AI 服务）
|
||||
responses:
|
||||
"200": { description: OK }
|
||||
|
||||
components:
|
||||
parameters:
|
||||
Authorization:
|
||||
name: Authorization
|
||||
in: header
|
||||
required: true
|
||||
schema: { type: string }
|
||||
description: Bearer JWT
|
||||
Slug:
|
||||
name: slug
|
||||
in: path
|
||||
required: true
|
||||
schema: { type: string, pattern: "^[a-z][a-z0-9_]{1,47}$" }
|
||||
Resource:
|
||||
name: resource
|
||||
in: path
|
||||
required: true
|
||||
schema: { type: string }
|
||||
description: 蓝图 apis.resources.path（无前导 /）；不可为保留名
|
||||
Id:
|
||||
name: id
|
||||
in: path
|
||||
required: true
|
||||
schema: { type: string }
|
||||
schemas:
|
||||
PageResult:
|
||||
type: object
|
||||
properties:
|
||||
items: { type: array, items: { $ref: "#/components/schemas/Row" } }
|
||||
total: { type: integer }
|
||||
Row:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
responses:
|
||||
NotFound:
|
||||
description: Not Found
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
code: { type: integer }
|
||||
message: { type: string }
|
||||
Reference in New Issue
Block a user