{
  "openapi": "3.1.0",
  "info": {
    "title": "绘研集 AI 只读接口",
    "version": "1.0.0",
    "description": "测试阶段无需注册的科研绘图、获准开放的避错反例、制作方法、帖子和讨论检索接口。优先读取 preview_url 轻量 JPEG，细节使用 original_image_url 原图；旧图片未补齐预览时 preview_url 为 null。无法看图时使用 text_fallback，须说明未进行视觉检查。完整网站与上传仍需登录。所有 AI 端点只读。"
  },
  "servers": [{"url": "https://scifig-atlas.work"}],
  "paths": {
    "/api/ai/search": {
      "get": {
        "operationId": "searchAtlas",
        "summary": "统一检索优秀作品、获准开放的反例、帖子和讨论",
        "parameters": [
          {"name":"q","in":"query","schema":{"type":"string","maxLength":240},"description":"中文或英文关键词"},
          {"name":"scope","in":"query","schema":{"type":"string","default":"all"},"description":"all 或 artworks,posts,discussions 的逗号分隔组合"},
          {"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":20,"default":10}}
        ],
        "responses": {"200":{"description":"匹配结果；figure_references 同时列出优秀作品与避错反例，分别提供实际存在的轻量预览、原图地址及文字后备资料","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}}}
      }
    },
    "/api/ai/artworks/{id}": {
      "get": {
        "operationId": "getArtwork",
        "summary": "读取公开作品、制作方法和讨论",
        "parameters": [{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],
        "responses": {"200":{"description":"公开作品详情"},"404":{"description":"作品不存在或未公开"}}
      }
    },
    "/api/ai/posts/{id}": {
      "get": {
        "operationId": "getPost",
        "summary": "读取公开帖子及附件信息",
        "parameters": [{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],
        "responses": {"200":{"description":"公开帖子详情"},"404":{"description":"帖子不存在或未公开"}}
      }
    }
  },
  "components": {
    "schemas": {
      "SearchResponse": {
        "type":"object",
        "required":["ok","query","figure_references","count","returned","results","content_policy"],
        "properties": {
          "ok":{"type":"boolean"},
          "query":{"type":"object"},
          "figure_references":{"type":"object","required":["good_examples","negative_examples","negative_count","instruction"],"properties":{"good_examples":{"type":"array","description":"已发布优秀作品；preview_url 为独立轻量 JPEG 或 null，original_image_url 为原图，text_fallback 为作者填写的文字资料；还含许可和引用信息","items":{"type":"object"}},"negative_examples":{"type":"array","description":"管理员启用并获准开放的典型反例；含 preview_url、original_image_url、text_fallback、不合格原因与改进建议","items":{"type":"object"}},"negative_count":{"type":"integer"},"instruction":{"type":"string"}}},
          "count":{"type":"integer"},
          "returned":{"type":"integer"},
          "results":{"type":"array","items":{"type":"object","properties":{"kind":{"enum":["artwork","post","discussion"]},"id":{"type":"string"},"title":{"type":"string"},"why_matched":{"type":"array","items":{"type":"string"}},"detail_url":{"type":"string","format":"uri"},"content_trust":{"enum":["curated","user_submitted"]}}}},
          "content_policy":{"type":"object"}
        }
      }
    }
  }
}