{
  "openapi": "3.0.3",
  "info": {
    "title": "GEO 检测平台公开 API",
    "version": "1.0.0",
    "description": "GEO（生成式引擎优化）检测平台的公开只读接口：读取站点配置与套餐、提交一次网站 GEO 检测并查询其状态与报告。所有端点均为 HTTPS，无需鉴权即可调用。"
  },
  "servers": [
    {
      "url": "https://geowebcheck.com"
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "summary": "服务健康检查",
        "description": "返回 API 与数据库的可用状态，用于探活。",
        "responses": {
          "200": {
            "description": "API 与数据库正常"
          },
          "503": {
            "description": "服务不可用（数据库不可达）"
          }
        }
      }
    },
    "/api/public/site-config": {
      "get": {
        "summary": "站点公开配置",
        "description": "返回站点名称、描述、联系方式等可公开的前台配置信息。",
        "responses": {
          "200": {
            "description": "站点配置信息"
          },
          "500": {
            "description": "服务端错误"
          }
        }
      }
    },
    "/api/public/plan": {
      "get": {
        "summary": "套餐列表",
        "description": "分页返回可用套餐（名称、价格、时长、检测次数等）。",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "每页数量",
            "schema": {
              "type": "integer"
            },
            "example": 20
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "页码",
            "schema": {
              "type": "integer"
            },
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "description": "套餐列表"
          },
          "500": {
            "description": "服务端错误"
          }
        }
      }
    },
    "/api/public/plan/{id}": {
      "get": {
        "summary": "套餐详情",
        "description": "按 ID 返回单个套餐的完整信息。",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "资源主键 ID",
            "schema": {
              "type": "integer"
            },
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "description": "套餐详情"
          },
          "404": {
            "description": "套餐不存在"
          },
          "500": {
            "description": "服务端错误"
          }
        }
      }
    },
    "/api/detection": {
      "post": {
        "summary": "提交一次 GEO 检测",
        "description": "对给定域名发起 10 维度 GEO 检测，返回检测报告记录（含 id）。任务异步执行，完成后可通过状态/报告端点查询。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domain"
                ],
                "properties": {
                  "domain": {
                    "type": "string",
                    "description": "目标站点 URL，例如 https://example.com",
                    "example": "https://example.com"
                  },
                  "keyword": {
                    "type": "string",
                    "description": "可选检测关键词",
                    "example": "GEO检测"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "已创建检测任务，返回报告记录（含 id）"
          },
          "422": {
            "description": "参数校验失败、域名被拒或重复提交"
          },
          "429": {
            "description": "触发限流或配额不足"
          },
          "500": {
            "description": "服务端错误"
          }
        }
      }
    },
    "/api/detection/{id}/status": {
      "get": {
        "summary": "查询检测状态",
        "description": "返回指定检测任务的执行状态（待处理/进行中/已完成/失败）。",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "资源主键 ID",
            "schema": {
              "type": "integer"
            },
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "description": "检测状态"
          },
          "404": {
            "description": "报告不存在"
          },
          "500": {
            "description": "服务端错误"
          }
        }
      }
    },
    "/api/detection/{id}/report": {
      "get": {
        "summary": "获取检测报告",
        "description": "返回已完成检测的完整报告（10 维度评分、问题清单、AI 引用统计与修复建议）。",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "资源主键 ID",
            "schema": {
              "type": "integer"
            },
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "description": "检测报告"
          },
          "403": {
            "description": "无权查看该报告"
          },
          "404": {
            "description": "报告不存在"
          },
          "500": {
            "description": "服务端错误"
          }
        }
      }
    }
  }
}