wpic-dev/datahub
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f3f73935e11d3a62ea93ce66395256db9850343c
datahub/backend/storage/openapi.json
T

7217 lines
306 KiB
JSON
Raw Normal View History

add mq controller
2026-03-13 14:50:06 +08:00
{
"openapi": "3.0.0",
"info": {
"title": "Datahub API",
"description": "Datahub API documentation",
"version": "1.0.0"
},
"servers": [
{
"url": "/api/v1",
"description": "API v1"
}
],
"paths": {
update mq controller
2026-03-13 15:01:55 +08:00
"/api/v1/failed-messages": {
"get": {
"tags": [
"Failed Messages"
],
"summary": "失败消息列表",
"description": "获取 Consumer 处理失败的消息列表，支持分页、按数据类型/平台/时间筛选。仅 admin 可访问。",
"operationId": "6dac9bdff8b35f75565ed5c6b8638937",
"parameters": [
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 15,
"maximum": 100
}
},
{
"name": "data_type",
"in": "query",
"description": "数据类型精确筛选（order/product/refund）",
"required": false,
"schema": {
"type": "string",
"enum": [
"order",
"product",
"refund"
]
}
},
{
"name": "platform_id",
"in": "query",
"description": "平台 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "error_type",
"in": "query",
"description": "异常类名模糊搜索",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "failed_at_from",
"in": "query",
"description": "失败时间起始（含）",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2026-01-01"
}
},
{
"name": "failed_at_to",
"in": "query",
"description": "失败时间截止（含）",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2026-12-31"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FailedMessageList"
}
},
"total": {
"type": "integer",
"example": 100
},
"page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 15
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "无权限",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/failed-messages/{id}": {
"get": {
"tags": [
"Failed Messages"
],
"summary": "失败消息详情",
"description": "获取失败消息详情，含完整错误堆栈和原始消息体。仅 admin 可访问。",
"operationId": "4f6b7410222ebc0fa65afdc1d168c15a",
"parameters": [
{
"name": "id",
"in": "path",
"description": "失败消息 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"$ref": "#/components/schemas/FailedMessageDetail"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "无权限",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "数据不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
add mq controller
2026-03-13 14:50:06 +08:00
"/api/v1/mq/status": {
"get": {
"tags": [
"MQ Status"
],
"summary": "获取消息队列状态",
"description": "查询 RabbitMQ 各队列的消息数、消费者数和运行状态。支持按队列类型筛选。仅 admin 角色可访问。",
"operationId": "3f5b041034fafc9738ecf65f166b6193",
"parameters": [
{
"name": "queue",
"in": "query",
"description": "队列类型筛选（orders/products/refunds/inventory）",
"required": false,
"schema": {
"type": "string",
"enum": [
"orders",
"products",
"refunds",
"inventory"
]
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"$ref": "#/components/schemas/MqQueueStatus"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "无效的队列类型参数",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "无权限",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"500": {
"description": "RabbitMQ 连接异常",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/orders": {
"get": {
"tags": [
"Orders"
],
"summary": "订单列表",
"description": "获取订单列表，支持分页、多维度筛选和时间范围筛选。返回业务字段，不含 raw/hash。",
"operationId": "7e493d0464138129e7e1f0e7ebee178b",
"parameters": [
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 15,
"maximum": 100
}
},
{
"name": "company_id",
"in": "query",
"description": "公司 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "platform_id",
"in": "query",
"description": "平台 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "store_id",
"in": "query",
"description": "店铺 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "order_status_id",
"in": "query",
"description": "订单状态 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "platform_order_id",
"in": "query",
"description": "平台订单 ID 精确搜索",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "created_date_from",
"in": "query",
"description": "创建时间起始（含）",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2026-01-01"
}
},
{
"name": "created_date_to",
"in": "query",
"description": "创建时间截止（含）",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2026-12-31"
}
},
{
"name": "paid_date_from",
"in": "query",
"description": "付款时间起始（含）",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2026-01-01"
}
},
{
"name": "paid_date_to",
"in": "query",
"description": "付款时间截止（含）",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2026-12-31"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Order"
}
},
"total": {
"type": "integer",
"example": 100
},
"page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 15
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "无权限",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/orders/{id}": {
"get": {
"tags": [
"Orders"
],
"summary": "订单详情",
"description": "获取订单详情，返回所有业务字段、ext 和关联的 order_items，不含 raw/hash。",
"operationId": "aff126ce9a5cef811fea88ceba395fdc",
"parameters": [
{
"name": "id",
"in": "path",
"description": "订单 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Order"
},
{
"properties": {
"order_items": {
"description": "关联订单子项",
"type": "array",
"items": {
"type": "object"
}
}
},
"type": "object"
}
]
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "无权限",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "数据不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/order-items": {
"get": {
"tags": [
"Order Items"
],
"summary": "订单项列表",
"description": "获取订单项列表，支持分页和多维度筛选。OrderItem 无 raw/hash 字段，仅提供 Normal 接口。",
"operationId": "894b5ea5fad8ecc3159e628333252260",
"parameters": [
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 15,
"maximum": 100
}
},
{
"name": "company_id",
"in": "query",
"description": "公司 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "platform_id",
"in": "query",
"description": "平台 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "store_id",
"in": "query",
"description": "店铺 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "order_id",
"in": "query",
"description": "内部订单 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "platform_order_id",
"in": "query",
"description": "平台订单 ID 精确筛选",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "platform_product_id",
"in": "query",
"description": "平台商品 ID 精确筛选",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "product_sku",
"in": "query",
"description": "SKU 编码精确筛选",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "created_date_from",
"in": "query",
"description": "创建时间起始（含）",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2026-01-01"
}
},
{
"name": "created_date_to",
"in": "query",
"description": "创建时间截止（含）",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2026-12-31"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OrderItem"
}
},
"total": {
"type": "integer",
"example": 100
},
"page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 15
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "无权限",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/order-items/{id}": {
"get": {
"tags": [
"Order Items"
],
"summary": "订单项详情",
"description": "获取订单项详情，返回完整字段和关联的父订单摘要信息。",
"operationId": "a808f2d76861f46925baef81c52da14f",
"parameters": [
{
"name": "id",
"in": "path",
"description": "订单项 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/OrderItem"
},
{
"properties": {
"parent_order": {
"description": "父订单摘要信息",
"type": "object",
"nullable": true
}
},
"type": "object"
}
]
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "无权限",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "数据不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/products": {
"get": {
"tags": [
"Products"
],
"summary": "产品列表",
"description": "获取产品列表，支持分页、多维度筛选。返回业务字段，不含 raw/hash。",
"operationId": "934e471439896276d2897b4b5132c077",
"parameters": [
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 15,
"maximum": 100
}
},
{
"name": "company_id",
"in": "query",
"description": "公司 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "platform_id",
"in": "query",
"description": "平台 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "store_id",
"in": "query",
"description": "店铺 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "status_id",
"in": "query",
"description": "产品状态 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "platform_item_id",
"in": "query",
"description": "平台商品 ID 精确搜索",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "name",
"in": "query",
"description": "商品名称模糊搜索",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Product"
}
},
"total": {
"type": "integer",
"example": 100
},
"page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 15
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "无权限",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/products/{id}": {
"get": {
"tags": [
"Products"
],
"summary": "产品详情",
"description": "获取产品详情，返回所有业务字段和 ext，不含 raw/hash。",
"operationId": "7d7422e8293b23608368a4a9000f8096",
"parameters": [
{
"name": "id",
"in": "path",
"description": "产品 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"$ref": "#/components/schemas/Product"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "无权限",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "数据不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/raw/orders": {
"get": {
"tags": [
"Orders (Raw)"
],
"summary": "订单列表（Raw）",
"description": "获取订单原始数据列表。返回关键标识 + hash，不含 raw 字段本身（太大）。筛选参数与 Normal 接口一致。",
"operationId": "562f4be5afd7463d1c9c9c653bdd0c35",
"parameters": [
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 15,
"maximum": 100
}
},
{
"name": "company_id",
"in": "query",
"description": "公司 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "platform_id",
"in": "query",
"description": "平台 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "store_id",
"in": "query",
"description": "店铺 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "order_status_id",
"in": "query",
"description": "订单状态 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "platform_order_id",
"in": "query",
"description": "平台订单 ID 精确搜索",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "created_date_from",
"in": "query",
"description": "创建时间起始（含）",
"required": false,
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "created_date_to",
"in": "query",
"description": "创建时间截止（含）",
"required": false,
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "paid_date_from",
"in": "query",
"description": "付款时间起始（含）",
"required": false,
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "paid_date_to",
"in": "query",
"description": "付款时间截止（含）",
"required": false,
"schema": {
"type": "string",
"format": "date"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"properties": {
"items": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"platform_order_id": {
"type": "string"
},
"store_id": {
"type": "integer"
},
"company_id": {
"type": "integer"
},
"platform_id": {
"type": "integer"
},
"order_status_id": {
"type": "integer"
},
"hash": {
"type": "string"
},
"created_date": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
},
"total": {
"type": "integer"
},
"page": {
"type": "integer"
},
"per_page": {
"type": "integer"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "无权限",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/raw/orders/{id}": {
"get": {
"tags": [
"Orders (Raw)"
],
"summary": "订单详情（Raw）",
"description": "获取订单原始数据详情。返回关键标识 + 完整 raw + hash + ext。",
"operationId": "6c9b613233d2ef2a708d51523149d84b",
"parameters": [
{
"name": "id",
"in": "path",
"description": "订单 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"properties": {
"id": {
"type": "integer"
},
"platform_order_id": {
"type": "string"
},
"store_id": {
"type": "integer"
},
"company_id": {
"type": "integer"
},
"platform_id": {
"type": "integer"
},
"order_status_id": {
"type": "integer"
},
"raw": {
"description": "平台原始数据",
"type": "object"
},
"hash": {
"type": "string"
},
"ext": {
"type": "object",
"nullable": true
},
"created_date": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "无权限",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "数据不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/raw/products": {
"get": {
"tags": [
"Products (Raw)"
],
"summary": "产品列表（Raw）",
"description": "获取产品原始数据列表。返回关键标识 + hash，不含 raw 字段本身（太大）。筛选参数与 Normal 接口一致。",
"operationId": "770fd6e9caf314efbc05aa0277c7e811",
"parameters": [
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 15,
"maximum": 100
}
},
{
"name": "company_id",
"in": "query",
"description": "公司 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "platform_id",
"in": "query",
"description": "平台 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "store_id",
"in": "query",
"description": "店铺 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "status_id",
"in": "query",
"description": "产品状态 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "platform_item_id",
"in": "query",
"description": "平台商品 ID 精确搜索",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "name",
"in": "query",
"description": "商品名称模糊搜索",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"properties": {
"items": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"platform_item_id": {
"type": "string"
},
"platform_model_id": {
"type": "string",
"nullable": true
},
"name": {
"type": "string",
"nullable": true
},
"store_id": {
"type": "integer"
},
"company_id": {
"type": "integer"
},
"platform_id": {
"type": "integer"
},
"hash": {
"type": "string"
},
"updated_date": {
"type": "string",
"format": "date-time",
"nullable": true
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
},
"total": {
"type": "integer"
},
"page": {
"type": "integer"
},
"per_page": {
"type": "integer"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "无权限",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/raw/products/{id}": {
"get": {
"tags": [
"Products (Raw)"
],
"summary": "产品详情（Raw）",
"description": "获取产品原始数据详情。返回关键标识 + 完整 raw + hash + ext。",
"operationId": "e0ba90775ff4ceb4fe459b8272a63624",
"parameters": [
{
"name": "id",
"in": "path",
"description": "产品 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"properties": {
"id": {
"type": "integer"
},
"platform_item_id": {
"type": "string"
},
"platform_model_id": {
"type": "string",
"nullable": true
},
"name": {
"type": "string",
"nullable": true
},
"store_id": {
"type": "integer"
},
"company_id": {
"type": "integer"
},
"platform_id": {
"type": "integer"
},
"raw": {
"description": "平台原始数据",
"type": "object"
},
"hash": {
"type": "string"
},
"ext": {
"type": "object",
"nullable": true
},
"created_date": {
"type": "string",
"format": "date-time",
"nullable": true
},
"updated_date": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "无权限",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "数据不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/raw/refunds": {
"get": {
"tags": [
"Refunds (Raw)"
],
"summary": "退款列表（Raw）",
"description": "获取退款原始数据列表。返回关键标识 + hash，不含 raw 字段本身（太大）。筛选参数与 Normal 接口一致。",
"operationId": "04e3c7e28df6496b975c24618933c6dd",
"parameters": [
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 15,
"maximum": 100
}
},
{
"name": "company_id",
"in": "query",
"description": "公司 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "platform_id",
"in": "query",
"description": "平台 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "store_id",
"in": "query",
"description": "店铺 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "refund_status_id",
"in": "query",
"description": "退款状态 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "refund_type_id",
"in": "query",
"description": "退款类型 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "platform_refund_id",
"in": "query",
"description": "平台退款 ID 精确搜索",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "platform_order_id",
"in": "query",
"description": "关联平台订单 ID 筛选",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "created_date_from",
"in": "query",
"description": "创建时间起始（含）",
"required": false,
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "created_date_to",
"in": "query",
"description": "创建时间截止（含）",
"required": false,
"schema": {
"type": "string",
"format": "date"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"properties": {
"items": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"platform_refund_id": {
"type": "string"
},
"platform_order_id": {
"type": "string"
},
"store_id": {
"type": "integer"
},
"company_id": {
"type": "integer"
},
"platform_id": {
"type": "integer"
},
"refund_status_id": {
"type": "integer"
},
"hash": {
"type": "string"
},
"created_date": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
},
"total": {
"type": "integer"
},
"page": {
"type": "integer"
},
"per_page": {
"type": "integer"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "无权限",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/raw/refunds/{id}": {
"get": {
"tags": [
"Refunds (Raw)"
],
"summary": "退款详情（Raw）",
"description": "获取退款原始数据详情。返回关键标识 + 完整 raw + hash + ext。",
"operationId": "884b7753642515815a193abb0cae88c9",
"parameters": [
{
"name": "id",
"in": "path",
"description": "退款 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"properties": {
"id": {
"type": "integer"
},
"platform_refund_id": {
"type": "string"
},
"platform_order_id": {
"type": "string"
},
"store_id": {
"type": "integer"
},
"company_id": {
"type": "integer"
},
"platform_id": {
"type": "integer"
},
"refund_status_id": {
"type": "integer"
},
"raw": {
"description": "平台原始数据",
"type": "object"
},
"hash": {
"type": "string"
},
"ext": {
"type": "object",
"nullable": true
},
"created_date": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "无权限",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "数据不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/raw/refund-items": {
"get": {
"tags": [
"Refund Items (Raw)"
],
"summary": "退款项列表（Raw）",
"description": "获取退款项原始数据列表。返回关键标识，不含 raw 字段本身（太大）。筛选参数与 Normal 接口一致。",
"operationId": "b1af2757230f49948c934063da9d627a",
"parameters": [
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 15,
"maximum": 100
}
},
{
"name": "company_id",
"in": "query",
"description": "公司 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "platform_id",
"in": "query",
"description": "平台 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "store_id",
"in": "query",
"description": "店铺 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "refund_id",
"in": "query",
"description": "父退款 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "refund_status_id",
"in": "query",
"description": "退款状态 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "refund_type_id",
"in": "query",
"description": "退款类型 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "platform_refund_id",
"in": "query",
"description": "平台退款子项 ID 精确搜索",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "platform_order_id",
"in": "query",
"description": "关联平台订单 ID 筛选",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "platform_product_id",
"in": "query",
"description": "平台商品 ID 精确筛选",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "created_date_from",
"in": "query",
"description": "创建时间起始（含）",
"required": false,
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "created_date_to",
"in": "query",
"description": "创建时间截止（含）",
"required": false,
"schema": {
"type": "string",
"format": "date"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"properties": {
"items": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"platform_refund_id": {
"type": "string"
},
"platform_parent_refund_id": {
"type": "string"
},
"platform_order_id": {
"type": "string"
},
"store_id": {
"type": "integer"
},
"company_id": {
"type": "integer"
},
"platform_id": {
"type": "integer"
},
"refund_status_id": {
"type": "integer"
},
"created_date": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
},
"total": {
"type": "integer"
},
"page": {
"type": "integer"
},
"per_page": {
"type": "integer"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "无权限",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/raw/refund-items/{id}": {
"get": {
"tags": [
"Refund Items (Raw)"
],
"summary": "退款项详情（Raw）",
"description": "获取退款项原始数据详情。返回关键标识 + 完整 raw + ext。",
"operationId": "6a82a9938eef667456c5a8948b984eb3",
"parameters": [
{
"name": "id",
"in": "path",
"description": "退款项 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"properties": {
"id": {
"type": "integer"
},
"platform_refund_id": {
"type": "string"
},
"platform_parent_refund_id": {
"type": "string"
},
"platform_order_id": {
"type": "string"
},
"store_id": {
"type": "integer"
},
"company_id": {
"type": "integer"
},
"platform_id": {
"type": "integer"
},
"refund_status_id": {
"type": "integer"
},
"raw": {
"description": "平台原始子项数据",
"type": "object"
},
"ext": {
"type": "object",
"nullable": true
},
"created_date": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "无权限",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "数据不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/refunds": {
"get": {
"tags": [
"Refunds"
],
"summary": "退款列表",
"description": "获取退款列表，支持分页、按退款状态/类型/时间范围筛选。返回业务字段，不含 raw/hash。",
"operationId": "bd68a8b63be96fc4bc13a7f914db8e6f",
"parameters": [
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 15,
"maximum": 100
}
},
{
"name": "company_id",
"in": "query",
"description": "公司 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "platform_id",
"in": "query",
"description": "平台 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "store_id",
"in": "query",
"description": "店铺 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "refund_status_id",
"in": "query",
"description": "退款状态 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "refund_type_id",
"in": "query",
"description": "退款类型 ID 精确筛选（1=未发货前退款 2=退货退款 3=退货后部分退款 4=无须退货退款 5=闪电退款）",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "platform_refund_id",
"in": "query",
"description": "平台退款 ID 精确搜索",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "platform_order_id",
"in": "query",
"description": "关联平台订单 ID 筛选",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "created_date_from",
"in": "query",
"description": "创建时间起始（含）",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2026-01-01"
}
},
{
"name": "created_date_to",
"in": "query",
"description": "创建时间截止（含）",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2026-12-31"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Refund"
}
},
"total": {
"type": "integer",
"example": 100
},
"page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 15
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "无权限",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/refunds/{id}": {
"get": {
"tags": [
"Refunds"
],
"summary": "退款详情",
"description": "获取退款详情，返回所有业务字段和 ext，不含 raw/hash。",
"operationId": "6009f4876a61b01d12a288fcfe78444c",
"parameters": [
{
"name": "id",
"in": "path",
"description": "退款 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"$ref": "#/components/schemas/Refund"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "无权限",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "数据不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/refund-items": {
"get": {
"tags": [
"Refund Items"
],
"summary": "退款项列表",
"description": "获取退款项列表，支持分页、按退款单/退款状态/类型/时间范围筛选。返回业务字段，不含 raw。",
"operationId": "ad798f6022c7e5b289827884ef582bc2",
"parameters": [
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 15,
"maximum": 100
}
},
{
"name": "company_id",
"in": "query",
"description": "公司 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "platform_id",
"in": "query",
"description": "平台 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "store_id",
"in": "query",
"description": "店铺 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "refund_id",
"in": "query",
"description": "父退款 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "refund_status_id",
"in": "query",
"description": "退款状态 ID 精确筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "refund_type_id",
"in": "query",
"description": "退款类型 ID 精确筛选（1=仅退款 2=退货退款 3=补偿退款）",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "platform_refund_id",
"in": "query",
"description": "平台退款子项 ID 精确搜索",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "platform_order_id",
"in": "query",
"description": "关联平台订单 ID 筛选",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "platform_product_id",
"in": "query",
"description": "平台商品 ID 精确筛选",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "created_date_from",
"in": "query",
"description": "创建时间起始（含）",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2026-01-01"
}
},
{
"name": "created_date_to",
"in": "query",
"description": "创建时间截止（含）",
"required": false,
"schema": {
"type": "string",
"format": "date",
"example": "2026-12-31"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RefundItem"
}
},
"total": {
"type": "integer",
"example": 100
},
"page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 15
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "无权限",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/refund-items/{id}": {
"get": {
"tags": [
"Refund Items"
],
"summary": "退款项详情",
"description": "获取退款项详情，返回所有业务字段和 ext，不含 raw。",
"operationId": "de6cf91ff904e528cba6f1b43f829a2c",
"parameters": [
{
"name": "id",
"in": "path",
"description": "退款项 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"$ref": "#/components/schemas/RefundItem"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "无权限",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "数据不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/me/api-keys": {
"get": {
"tags": [
"ApiKeys"
],
"summary": "API Key 列表",
"description": "列出当前用户的所有 API Keys",
"operationId": "c01c1650a1944005fe5b51f72bacbbd4",
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"key_prefix": {
"type": "string"
},
"last_used_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"enabled": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"ApiKeys"
],
"summary": "生成 API Key",
"description": "生成新的 API Key，需用户已启用 api_key_enabled。明文仅在生成时返回一次",
"operationId": "12fd3adae0626962960533c85569d1b1",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"example": "Production Key",
"maxLength": 100
},
"expires_at": {
"description": "过期时间，不传则永不过期",
"type": "string",
"format": "date-time",
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "生成成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "生成成功"
},
"data": {
"properties": {
"plain_key": {
"description": "明文 Key，仅此次可见",
"type": "string"
},
"api_key": {
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"key_prefix": {
"type": "string"
},
"expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"enabled": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "参数校验失败",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "未启用 API Key 功能",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/me/api-keys/{id}": {
"delete": {
"tags": [
"ApiKeys"
],
"summary": "删除 API Key",
"description": "删除 API Key",
"operationId": "7356615676c0ac3874f8657b49154931",
"parameters": [
{
"name": "id",
"in": "path",
"description": "API Key ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "删除成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "删除成功"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "API Key 不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/register": {
"post": {
"tags": [
"Auth"
],
"summary": "用户注册",
"description": "注册新用户，需提供用户名、密码和邮箱",
"operationId": "b099deca54ae9ddc3ee7e2261b6fc125",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"username",
"password",
"email"
],
"properties": {
"username": {
"type": "string",
"example": "new_user",
"maxLength": 20,
"minLength": 3
},
"password": {
"type": "string",
"example": "Pass_1234",
"maxLength": 32,
"minLength": 6
},
"email": {
"type": "string",
"format": "email",
"example": "user@example.com",
"maxLength": 100
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "注册成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "注册成功"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"username": {
"type": "string",
"example": "new_user"
},
"email": {
"type": "string",
"example": "user@example.com"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "参数校验失败或唯一性冲突",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/login": {
"post": {
"tags": [
"Auth"
],
"summary": "用户登录",
"description": "使用用户名和密码登录，返回 access_token 和 refresh_token",
"operationId": "383bcb1269d6dcce4609dc1f5d3ef129",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"username",
"password"
],
"properties": {
"username": {
"type": "string",
"example": "admin"
},
"password": {
"type": "string",
"example": "Pass_1234"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "登录成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "登录成功"
},
"data": {
"properties": {
"access_token": {
"type": "string"
},
"refresh_token": {
"type": "string"
},
"token_type": {
"type": "string",
"example": "Bearer"
},
"expires_in": {
"type": "integer",
"example": 7200
},
"user": {
"properties": {
"id": {
"type": "integer"
},
"username": {
"type": "string"
},
"email": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "参数校验失败",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "用户名或密码错误",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "账号已被禁用",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
}
}
},
"/refresh": {
"get": {
"tags": [
"Auth"
],
"summary": "刷新 Access Token",
"description": "使用 refresh_token 获取新的 access_token，同时轮换 refresh_token",
"operationId": "fc18486b361cc4791acbafd8a2f25fff",
"parameters": [
{
"name": "refresh_token",
"in": "query",
"description": "Refresh Token",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Token 刷新成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "Token 刷新成功"
},
"data": {
"properties": {
"access_token": {
"type": "string"
},
"refresh_token": {
"type": "string"
},
"token_type": {
"type": "string",
"example": "Bearer"
},
"expires_in": {
"type": "integer",
"example": 7200
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "缺少 refresh_token 参数",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "refresh_token 无效或已过期",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"403": {
"description": "账号已被禁用",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/me": {
"get": {
"tags": [
"Auth"
],
"summary": "获取当前用户信息",
"description": "获取当前用户信息",
"operationId": "f03c8d46af839b7dbd0b659647cab574",
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"username": {
"type": "string",
"example": "admin"
},
"email": {
"type": "string",
"example": "admin@example.com"
},
"status": {
"type": "integer",
"example": 1
},
"ext": {
"type": "object",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/me/profile": {
"put": {
"tags": [
"Auth"
],
"summary": "更新个人信息",
"description": "当前用户更新自己的 email 和 ext 字段",
"operationId": "01c6d8f425109cd3dfff51d1d69cd55c",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"email": {
"type": "string",
"format": "email",
"example": "new@example.com",
"maxLength": 100
},
"ext": {
"type": "object",
"example": {
"nickname": "user"
},
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "更新成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "个人信息更新成功"
},
"data": {
"properties": {
"id": {
"type": "integer"
},
"username": {
"type": "string"
},
"email": {
"type": "string"
},
"status": {
"type": "integer"
},
"ext": {
"type": "object",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "参数校验失败或唯一性冲突",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/me/password": {
"put": {
"tags": [
"Auth"
],
"summary": "修改密码",
"description": "修改当前用户密码，需验证旧密码。修改成功后清除 refresh_token，需重新登录",
"operationId": "c3ca37414997ba697e6c11173d9bc483",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"old_password",
"new_password"
],
"properties": {
"old_password": {
"type": "string",
"example": "OldPass_1234"
},
"new_password": {
"type": "string",
"example": "NewPass_5678",
"maxLength": 32,
"minLength": 6
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "密码修改成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "密码修改成功，请重新登录"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "参数校验失败或旧密码不正确",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/logout": {
"get": {
"tags": [
"Auth"
],
"summary": "退出登录",
"description": "退出登录，清除 refresh_token 并注销当前 JWT token",
"operationId": "dc5f3d60e870dd8b211f88cd97635158",
"responses": {
"200": {
"description": "退出成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "退出成功"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/companies": {
"get": {
"tags": [
"Companies"
],
"summary": "公司列表",
"description": "获取公司列表，支持按 name/label 模糊搜索，受 scope 过滤",
"operationId": "e3e4d8f38acabbb4c061ba987d6e14dc",
"parameters": [
{
"name": "name",
"in": "query",
"description": "公司名称模糊搜索（匹配 name 或 label）",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "acme"
},
"label": {
"type": "string",
"example": "阿克米公司"
},
"enabled": {
"type": "boolean",
"example": true
},
"ext": {
"type": "object",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/users/{id}/data-scope": {
"get": {
"tags": [
"DataScope"
],
"summary": "查看用户数据权限",
"description": "返回用户的 scope 列表（含实体名称）和解析后的 store_ids",
"operationId": "0215f552f5c2315b8b93d030ef72db76",
"parameters": [
{
"name": "id",
"in": "path",
"description": "用户 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"properties": {
"user_id": {
"type": "integer",
"example": 1
},
"role": {
"type": "string",
"example": "admin"
},
"scopes": {
"type": "array",
"items": {
"properties": {
"scope_type": {
"type": "string",
"example": "company"
},
"scope_id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "示例公司"
}
},
"type": "object"
}
},
"resolved_store_ids": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
2,
3
]
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "用户不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"DataScope"
],
"summary": "设置用户数据权限",
"description": "全量替换用户的 scope 绑定，并重建 bitmap",
"operationId": "4ff88235674fa406239c90406f051994",
"parameters": [
{
"name": "id",
"in": "path",
"description": "用户 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"scopes"
],
"properties": {
"scopes": {
"type": "array",
"items": {
"required": [
"scope_type",
"scope_id"
],
"properties": {
"scope_type": {
"type": "string",
"example": "company",
"enum": [
"company",
"platform",
"store"
]
},
"scope_id": {
"type": "integer",
"example": 1
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "数据权限更新成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "数据权限更新成功"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "参数校验失败（无效 scope_type 等）",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "用户不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/platforms": {
"get": {
"tags": [
"Platforms"
],
"summary": "平台列表",
"description": "获取全部平台列表（全局数据，不过滤）",
"operationId": "5ff5cb3822eee3a87c0387f6a5ad4637",
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"developer_id": {
"type": "integer",
"example": 1
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/roles": {
"get": {
"tags": [
"Roles"
],
"summary": "角色列表",
"description": "获取所有角色，包含每个角色的用户数",
"operationId": "9a543d6f94510bc9ca9208afc0b4715c",
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "editor"
},
"users_count": {
"type": "integer",
"example": 5
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/users/{id}/role": {
"put": {
"tags": [
"Roles"
],
"summary": "分配用户角色",
"description": "为指定用户分配角色，administrator 不允许降级自己的角色",
"operationId": "49884e2548d00ed9b195e873b2dd3934",
"parameters": [
{
"name": "id",
"in": "path",
"description": "用户 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"role_id"
],
"properties": {
"role_id": {
"description": "角色 ID",
"type": "integer",
"example": 2
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "角色分配成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "角色分配成功"
},
"data": {
"$ref": "#/components/schemas/User"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "不允许降级自己的管理员角色",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "用户或角色不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/roles/{id}/route-groups": {
"get": {
"tags": [
"Roles"
],
"summary": "查看角色已授权的路由组",
"description": "获取指定角色已授权的路由组列表",
"operationId": "25aba1fb2a9a4cc81e1bf06c716deda9",
"parameters": [
{
"name": "id",
"in": "path",
"description": "角色 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"type": "array",
"items": {
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "角色不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Roles"
],
"summary": "设置角色的路由组授权",
"description": "全量替换指定角色的路由组授权，administrator 角色不允许修改",
"operationId": "1e1f0c23e58bc994ea055407eb469a37",
"parameters": [
{
"name": "id",
"in": "path",
"description": "角色 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"group_ids"
],
"properties": {
"group_ids": {
"type": "array",
"items": {
"type": "integer"
},
"example": [
1,
3,
5
]
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "路由组授权更新成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "路由组授权更新成功"
},
"data": {
"type": "array",
"items": {
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"400": {
"description": "administrator 角色不允许修改或参数错误",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "角色不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/roles/{id}/route-overrides": {
"get": {
"tags": [
"Roles"
],
"summary": "查看角色的路由覆盖",
"description": "获取指定角色的路由覆盖列表，包含路由详情",
"operationId": "7766effa17b431f2bcd67b1f434ee042",
"parameters": [
{
"name": "id",
"in": "path",
"description": "角色 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"role_id": {
"type": "integer"
},
"route_id": {
"type": "integer"
},
"allowed": {
"type": "boolean"
},
"route": {
"type": "object"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "角色不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Roles"
],
"summary": "设置角色的路由覆盖",
"description": "全量替换指定角色的路由覆盖规则，administrator 角色不允许修改",
"operationId": "7ab36e126b6eb4e7631cc7b51b5d2779",
"parameters": [
{
"name": "id",
"in": "path",
"description": "角色 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"overrides"
],
"properties": {
"overrides": {
"type": "array",
"items": {
"required": [
"route_id",
"allowed"
],
"properties": {
"route_id": {
"description": "路由 ID",
"type": "integer",
"example": 12
},
"allowed": {
"description": "是否允许",
"type": "boolean",
"example": false
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "路由覆盖更新成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "路由覆盖更新成功"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer"
},
"role_id": {
"type": "integer"
},
"route_id": {
"type": "integer"
},
"allowed": {
"type": "boolean"
},
"route": {
"type": "object"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"400": {
"description": "route_id 重复、不存在或 administrator 角色不允许修改",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "角色不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/route-groups": {
"get": {
"tags": [
"RouteGroups"
],
"summary": "路由组列表",
"description": "返回所有路由组，包含每组的路由数量",
"operationId": "dc2a90e0b1d08db3762003eac4f93598",
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "user-management"
},
"label": {
"type": "string",
"example": "用户管理",
"nullable": true
},
"description": {
"type": "string",
"example": "用户相关路由",
"nullable": true
},
"sort_order": {
"type": "integer",
"example": 0
},
"routes_count": {
"type": "integer",
"example": 5
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"RouteGroups"
],
"summary": "创建路由组",
"description": "创建路由组",
"operationId": "5796b5d8d366ca24bd7b850510fdc77d",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"example": "user-management",
"maxLength": 100
},
"label": {
"type": "string",
"example": "用户管理",
"nullable": true,
"maxLength": 200
},
"description": {
"type": "string",
"example": "用户相关路由",
"nullable": true
},
"sort_order": {
"type": "integer",
"example": 0,
"default": 0
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "创建成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "创建成功"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "user-management"
},
"label": {
"type": "string",
"example": "用户管理",
"nullable": true
},
"description": {
"type": "string",
"nullable": true
},
"sort_order": {
"type": "integer",
"example": 0
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "参数校验失败或名称重复",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/route-groups/{id}": {
"put": {
"tags": [
"RouteGroups"
],
"summary": "更新路由组",
"description": "更新路由组",
"operationId": "08ab6c0eb639ed8c3c7b2aa5151f3f8b",
"parameters": [
{
"name": "id",
"in": "path",
"description": "路由组 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"type": "string",
"example": "user-management",
"maxLength": 100
},
"label": {
"type": "string",
"example": "用户管理",
"nullable": true,
"maxLength": 200
},
"description": {
"type": "string",
"example": "用户相关路由",
"nullable": true
},
"sort_order": {
"type": "integer",
"example": 0
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "更新成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "更新成功"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "user-management"
},
"label": {
"type": "string",
"example": "用户管理",
"nullable": true
},
"description": {
"type": "string",
"nullable": true
},
"sort_order": {
"type": "integer",
"example": 0
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "参数校验失败或名称重复",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "路由组不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"tags": [
"RouteGroups"
],
"summary": "删除路由组",
"description": "删除路由组，组内路由 group_id 自动设为 NULL，role_route_groups 关联自动级联删除",
"operationId": "2b870b541944a9318469fafc2ad83834",
"parameters": [
{
"name": "id",
"in": "path",
"description": "路由组 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "删除成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "删除成功"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "路由组不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/routes": {
"get": {
"tags": [
"RouteGroups"
],
"summary": "路由列表",
"description": "获取全部路由列表，含分组信息，支持按 group_id、method、path 筛选",
"operationId": "06fcdb734181d39362a999d1599a5e66",
"parameters": [
{
"name": "group_id",
"in": "query",
"description": "路由组 ID，传 0 或 \"ungrouped\" 筛选未分组路由",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "method",
"in": "query",
"description": "HTTP 方法筛选",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "path",
"in": "query",
"description": "路径模糊搜索",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"method": {
"type": "string",
"example": "GET"
},
"path": {
"type": "string",
"example": "/api/v1/users"
},
"group_id": {
"type": "integer",
"example": 1,
"nullable": true
},
"group": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "user-management"
},
"label": {
"type": "string",
"example": "用户管理",
"nullable": true
}
},
"type": "object",
"nullable": true
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/routes/{id}/group": {
"put": {
"tags": [
"RouteGroups"
],
"summary": "分配路由到路由组",
"description": "将路由分配到指定路由组，传 group_id=null 表示从分组中移出",
"operationId": "10daee20cc95a281bc0bc3716df103aa",
"parameters": [
{
"name": "id",
"in": "path",
"description": "路由 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"group_id"
],
"properties": {
"group_id": {
"description": "路由组 ID，传 null 移出分组",
"type": "integer",
"example": 1,
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "分配成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "分配成功"
},
"data": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"method": {
"type": "string",
"example": "GET"
},
"path": {
"type": "string",
"example": "/api/v1/users"
},
"group_id": {
"type": "integer",
"example": 1,
"nullable": true
},
"group": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"name": {
"type": "string",
"example": "user-management"
},
"label": {
"type": "string",
"example": "用户管理",
"nullable": true
}
},
"type": "object",
"nullable": true
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "参数校验失败",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "路由或目标路由组不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/stores": {
"get": {
"tags": [
"Stores"
],
"summary": "店铺列表",
"description": "获取店铺列表，受 scope 过滤，支持 company_id/platform_id 筛选及 name 模糊搜索",
"operationId": "36279ef5f2735b2624e99a82ebc3dccc",
"parameters": [
{
"name": "company_id",
"in": "query",
"description": "按公司 ID 筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "platform_id",
"in": "query",
"description": "按平台 ID 筛选",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "name",
"in": "query",
"description": "按店铺名称模糊搜索",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"company_id": {
"type": "integer",
"example": 1
},
"platform_id": {
"type": "integer",
"example": 1
},
"platform_store_id": {
"type": "string",
"example": "SHOP-001"
},
"name": {
"type": "string",
"example": "my-store"
},
"label": {
"type": "string",
"example": "我的店铺"
},
"enabled": {
"type": "boolean",
"example": true
},
"warehouse_id": {
"type": "integer",
"example": 1
},
"currency_id": {
"type": "integer",
"example": 1
},
"timezone": {
"type": "integer",
"example": 8
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/users": {
"get": {
"tags": [
"Users"
],
"summary": "用户列表",
"description": "获取用户列表，支持分页、按 username/email 模糊搜索、按 status 精确筛选",
"operationId": "4f028975120b69092c0eae73bb36bcac",
"parameters": [
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 15,
"maximum": 100
}
},
{
"name": "username",
"in": "query",
"description": "用户名模糊搜索",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "email",
"in": "query",
"description": "邮箱模糊搜索",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "status",
"in": "query",
"description": "状态筛选（0=禁用，1=启用）",
"required": false,
"schema": {
"type": "integer",
"enum": [
0,
1
]
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/User"
}
},
"total": {
"type": "integer",
"example": 100
},
"page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 15
}
},
"type": "object"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"tags": [
"Users"
],
"summary": "创建用户",
"description": "创建用户",
"operationId": "0b5969ce7b77ccaa0b2e9b551e302980",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"username",
"password",
"email"
],
"properties": {
"username": {
"type": "string",
"example": "new_user",
"maxLength": 20,
"minLength": 3
},
"password": {
"type": "string",
"example": "Pass_1234",
"maxLength": 32,
"minLength": 6
},
"email": {
"type": "string",
"format": "email",
"example": "new@example.com",
"maxLength": 100
},
"status": {
"type": "integer",
"default": 1,
"enum": [
0,
1
]
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "创建成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "创建成功"
},
"data": {
"$ref": "#/components/schemas/User"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "参数校验失败或唯一性冲突",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/users/{id}": {
"get": {
"tags": [
"Users"
],
"summary": "用户详情",
"description": "用户详情",
"operationId": "b0770c8ad8eb11c5493fe9643c657673",
"parameters": [
{
"name": "id",
"in": "path",
"description": "用户 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "获取成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "获取成功"
},
"data": {
"$ref": "#/components/schemas/User"
}
},
"type": "object"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "用户不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"tags": [
"Users"
],
"summary": "更新用户信息",
"description": "更新用户的 username、email 或 ext 字段，不支持修改密码",
"operationId": "c5ee224e653aac218896c93ecc3f9b67",
"parameters": [
{
"name": "id",
"in": "path",
"description": "用户 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"username": {
"type": "string",
"example": "updated_user",
"maxLength": 20,
"minLength": 3
},
"email": {
"type": "string",
"format": "email",
"example": "updated@example.com",
"maxLength": 100
},
"ext": {
"type": "object",
"example": {
"nickname": "Tester"
},
"nullable": true
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "更新成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "更新成功"
},
"data": {
"$ref": "#/components/schemas/User"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "参数校验失败或唯一性冲突",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "用户不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
},
"/users/{id}/status": {
"patch": {
"tags": [
"Users"
],
"summary": "更新用户状态",
"description": "启用或禁用用户",
"operationId": "c1ad72b12757d083cf0aebbf2f3787fd",
"parameters": [
{
"name": "id",
"in": "path",
"description": "用户 ID",
"required": true,
"schema": {
"type": "integer"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"status"
],
"properties": {
"status": {
"description": "0=禁用，1=启用",
"type": "integer",
"enum": [
0,
1
]
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "状态更新成功",
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "状态更新成功"
},
"data": {
"$ref": "#/components/schemas/User"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "参数校验失败",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"401": {
"description": "未认证",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "用户不存在",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
}
},
"components": {
"schemas": {
"Order": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"company_id": {
"type": "integer",
"example": 1
},
"platform_id": {
"type": "integer",
"example": 2
},
"store_id": {
"type": "integer",
"example": 100
},
"order_status_id": {
"type": "integer",
"example": 1
},
"platform_order_id": {
"type": "string",
"example": "ORD-20260101-001"
},
"buyer_user_id": {
"type": "string",
"example": "buyer_123",
"nullable": true
},
"payment_method_id": {
"type": "integer",
"example": 1
},
"presale": {
"type": "boolean",
"example": false
},
"total_amount": {
"type": "number",
"format": "decimal",
"example": 199.99
},
"total_paid": {
"type": "number",
"format": "decimal",
"example": 189.99
},
"total_discount": {
"type": "number",
"format": "decimal",
"example": 10
},
"total_received": {
"type": "number",
"format": "decimal",
"example": 189.99
},
"freight_fee": {
"type": "number",
"format": "decimal",
"example": 0
},
"tax_fee": {
"type": "number",
"format": "decimal",
"example": 0
},
"discount_fee": {
"type": "number",
"format": "decimal",
"example": 10
},
"commission_fee": {
"type": "number",
"format": "decimal",
"example": 5
},
"coupon_amount": {
"type": "number",
"format": "decimal",
"example": 0
},
"voucher_amount": {
"type": "number",
"format": "decimal",
"example": 0
},
"order_type_id": {
"type": "integer",
"example": 1
},
"hash": {
"type": "string",
"example": "a1b2c3d4e5f6..."
},
"raw": {
"description": "平台原始数据",
"type": "object",
"nullable": true
},
"ext": {
"description": "扩展字段",
"type": "object",
"nullable": true
},
"created_date": {
"type": "string",
"format": "date-time"
},
"updated_date": {
"type": "string",
"format": "date-time",
"nullable": true
},
"paid_date": {
"type": "string",
"format": "date-time",
"nullable": true
},
"shipping_date": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"OrderItem": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"company_id": {
"type": "integer",
"example": 1
},
"platform_id": {
"type": "integer",
"example": 2
},
"store_id": {
"type": "integer",
"example": 100
},
"order_id": {
"type": "integer",
"example": 1000
},
"platform_order_id": {
"type": "string",
"example": "ORD-20260101-001"
},
"sub_order_id": {
"type": "string",
"example": "SUB-001",
"nullable": true
},
"sub_order_type_id": {
"type": "integer",
"example": 1
},
"product_id": {
"type": "integer",
"example": 500
},
"platform_product_id": {
"type": "string",
"example": "PROD-001"
},
"product_sku": {
"type": "string",
"example": "SKU-ABC-001",
"nullable": true
},
"product_barcode": {
"type": "string",
"example": "6901234567890",
"nullable": true
},
"unit_price": {
"type": "number",
"format": "decimal",
"example": 49.99
},
"quantity": {
"type": "integer",
"example": 2
},
"discount": {
"type": "number",
"format": "decimal",
"example": 5
},
"total": {
"type": "number",
"format": "decimal",
"example": 94.98
},
"created_date": {
"type": "string",
"format": "date-time"
},
"ext": {
"description": "扩展字段",
"type": "object",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"Product": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"company_id": {
"type": "integer",
"example": 1
},
"platform_id": {
"type": "integer",
"example": 2
},
"store_id": {
"type": "integer",
"example": 100
},
"status_id": {
"type": "integer",
"example": 1
},
"type_id": {
"type": "integer",
"example": 1
},
"platform_item_id": {
"type": "string",
"example": "ITEM-001"
},
"platform_model_id": {
"type": "string",
"example": "MODEL-A",
"nullable": true
},
"name": {
"type": "string",
"example": "iPhone 16 Pro",
"nullable": true
},
"price": {
"type": "number",
"format": "decimal",
"example": 99.99
},
"currency": {
"type": "string",
"example": "CNY"
},
"num": {
"type": "integer",
"example": 100
},
"hash": {
"type": "string",
"example": "a1b2c3d4e5f6..."
},
"raw": {
"description": "平台原始数据",
"type": "object",
"nullable": true
},
"ext": {
"description": "扩展字段",
"type": "object",
"nullable": true
},
"created_date": {
"type": "string",
"format": "date-time",
"nullable": true
},
"updated_date": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"Refund": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"company_id": {
"type": "integer",
"example": 1
},
"platform_id": {
"type": "integer",
"example": 2
},
"store_id": {
"type": "integer",
"example": 100
},
"order_id": {
"type": "integer",
"example": 500,
"nullable": true
},
"platform_order_id": {
"type": "string",
"example": "ORD-20260101-001"
},
"platform_refund_id": {
"type": "string",
"example": "RF-20260115-001"
},
"refund_status_id": {
"type": "integer",
"example": 1
},
"refund_type_id": {
"type": "integer",
"example": 2
},
"reason": {
"type": "string",
"example": "商品质量问题",
"nullable": true
},
"buyer_user_id": {
"type": "string",
"example": "buyer_123",
"nullable": true
},
"refund_amount": {
"type": "number",
"format": "decimal",
"example": 99.99
},
"freight_refund": {
"type": "number",
"format": "decimal",
"example": 10
},
"refund_total": {
"type": "number",
"format": "decimal",
"example": 109.99
},
"currency": {
"type": "string",
"example": "CNY"
},
"hash": {
"type": "string",
"example": "a1b2c3d4e5f6..."
},
"raw": {
"description": "平台原始数据",
"type": "object",
"nullable": true
},
"ext": {
"description": "扩展字段",
"type": "object",
"nullable": true
},
"order_created_date": {
"type": "string",
"format": "date-time",
"nullable": true
},
"order_paid_date": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_date": {
"type": "string",
"format": "date-time"
},
"updated_date": {
"type": "string",
"format": "date-time",
"nullable": true
},
"completed_date": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"RefundItem": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"company_id": {
"type": "integer",
"example": 1
},
"platform_id": {
"type": "integer",
"example": 2
},
"store_id": {
"type": "integer",
"example": 100
},
"refund_id": {
"type": "integer",
"example": 50
},
"platform_parent_refund_id": {
"type": "string",
"example": "PRF-001",
"nullable": true
},
"platform_refund_id": {
"type": "string",
"example": "RF-ITEM-001"
},
"refund_status_id": {
"type": "integer",
"example": 1
},
"refund_type_id": {
"type": "integer",
"example": 2
},
"reason": {
"type": "string",
"example": "商品质量问题",
"nullable": true
},
"currency": {
"type": "string",
"example": "CNY"
},
"buyer_user_id": {
"type": "string",
"example": "buyer_123",
"nullable": true
},
"platform_order_id": {
"type": "string",
"example": "ORD-20260101-001"
},
"platform_sub_order_id": {
"type": "string",
"example": "SUB-001",
"nullable": true
},
"platform_product_id": {
"type": "string",
"example": "PROD-001",
"nullable": true
},
"quantity": {
"type": "integer",
"example": 1
},
"refund_amount": {
"type": "number",
"format": "decimal",
"example": 99.99
},
"raw": {
"description": "平台原始子项数据",
"type": "object",
"nullable": true
},
"ext": {
"description": "扩展字段",
"type": "object",
"nullable": true
},
"order_created_date": {
"type": "string",
"format": "date-time",
"nullable": true
},
"order_paid_date": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_date": {
"type": "string",
"format": "date-time"
},
"updated_date": {
"type": "string",
"format": "date-time",
"nullable": true
},
"completed_date": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"User": {
"properties": {
"id": {
"type": "integer",
"example": 1
},
"username": {
"type": "string",
"example": "user_1234"
},
"email": {
"type": "string",
"example": "user@example.com"
},
"status": {
"type": "integer",
"example": 1
},
"role_id": {
"type": "integer",
"example": 1,
"nullable": true
},
"api_key_enabled": {
"type": "boolean",
"example": false
},
"ext": {
"type": "object",
"example": {
"nickname": "user"
},
"nullable": true
},
"refresh_token_expires_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"ApiResponse": {
"properties": {
"code": {
"type": "integer",
"example": 0
},
"message": {
"type": "string",
"example": "success"
},
"data": {
"type": "object",
"nullable": true
}
},
"type": "object"
},
"PaginatedData": {
"properties": {
"items": {
"type": "array",
"items": {}
},
"total": {
"type": "integer",
"example": 0
},
"page": {
"type": "integer",
"example": 1
},
"per_page": {
"type": "integer",
"example": 15
}
},
"type": "object"
},
"ErrorResponse": {
"properties": {
"code": {
"type": "integer",
"example": 400
},
"message": {
"type": "string",
"example": "Bad request"
},
"data": {
"type": "object",
"nullable": true
}
},
"type": "object"
},
"MqQueueInfo": {
"description": "单个队列的状态信息",
"properties": {
"queue": {
"description": "队列名称",
"type": "string",
"example": "orders.queue"
},
"messages": {
"description": "消息数量（异常时为 N/A）",
"example": 5,
"oneOf": [
{
"type": "integer"
},
{
"type": "string"
}
]
},
"consumers": {
"description": "消费者数量（异常时为 N/A）",
"example": 1,
"oneOf": [
{
"type": "integer"
},
{
"type": "string"
}
]
},
"status": {
"description": "队列状态",
"type": "string",
"example": "active",
"enum": [
"high_load",
"processing",
"active",
"empty",
"error"
]
}
},
"type": "object"
},
"MqQueueStatus": {
"description": "消息队列全量状态",
"properties": {
"business_queues": {
"description": "业务队列列表",
"type": "array",
"items": {
"$ref": "#/components/schemas/MqQueueInfo"
}
},
"retry_queues": {
"description": "重试队列列表",
"type": "array",
"items": {
"$ref": "#/components/schemas/MqQueueInfo"
}
},
"error_queue": {
"$ref": "#/components/schemas/MqQueueInfo"
},
"summary": {
"description": "汇总统计",
"properties": {
"total_messages": {
"description": "消息总数",
"type": "integer",
"example": 7
},
"total_consumers": {
"description": "消费者总数",
"type": "integer",
"example": 1
}
},
"type": "object"
},
"fetched_at": {
"description": "数据获取时间",
"type": "string",
"format": "date-time",
"example": "2026-03-13 12:00:00"
}
},
"type": "object"
update mq controller
2026-03-13 15:01:55 +08:00
},
"FailedMessageList": {
"description": "失败消息列表项",
"properties": {
"id": {
"type": "integer",
"example": 1
},
"error_id": {
"type": "string",
"example": "err_67890abc"
},
"data_type": {
"type": "string",
"example": "order",
"enum": [
"order",
"product",
"refund"
]
},
"platform": {
"type": "string",
"example": "Tmall",
"nullable": true
},
"platform_id": {
"type": "integer",
"example": 1,
"nullable": true
},
"company_id": {
"type": "integer",
"example": 1,
"nullable": true
},
"store_id": {
"type": "integer",
"example": 1,
"nullable": true
},
"error_type": {
"type": "string",
"example": "RuntimeException"
},
"error_message": {
"type": "string",
"example": "Connection refused"
},
"retry_count": {
"type": "integer",
"example": 3
},
"message_id": {
"type": "string",
"example": "msg_12345",
"nullable": true
},
"failed_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
},
"FailedMessageDetail": {
"description": "失败消息详情（含完整错误堆栈和原始消息体）",
"properties": {
"id": {
"type": "integer",
"example": 1
},
"error_id": {
"type": "string",
"example": "err_67890abc"
},
"data_type": {
"type": "string",
"example": "order",
"enum": [
"order",
"product",
"refund"
]
},
"platform": {
"type": "string",
"example": "Tmall",
"nullable": true
},
"platform_id": {
"type": "integer",
"example": 1,
"nullable": true
},
"company_id": {
"type": "integer",
"example": 1,
"nullable": true
},
"store_id": {
"type": "integer",
"example": 1,
"nullable": true
},
"error_type": {
"type": "string",
"example": "RuntimeException"
},
"error_message": {
"type": "string",
"example": "Connection refused"
},
"error_code": {
"type": "integer",
"example": 0
},
"error_trace": {
"description": "完整异常堆栈",
"type": "string"
},
"original_message": {
"description": "原始消息体 JSON",
"type": "object"
},
"retry_count": {
"type": "integer",
"example": 3
},
"message_id": {
"type": "string",
"example": "msg_12345",
"nullable": true
},
"failed_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"type": "object"
add mq controller
2026-03-13 14:50:06 +08:00
}
},
"securitySchemes": {
"bearerAuth": {
"type": "http",
"bearerFormat": "JWT",
"scheme": "bearer"
},
"apiKeyAuth": {
"type": "apiKey",
"name": "X-API-Key",
"in": "header"
}
}
},
"tags": [
update mq controller
2026-03-13 15:01:55 +08:00
{
"name": "Failed Messages",
"description": "失败消息查看"
},
add mq controller
2026-03-13 14:50:06 +08:00
{
"name": "MQ Status",
"description": "消息队列状态监控"
},
{
"name": "Orders",
"description": "订单管理"
},
{
"name": "Order Items",
"description": "订单项管理"
},
{
"name": "Products",
"description": "产品管理"
},
{
"name": "Orders (Raw)",
"description": "订单原始数据"
},
{
"name": "Products (Raw)",
"description": "产品原始数据"
},
{
"name": "Refunds (Raw)",
"description": "退款原始数据"
},
{
"name": "Refund Items (Raw)",
"description": "退款项原始数据"
},
{
"name": "Refunds",
"description": "退款管理"
},
{
"name": "Refund Items",
"description": "退款项管理"
},
{
"name": "ApiKeys",
"description": "API Key 管理"
},
{
"name": "Auth",
"description": "认证与个人信息"
},
{
"name": "Companies",
"description": "公司管理"
},
{
"name": "DataScope",
"description": "用户数据范围管理"
},
{
"name": "Platforms",
"description": "平台管理"
},
{
"name": "Roles",
"description": "角色与授权管理"
},
{
"name": "RouteGroups",
"description": "路由组管理"
},
{
"name": "Stores",
"description": "店铺管理"
},
{
"name": "Users",
"description": "用户管理"
}
]
}
Reference in New Issue Copy Permalink