{
  "openapi": "3.1.0",
  "info": {
    "title": "AI 姿势画廊 API",
    "version": "1.0.0",
    "description": "面向 AI Agent 的只读姿势数据库。元数据存储于 D1，图片存储于 R2。完整 Agent 指南见 https://pose.51proxy.org/AGENT_API.md。"
  },
  "servers": [
    { "url": "https://pose.51proxy.org", "description": "生产环境" }
  ],
  "security": [
    { "bearerAuth": [] }
  ],
  "tags": [
    { "name": "Discovery", "description": "发现分类与可用值" },
    { "name": "Poses", "description": "按姿势聚合查询" },
    { "name": "Images", "description": "逐张图片查询与图片文件" },
    { "name": "System", "description": "服务状态" }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "tags": ["System"],
        "summary": "健康检查",
        "security": [],
        "responses": {
          "200": {
            "description": "服务正常",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } }
          }
        }
      }
    },
    "/api/meta": {
      "get": {
        "tags": ["Discovery"],
        "summary": "获取系统、分类、角度和总量",
        "description": "Agent 应首先调用此端点发现有效 system slug、category ID 和 angle value。",
        "responses": {
          "200": {
            "description": "元数据",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaResponse" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/poses": {
      "get": {
        "tags": ["Poses"],
        "summary": "搜索姿势",
        "description": "每条结果代表一个姿势，cover 是当前 angle 对应图片或该姿势第一张图片。",
        "parameters": [
          { "$ref": "#/components/parameters/System" },
          { "$ref": "#/components/parameters/Category" },
          { "$ref": "#/components/parameters/Angle" },
          { "$ref": "#/components/parameters/Query" },
          { "$ref": "#/components/parameters/Page" },
          { "$ref": "#/components/parameters/PoseLimit" }
        ],
        "responses": {
          "200": {
            "description": "分页姿势列表",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoseListResponse" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/images": {
      "get": {
        "tags": ["Images"],
        "summary": "搜索单张图片",
        "description": "每条结果代表一个角度图片。适合按角度筛选或构建图片清单。",
        "parameters": [
          { "$ref": "#/components/parameters/System" },
          { "$ref": "#/components/parameters/Category" },
          { "$ref": "#/components/parameters/Angle" },
          { "$ref": "#/components/parameters/Query" },
          { "$ref": "#/components/parameters/Page" },
          { "$ref": "#/components/parameters/ImageLimit" }
        ],
        "responses": {
          "200": {
            "description": "分页图片列表",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageListResponse" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/pose/{id}": {
      "get": {
        "tags": ["Poses"],
        "summary": "获取姿势详情",
        "description": "返回单个姿势和全部可用角度。ID 应从 /api/poses 获取。",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "description": "姿势 ID，例如 full-sexy_P001", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "姿势详情",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoseDetail" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/thumb/{filename}": {
      "get": {
        "tags": ["Images"],
        "summary": "获取 300×400 JPEG 缩略图",
        "parameters": [
          { "name": "filename", "in": "path", "required": true, "schema": { "type": "string", "example": "full_sexy_P001_front.jpg" } }
        ],
        "responses": {
          "200": { "description": "JPEG 图片", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "image/jpeg": { "schema": { "type": "string", "contentEncoding": "binary" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/img/{filename}": {
      "get": {
        "tags": ["Images"],
        "summary": "获取 900×1200 PNG 原图",
        "parameters": [
          { "name": "filename", "in": "path", "required": true, "schema": { "type": "string", "example": "full_sexy_P001_front.png" } }
        ],
        "responses": {
          "200": { "description": "PNG 图片", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "image/png": { "schema": { "type": "string", "contentEncoding": "binary" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "opaque token", "description": "使用管理员提供的 API Token。" }
    },
    "parameters": {
      "System": { "name": "system", "in": "query", "description": "系统 slug；从 /api/meta 获取", "schema": { "type": "string", "examples": ["full-sexy", "full-standard", "upper-body", "pair"] } },
      "Category": { "name": "category", "in": "query", "description": "分类 ID；从 /api/meta 获取", "schema": { "type": "string", "example": "full-sexy-c05" } },
      "Angle": { "name": "angle", "in": "query", "description": "稳定的角度存储值；显示时使用 angle_zh", "schema": { "type": "string", "enum": ["正面", "上から", "下から", "横", "斜め"] } },
      "Query": { "name": "q", "in": "query", "description": "搜索中文/日文姿势名、姿势编号、ID、分类；最长 120 字符", "schema": { "type": "string", "maxLength": 120 } },
      "Page": { "name": "page", "in": "query", "description": "页码，从 1 开始", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } },
      "PoseLimit": { "name": "limit", "in": "query", "description": "每页姿势数", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 60 } },
      "ImageLimit": { "name": "limit", "in": "query", "description": "每页图片数", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 80 } }
    },
    "responses": {
      "Unauthorized": { "description": "缺少或无效的 Bearer Token", "headers": { "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "NotFound": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "Health": { "type": "object", "required": ["ok", "service"], "properties": { "ok": { "type": "boolean", "const": true }, "service": { "type": "string", "const": "ai-pose-gallery" } } },
      "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "documentation": { "type": "string", "format": "uri" } } },
      "Totals": { "type": "object", "required": ["pose_count", "image_count", "category_count", "system_count"], "properties": { "pose_count": { "type": "integer", "example": 288 }, "image_count": { "type": "integer", "example": 1439 }, "category_count": { "type": "integer", "example": 30 }, "system_count": { "type": "integer", "example": 4 } } },
      "System": { "type": "object", "required": ["slug", "name_zh", "pose_count", "image_count"], "properties": { "slug": { "type": "string", "example": "full-sexy" }, "name_ja": { "type": "string" }, "name_zh": { "type": "string", "example": "全身单人·性感系" }, "sort_order": { "type": "integer" }, "pose_count": { "type": "integer" }, "image_count": { "type": "integer" } } },
      "Category": { "type": "object", "required": ["id", "system_slug", "name_zh", "pose_count", "image_count"], "properties": { "id": { "type": "string", "example": "full-sexy-c05" }, "system_slug": { "type": "string" }, "name_ja": { "type": "string" }, "name_zh": { "type": "string", "example": "站姿" }, "sort_order": { "type": "integer" }, "pose_count": { "type": "integer" }, "image_count": { "type": "integer" } } },
      "AngleMeta": { "type": "object", "required": ["value", "label"], "properties": { "value": { "type": "string", "example": "上から" }, "label": { "type": "string", "example": "俯视" } } },
      "MetaResponse": { "type": "object", "required": ["systems", "categories", "angles", "totals"], "properties": { "systems": { "type": "array", "items": { "$ref": "#/components/schemas/System" } }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }, "angles": { "type": "array", "items": { "$ref": "#/components/schemas/AngleMeta" } }, "totals": { "$ref": "#/components/schemas/Totals" } } },
      "ImageRef": { "type": "object", "required": ["id", "angle", "angle_zh", "thumb_url", "original_url"], "properties": { "id": { "type": "string", "example": "full_sexy_P001_front" }, "angle": { "type": "string", "example": "正面" }, "angle_zh": { "type": "string", "example": "正面" }, "thumb_url": { "type": "string", "example": "/thumb/full_sexy_P001_front.jpg" }, "original_url": { "type": "string", "example": "/img/full_sexy_P001_front.png" } } },
      "Pose": { "type": "object", "required": ["id", "pose_no", "name_zh", "system_slug", "system_zh", "category_id", "category_zh", "image_count", "cover"], "properties": { "id": { "type": "string", "example": "full-sexy_P001" }, "pose_no": { "type": "string", "example": "P001" }, "name_ja": { "type": "string" }, "name_zh": { "type": "string", "example": "S形站姿，胯部向侧顶出" }, "system_slug": { "type": "string" }, "system_ja": { "type": "string" }, "system_zh": { "type": "string" }, "category_id": { "type": "string" }, "category_ja": { "type": "string" }, "category_zh": { "type": "string" }, "image_count": { "type": "integer", "minimum": 1 }, "cover": { "anyOf": [{ "$ref": "#/components/schemas/ImageRef" }, { "type": "null" }] } } },
      "PoseDetail": { "allOf": [{ "$ref": "#/components/schemas/Pose" }, { "type": "object", "required": ["images"], "properties": { "images": { "type": "array", "items": { "$ref": "#/components/schemas/ImageRef" } } } }] },
      "Image": { "allOf": [{ "$ref": "#/components/schemas/ImageRef" }, { "type": "object", "required": ["pose_id", "pose_no", "name_zh", "system_slug", "category_id"], "properties": { "pose_id": { "type": "string" }, "pose_no": { "type": "string" }, "name_ja": { "type": "string" }, "name_zh": { "type": "string" }, "system_slug": { "type": "string" }, "system_ja": { "type": "string" }, "system_zh": { "type": "string" }, "category_id": { "type": "string" }, "category_ja": { "type": "string" }, "category_zh": { "type": "string" } } }] },
      "PoseListResponse": { "type": "object", "required": ["poses", "total", "page", "limit", "has_more"], "properties": { "poses": { "type": "array", "items": { "$ref": "#/components/schemas/Pose" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "has_more": { "type": "boolean" } } },
      "ImageListResponse": { "type": "object", "required": ["images", "total", "page", "limit", "has_more"], "properties": { "images": { "type": "array", "items": { "$ref": "#/components/schemas/Image" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "has_more": { "type": "boolean" } } }
    }
  }
}
