{
  "openapi": "3.1.0",
  "info": {
    "title": "明膳 CMS API",
    "version": "1.3.0",
    "description": "首页素材和官网文章直接联动。后台选择素材、保存草稿、发布，官网服务端即时读取发布版本。管理写入需要会话及 CSRF。"
  },
  "servers": [
    {
      "url": "https://api.mingshanhealth.com"
    }
  ],
  "tags": [
    {
      "name": "Health"
    },
    {
      "name": "Authentication"
    },
    {
      "name": "Users"
    },
    {
      "name": "Content"
    },
    {
      "name": "Media"
    },
    {
      "name": "Audit"
    },
    {
      "name": "Public"
    }
  ],
  "paths": {
    "/healthz": {
      "get": {
        "tags": [
          "Health"
        ],
        "summary": "API 与数据库健康检查",
        "responses": {
          "200": {
            "description": "服务正常",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/login": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "登录后台",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoginRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "登录成功并设置会话 Cookie",
            "headers": {
              "Set-Cookie": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LoginResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/auth/logout": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "退出登录",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Ok"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/auth/me": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "summary": "读取当前用户和 CSRF Token",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "当前会话",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/auth/change-password": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "修改自己的密码",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChangePasswordRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Ok"
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          }
        },
        "description": "成功后所有已有会话失效，必须重新登录。"
      }
    },
    "/api/stats": {
      "get": {
        "tags": [
          "Audit"
        ],
        "summary": "读取后台概览统计",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "统计数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatsResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/users": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "账号列表",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "账号列表",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/User"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "post": {
        "tags": [
          "Users"
        ],
        "summary": "新增后台账号",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateUserRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "创建成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserItemResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/users/{user_id}": {
      "patch": {
        "tags": [
          "Users"
        ],
        "summary": "启停账号或重置密码，仅 admin",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/UserId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateUserRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Ok"
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/content": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "内容列表",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Kind"
          },
          {
            "$ref": "#/components/parameters/Status"
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100000,
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 120
            },
            "description": "标题或 Slug 搜索"
          }
        ],
        "responses": {
          "200": {
            "description": "内容列表",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ContentSummary"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          }
        },
        "description": "分页响应包含 items、total、page、page_size。"
      },
      "post": {
        "tags": [
          "Content"
        ],
        "summary": "新增内容草稿",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContentWrite"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "创建成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentItemResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/content/{item_id}": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "读取单条完整内容",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ItemId"
          }
        ],
        "responses": {
          "200": {
            "description": "内容详情",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentItemResponse"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "put": {
        "tags": [
          "Content"
        ],
        "summary": "完整更新内容",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ItemId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContentUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "更新成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentItemResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "description": "版本冲突，请重新读取并合并编辑"
          },
          "428": {
            "description": "缺少 version"
          }
        },
        "description": "保存编辑版本，不改变公开发布快照。已发布过的 Slug 固定。"
      }
    },
    "/api/content/{item_id}/status": {
      "post": {
        "tags": [
          "Content"
        ],
        "summary": "修改内容发布状态",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ItemId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "status",
                  "version"
                ],
                "properties": {
                  "status": {
                    "$ref": "#/components/schemas/ContentStatus"
                  },
                  "version": {
                    "type": "integer",
                    "minimum": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "状态已更新"
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "description": "版本冲突，请重新读取并合并编辑"
          },
          "428": {
            "description": "缺少 version"
          }
        },
        "description": "article 发布后同步到官网 /news 和 /news/{slug}，下线后公开详情404；page/site_info仍为通用接口内容。"
      }
    },
    "/api/media": {
      "get": {
        "tags": [
          "Media"
        ],
        "summary": "媒体列表",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "媒体列表",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Media"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100000,
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "archived",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "image",
                "video"
              ]
            },
            "description": "筛选图片或视频"
          }
        ],
        "description": "分页响应包含 items、total、page、page_size。"
      },
      "post": {
        "tags": [
          "Media"
        ],
        "summary": "上传图片／常用文件（20MB）或 H.264 MP4 视频（100MB、120 秒、最大 4K）",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "上传成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "item": {
                      "$ref": "#/components/schemas/Media"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/media/{media_id}": {
      "delete": {
        "tags": [
          "Media"
        ],
        "summary": "归档媒体，保留已有文件链接",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "name": "media_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Ok"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/media/{media_id}/optimize": {
      "post": {
        "tags": [
          "Media"
        ],
        "summary": "按识别用途生成统一桌面图和手机适配图",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "name": "media_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "优化完成",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "item": {
                      "$ref": "#/components/schemas/Media"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/homepage-modules": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "读取首页模块配置",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "首页模块列表"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/homepage-modules/{module_key}": {
      "patch": {
        "tags": [
          "Content"
        ],
        "summary": "切换首页模块展示状态",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "name": "module_key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "video_hero",
                "static_hero"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "is_visible"
                ],
                "properties": {
                  "is_visible": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "状态已更新"
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/audit": {
      "get": {
        "tags": [
          "Audit"
        ],
        "summary": "最近 200 条审计记录，仅 admin",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "审计记录列表"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/public/content": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "已发布内容列表",
        "parameters": [
          {
            "$ref": "#/components/parameters/Kind"
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100000,
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 120
            },
            "description": "站内文章搜索（标题与摘要）"
          }
        ],
        "responses": {
          "200": {
            "description": "公开内容列表",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PublicContentSummary"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "description": "分页响应包含 items、total、page、page_size。"
      }
    },
    "/public/content/{slug}": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "通过 slug 读取已发布内容",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "公开内容详情",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContentItemResponse"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/public/homepage-modules": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "读取官网首页模块展示状态",
        "responses": {
          "200": {
            "description": "首页模块状态"
          }
        }
      }
    },
    "/api/content/validate": {
      "post": {
        "tags": [
          "Content"
        ],
        "summary": "校验内容，不保存或发布",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContentWrite"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "ok=true, dry_run=true, item 为清理后的内容"
          },
          "400": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/content/{item_id}/revisions": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "最近 30 个历史版本",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ItemId"
          }
        ],
        "responses": {
          "200": {
            "description": "items: version, snapshot, created_at"
          }
        }
      }
    },
    "/api/media/{media_id}/restore": {
      "post": {
        "tags": [
          "Media"
        ],
        "summary": "恢复归档文件",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "name": "media_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Ok"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/system": {
      "get": {
        "tags": [
          "Health"
        ],
        "summary": "后台运行状态，仅 admin",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "服务版本、数据库连接、上传权限、待改密账号数"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/site-home": {
      "get": {
        "tags": [
          "Content"
        ],
        "summary": "读取首页编辑值、发布值、版本与字段定义",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "item: draft,published,version,published_version,updated_at,published_at；fields: key,label,kind,group"
          }
        }
      },
      "put": {
        "tags": [
          "Content"
        ],
        "summary": "保存首页素材草稿，不影响官网",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "version",
                  "values"
                ],
                "properties": {
                  "version": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "values": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    },
                    "description": "GET fields 列出的全部字段；媒体使用素材库或现有官网素材地址，video_mobile 可空"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "更新后的 item"
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "428": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/site-home/publish": {
      "post": {
        "tags": [
          "Content"
        ],
        "summary": "发布首页草稿，官网即时读取新版本",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "version"
                ],
                "properties": {
                  "version": {
                    "type": "integer",
                    "minimum": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "发布成功，返回 item"
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "428": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/public/site-home": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "仅查询已发布首页素材",
        "responses": {
          "200": {
            "description": "item:发布值，version:发布版本"
          }
        }
      }
    },
    "/api/products": {
      "get": {
        "tags": [
          "Products"
        ],
        "summary": "产品草稿与上架状态列表",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "enum": [
                "draft",
                "published",
                "offline"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "items,total,page,page_size；每项包含 version 和 published_snapshot"
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "428": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "post": {
        "tags": [
          "Products"
        ],
        "summary": "新增产品草稿",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "slug": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 140
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 160
                  },
                  "subtitle": {
                    "type": "string",
                    "maxLength": 240
                  },
                  "summary": {
                    "type": "string",
                    "maxLength": 2000
                  },
                  "body": {
                    "type": "string",
                    "maxLength": 100000,
                    "description": "经服务端清理的 HTML 详情"
                  },
                  "image_url": {
                    "type": "string",
                    "description": "素材库图片或现有官网图片地址；服务端校验存在性"
                  },
                  "sort_order": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 100000,
                    "default": 100
                  }
                },
                "required": [
                  "slug",
                  "name",
                  "image_url"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "item：含 id、version 的产品草稿"
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "428": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/products/{product_id}": {
      "get": {
        "tags": [
          "Products"
        ],
        "summary": "读取单个产品及发布快照",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "product_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "item"
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "428": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "put": {
        "tags": [
          "Products"
        ],
        "summary": "保存产品草稿，发布前不改变线上内容或顺序",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "name": "product_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "slug": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 140
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 160
                  },
                  "subtitle": {
                    "type": "string",
                    "maxLength": 240
                  },
                  "summary": {
                    "type": "string",
                    "maxLength": 2000
                  },
                  "body": {
                    "type": "string",
                    "maxLength": 100000,
                    "description": "经服务端清理的 HTML 详情"
                  },
                  "image_url": {
                    "type": "string",
                    "description": "素材库图片或现有官网图片地址；服务端校验存在性"
                  },
                  "sort_order": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 100000,
                    "default": 100
                  },
                  "version": {
                    "type": "integer",
                    "minimum": 1
                  }
                },
                "required": [
                  "slug",
                  "name",
                  "image_url",
                  "version"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "item：version 增加，已发布地址不可修改"
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "428": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/products/{product_id}/status": {
      "post": {
        "tags": [
          "Products"
        ],
        "summary": "产品上架／下架，同步首页、产品中心、详情、搜索",
        "security": [
          {
            "sessionCookie": [],
            "csrfToken": []
          }
        ],
        "parameters": [
          {
            "name": "product_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "version": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "draft",
                      "published",
                      "offline"
                    ]
                  }
                },
                "required": [
                  "version",
                  "status"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "item；上架时复制快照并使用该快照排序，下架后公开详情404"
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "428": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/public/products": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "已上架产品列表，按已发布顺序排列",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          }
        ],
        "responses": {
          "200": {
            "description": "items,total,page,page_size；仅公开快照，不含 body"
          }
        }
      }
    },
    "/public/products/{slug}": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "已上架产品详情",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "item：包含产品正文"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "sessionCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "mingshan_admin_session",
        "description": "登录接口设置的 HttpOnly 会话 Cookie"
      },
      "csrfToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-CSRF-Token",
        "description": "登录或 /api/auth/me 返回的 csrf_token"
      }
    },
    "parameters": {
      "UserId": {
        "name": "user_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "integer"
        }
      },
      "ItemId": {
        "name": "item_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "integer"
        }
      },
      "Kind": {
        "name": "kind",
        "in": "query",
        "required": false,
        "schema": {
          "$ref": "#/components/schemas/ContentKind"
        }
      },
      "Status": {
        "name": "status",
        "in": "query",
        "required": false,
        "schema": {
          "$ref": "#/components/schemas/ContentStatus"
        }
      }
    },
    "responses": {
      "Ok": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/OkResponse"
            }
          }
        }
      },
      "Error": {
        "description": "错误响应",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "OkResponse": {
        "type": "object",
        "required": [
          "ok"
        ],
        "properties": {
          "ok": {
            "const": true
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "ok",
          "error"
        ],
        "properties": {
          "ok": {
            "const": false
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "HealthResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "const": true
          },
          "service": {
            "const": "mingshan-cms-api"
          }
        }
      },
      "LoginRequest": {
        "type": "object",
        "required": [
          "username",
          "password"
        ],
        "properties": {
          "username": {
            "type": "string",
            "minLength": 3,
            "maxLength": 32
          },
          "password": {
            "type": "string",
            "format": "password"
          }
        }
      },
      "LoginResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "const": true
          },
          "user": {
            "$ref": "#/components/schemas/User"
          },
          "csrf_token": {
            "type": "string"
          }
        }
      },
      "MeResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "const": true
          },
          "user": {
            "$ref": "#/components/schemas/User"
          },
          "csrf_token": {
            "type": "string"
          }
        }
      },
      "ChangePasswordRequest": {
        "type": "object",
        "required": [
          "current_password",
          "new_password"
        ],
        "properties": {
          "current_password": {
            "type": "string",
            "format": "password"
          },
          "new_password": {
            "type": "string",
            "format": "password",
            "minLength": 12,
            "maxLength": 128,
            "description": "同时包含字母和数字，禁止常见弱密码"
          }
        }
      },
      "CreateUserRequest": {
        "type": "object",
        "required": [
          "username",
          "password",
          "role"
        ],
        "properties": {
          "username": {
            "type": "string",
            "pattern": "^[A-Za-z][A-Za-z0-9_]{2,31}$"
          },
          "password": {
            "type": "string",
            "format": "password",
            "minLength": 12,
            "maxLength": 128,
            "description": "同时包含字母和数字，禁止常见弱密码"
          },
          "role": {
            "$ref": "#/components/schemas/UserRole"
          }
        }
      },
      "UpdateUserRequest": {
        "type": "object",
        "properties": {
          "is_active": {
            "type": "boolean"
          },
          "password": {
            "type": "string",
            "format": "password",
            "minLength": 12,
            "maxLength": 128,
            "description": "同时包含字母和数字，禁止常见弱密码"
          }
        }
      },
      "UserRole": {
        "type": "string",
        "enum": [
          "admin",
          "ops"
        ]
      },
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "username": {
            "type": "string"
          },
          "role": {
            "$ref": "#/components/schemas/UserRole"
          },
          "is_active": {
            "type": "boolean"
          },
          "last_login_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "UserItemResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "const": true
          },
          "item": {
            "$ref": "#/components/schemas/User"
          }
        }
      },
      "ContentKind": {
        "type": "string",
        "enum": [
          "site_info",
          "page",
          "article"
        ]
      },
      "ContentStatus": {
        "type": "string",
        "enum": [
          "draft",
          "published",
          "offline"
        ]
      },
      "ContentWrite": {
        "type": "object",
        "required": [
          "kind",
          "slug",
          "title"
        ],
        "properties": {
          "kind": {
            "$ref": "#/components/schemas/ContentKind"
          },
          "slug": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9-]{1,139}$"
          },
          "title": {
            "type": "string",
            "maxLength": 240
          },
          "summary": {
            "type": "string"
          },
          "body": {
            "type": "string"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "ContentSummary": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ContentWrite"
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "status": {
                "$ref": "#/components/schemas/ContentStatus"
              },
              "published_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "created_at": {
                "type": "string",
                "format": "date-time"
              },
              "updated_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          {
            "type": "object",
            "properties": {
              "version": {
                "type": "integer",
                "minimum": 1
              }
            }
          }
        ]
      },
      "ContentItem": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ContentSummary"
          },
          {
            "type": "object",
            "properties": {
              "author_id": {
                "type": [
                  "integer",
                  "null"
                ]
              }
            }
          }
        ]
      },
      "ContentItemResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "const": true
          },
          "item": {
            "$ref": "#/components/schemas/ContentItem"
          }
        }
      },
      "PublicContentSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "kind": {
            "$ref": "#/components/schemas/ContentKind"
          },
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "metadata": {
            "type": "object"
          },
          "published_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Media": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "original_name": {
            "type": "string"
          },
          "stored_name": {
            "type": "string"
          },
          "mime_type": {
            "type": "string"
          },
          "extension": {
            "type": "string"
          },
          "size_bytes": {
            "type": "integer"
          },
          "public_url": {
            "type": "string",
            "format": "uri"
          },
          "width_px": {
            "type": [
              "integer",
              "null"
            ]
          },
          "height_px": {
            "type": [
              "integer",
              "null"
            ]
          },
          "aspect_ratio": {
            "type": [
              "number",
              "null"
            ]
          },
          "detected_role": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "desktop_banner",
              "landscape_content",
              "square_content",
              "product_portrait",
              "mobile_story",
              null
            ]
          },
          "optimized_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "mobile_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "optimization_status": {
            "type": "string",
            "enum": [
              "original",
              "optimized"
            ]
          },
          "uploaded_by": {
            "type": [
              "integer",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "StatsResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "const": true
          },
          "content": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "media": {
            "type": "integer"
          },
          "users": {
            "type": "integer"
          }
        }
      },
      "ContentUpdate": {
        "type": "object",
        "required": [
          "kind",
          "slug",
          "title",
          "version"
        ],
        "properties": {
          "kind": {
            "$ref": "#/components/schemas/ContentKind"
          },
          "slug": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9-]{1,139}$"
          },
          "title": {
            "type": "string",
            "maxLength": 240
          },
          "summary": {
            "type": "string"
          },
          "body": {
            "type": "string"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "version": {
            "type": "integer",
            "minimum": 1
          }
        }
      }
    }
  }
}
