{
  "openapi": "3.1.0",
  "info": {
    "title": "产业前沿资讯发布 API",
    "version": "1.0.0",
    "description": "使用账户 API Key 创建或更新资讯。hashId 是调用方定义的唯一标识；isUpdate=true 时重新提交同一 hashId 会更新原资讯。正文使用 HTML，服务端会清洗不安全内容。",
    "contact": {
      "name": "产业前沿编辑部",
      "url": "/api-docs"
    }
  },
  "servers": [
    {
      "url": "/api/v1"
    }
  ],
  "tags": [
    { "name": "Articles", "description": "资讯创建、更新与查询" },
    { "name": "Taxonomy", "description": "分类和合集发现" }
  ],
  "security": [
    { "ApiKeyAuth": [] }
  ],
  "paths": {
    "/articles": {
      "post": {
        "tags": ["Articles"],
        "summary": "创建或更新资讯",
        "operationId": "upsertArticle",
        "description": "默认 isUpdate=false：hashId 不存在时创建，已存在时返回 409。设为 true 时更新当前账户已有的资讯；hashId 属于其他账户时返回 409。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ArticleInput" },
              "examples": {
                "create": {
                  "summary": "创建资讯",
                  "value": {
                    "hashId": "industry-2026-11-17-001",
                    "isUpdate": false,
                    "title": "固态电池中试线的工程化拐点",
                    "summary": "从材料体系到制造良率，产业正在跨过第一道门槛。",
                    "contentHtml": "<h2>从实验室到中试线</h2><p>正文内容……</p>",
                    "coverImage": "https://example.com/cover.jpg",
                    "author": "产业研究部",
                    "publishedAt": "2026-11-17T10:00:00+08:00",
                    "categorySlug": "industry-news",
                    "collectionId": 4,
                    "collectionOrder": 10,
                    "sourceName": "公开资料整理",
                    "sourceUrl": "https://example.com/source",
                    "status": "published",
                    "isFeatured": false
                  }
                },
                "update": {
                  "summary": "更新资讯",
                  "value": {
                    "hashId": "industry-2026-11-17-001",
                    "isUpdate": true,
                    "title": "固态电池中试线的工程化拐点（更新）",
                    "summary": "补充最新中试线进展与良率数据。",
                    "contentHtml": "<p>更新后的正文……</p>"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "创建成功",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ArticleResponse" } }
            }
          },
          "200": {
            "description": "更新成功",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ArticleResponse" } }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "415": { "$ref": "#/components/responses/UnsupportedMedia" },
          "422": { "$ref": "#/components/responses/ValidationError" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/articles/{hashId}": {
      "get": {
        "tags": ["Articles"],
        "summary": "查询当前账户的资讯",
        "operationId": "getArticleByHash",
        "parameters": [
          {
            "name": "hashId",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "maxLength": 128 }
          }
        ],
        "responses": {
          "200": {
            "description": "查询成功",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ArticleResponse" } }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/categories": {
      "get": {
        "tags": ["Taxonomy"],
        "summary": "列出分类",
        "operationId": "listCategories",
        "responses": {
          "200": {
            "description": "分类列表",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean", "const": true },
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Category" }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/collections": {
      "get": {
        "tags": ["Taxonomy"],
        "summary": "列出合集",
        "operationId": "listCollections",
        "responses": {
          "200": {
            "description": "合集列表",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean", "const": true },
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Collection" }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "在后台「API Key」页面创建。格式：Authorization: Bearer cyk_..."
      }
    },
    "schemas": {
      "ArticleInput": {
        "type": "object",
        "required": ["hashId"],
        "properties": {
          "hashId": {
            "type": "string",
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
            "description": "调用方定义的资讯唯一标识。"
          },
          "isUpdate": {
            "type": "boolean",
            "default": false,
            "description": "hashId 已存在时必须为 true 才会更新。"
          },
          "title": {
            "type": "string",
            "minLength": 2,
            "maxLength": 120,
            "description": "创建时必填；更新时可省略以保留原值。"
          },
          "summary": {
            "type": "string",
            "minLength": 10,
            "maxLength": 300,
            "description": "创建时必填；更新时可省略以保留原值。"
          },
          "contentHtml": {
            "type": "string",
            "maxLength": 1048576,
            "description": "富文本 HTML。创建时必填；服务端会清洗不安全标签。"
          },
          "coverImage": {
            "type": ["string", "null"],
            "description": "封面 URL、/uploads/... 或 /images/...；传 null/空字符串清空。"
          },
          "author": {
            "type": ["string", "null"],
            "maxLength": 80,
            "description": "作者署名；不填时显示 API Key 所属账户名称。"
          },
          "publishedAt": {
            "type": "string",
            "format": "date-time",
            "description": "发布时间，ISO 8601。"
          },
          "categoryId": {
            "type": "integer",
            "minimum": 1,
            "description": "分类 ID；和 categorySlug 二选一。"
          },
          "categorySlug": {
            "type": "string",
            "description": "分类 slug，例如 industry-news、tech-docs、insights。"
          },
          "collectionId": {
            "type": ["integer", "null"],
            "description": "合集 ID；null 表示不归入合集。"
          },
          "collectionOrder": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9999,
            "default": 0
          },
          "sourceName": {
            "type": "string",
            "maxLength": 80
          },
          "sourceUrl": {
            "type": "string",
            "format": "uri",
            "description": "来源链接，仅 http/https。"
          },
          "status": {
            "type": "string",
            "enum": ["published", "draft"],
            "default": "published"
          },
          "isFeatured": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "ArticleResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean", "const": true },
          "data": {
            "type": "object",
            "properties": {
              "action": { "type": "string", "enum": ["created", "updated", "fetched"] },
              "id": { "type": "integer" },
              "hashId": { "type": "string" },
              "title": { "type": "string" },
              "summary": { "type": "string" },
              "status": { "type": "string", "enum": ["published", "draft"] },
              "author": { "type": "string" },
              "category": { "$ref": "#/components/schemas/Category" },
              "collection": {
                "oneOf": [
                  { "$ref": "#/components/schemas/Collection" },
                  { "type": "null" }
                ]
              },
              "collectionOrder": { "type": "integer" },
              "coverImage": { "type": "string" },
              "sourceName": { "type": "string" },
              "sourceUrl": { "type": "string" },
              "publishedAt": { "type": ["string", "null"], "format": "date-time" },
              "createdAt": { "type": "string", "format": "date-time" },
              "updatedAt": { "type": "string", "format": "date-time" },
              "url": { "type": "string", "format": "uri" },
              "contentHtml": { "type": "string" }
            }
          }
        }
      },
      "Category": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "description": { "type": "string" },
          "color": { "type": "string" },
          "publishedCount": { "type": "integer" },
          "isSystem": { "type": "boolean" }
        }
      },
      "Collection": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "coverImage": { "type": "string" },
          "publishedCount": { "type": "integer" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean", "const": false },
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" },
              "fields": {
                "type": "object",
                "additionalProperties": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "API Key 缺失、无效、被禁用或账户被停用",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
        }
      },
      "NotFound": {
        "description": "资讯或 API 路径不存在",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
        }
      },
      "Conflict": {
        "description": "hashId 冲突或归属冲突",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
        }
      },
      "UnsupportedMedia": {
        "description": "必须使用 application/json",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
        }
      },
      "ValidationError": {
        "description": "字段校验失败",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
        }
      },
      "InternalError": {
        "description": "服务器内部错误",
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }
        }
      }
    }
  }
}
