142 lines
4.3 KiB
YAML
142 lines
4.3 KiB
YAML
openapi: 3.1.1
|
||
info:
|
||
title: SaaS Platform Admin Query API
|
||
version: 1.0.0
|
||
description: |
|
||
通用数据查询接口，供系统管理员智能体（如 Dify Agent）使用。
|
||
接收自然语言问题，返回结构化平台数据。
|
||
所有查询自动应用租户隔离、权限控制和敏感字段脱敏。
|
||
|
||
servers:
|
||
- url: https://service.aigc-quickapp.com/api/v1
|
||
description: Internal Admin API Gateway (SaaS Platform)
|
||
|
||
paths:
|
||
/admin/query:
|
||
post:
|
||
summary: 查询 SaaS 平台数据（自然语言接口）
|
||
description: |
|
||
接收自然语言形式的问题，智能解析并返回平台相关数据。
|
||
支持订单、用户、商品、租户、GMV、日志等维度的查询。
|
||
示例问题：
|
||
- "商家 TechStore 昨天的 GMV 是多少？"
|
||
- "列出所有未发货的订单"
|
||
- "用户 12345 最近一次登录时间？"
|
||
|
||
operationId: queryPlatformData
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/QueryRequest'
|
||
|
||
responses:
|
||
'200':
|
||
description: 查询成功，返回结构化数据
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/QueryResponse'
|
||
'400':
|
||
description: 请求参数无效（如缺少 question）
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
'401':
|
||
description: 未授权（API Key 缺失或无效）
|
||
'403':
|
||
description: 权限不足（如越权查询其他租户）
|
||
'500':
|
||
description: 内部服务错误
|
||
|
||
security:
|
||
- AdminApiKey: []
|
||
|
||
components:
|
||
schemas:
|
||
QueryRequest:
|
||
type: object
|
||
required:
|
||
- question
|
||
properties:
|
||
question:
|
||
type: string
|
||
description: |
|
||
用户提出的自然语言问题。
|
||
必须清晰、具体，包含必要上下文（如商家名、时间范围等）。
|
||
example: "tenant-abc 上周的订单总量是多少？"
|
||
context:
|
||
type: object
|
||
description: |
|
||
可选上下文信息，用于辅助解析（如当前用户所属租户）。
|
||
由调用方（如 Dify Agent）根据对话上下文填充。
|
||
properties:
|
||
current_tenant_id:
|
||
type: string
|
||
description: 当前操作者所属租户 ID
|
||
example: "tenant-xyz"
|
||
operator_role:
|
||
type: string
|
||
description: 操作者角色（如 admin, support）
|
||
enum: [admin, support, super_admin]
|
||
additionalProperties: false
|
||
|
||
QueryResponse:
|
||
type: object
|
||
required:
|
||
- result
|
||
properties:
|
||
result:
|
||
oneOf:
|
||
- type: object
|
||
description: 结构化数据对象（如单条记录）
|
||
- type: array
|
||
description: 数据列表（如订单列表）
|
||
items:
|
||
type: object
|
||
- type: string
|
||
description: 简单值（如数字、文本）
|
||
- type: null
|
||
description: 无结果
|
||
example:
|
||
orders_count: 142
|
||
gmv: "¥28,400.00"
|
||
return_rate: "2.1%"
|
||
metadata:
|
||
type: object
|
||
description: 查询元信息（调试用）
|
||
properties:
|
||
executed_query_type:
|
||
type: string
|
||
description: 实际执行的查询类型
|
||
example: "sales_summary_by_tenant"
|
||
data_source:
|
||
type: string
|
||
description: 数据来源
|
||
example: "orders_analytics_view"
|
||
processing_time_ms:
|
||
type: integer
|
||
additionalProperties: false
|
||
|
||
ErrorResponse:
|
||
type: object
|
||
required:
|
||
- error
|
||
properties:
|
||
error:
|
||
type: string
|
||
example: "MISSING_REQUIRED_FIELD: 'question' is required"
|
||
details:
|
||
type: object
|
||
additionalProperties: true
|
||
|
||
securitySchemes:
|
||
AdminApiKey:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: JWT
|
||
description: |
|
||
Bearer Token 格式的管理员 API Key。
|
||
示例：`Authorization: Bearer sk-admin-xxxxxxxxxxxx` |