openapi.yaml

openapi: 3.1.0
info:
  title: 鉴微 Jianwei API
  description: |
    「鉴微」AI 技术追踪与深度解析知识库 后端 API（FastAPI）。

    四大模块：
    - **auth** 认证鉴权（注册/登录/RSA 公钥/当前用户）
    - **feed** AI 前沿资讯流（见微）— 6h 定时，Redis 环形列表最新 50 条
    - **analyze / tasks** 开源项目深度解剖（知著）+ 技术站点熔炼炉（重构）— 异步任务 + SSE 进度
    - **search / chat / kb** 智能技术知识库（鉴真）— 语义搜索 + RAG 问答 + 文档管理

    鉴权：除 register/login/pubkey/health 外，均需 `Authorization: Bearer <JWT>`。

    SSE 端点（`/api/tasks/{id}/stream`、`/api/chat`）返回 `text/event-stream`，帧格式见各端点 description。
  version: 1.0.0

servers:
  - url: https://jianwei.example.com
    description: 生产
  - url: http://localhost:8000
    description: 本地

security:
  - bearerJWT: []

tags:
  - name: auth
    description: 认证鉴权
  - name: feed
    description: AI 前沿资讯流（见微）
  - name: analyze
    description: GitHub / 站点 深度解析（知著 / 重构）
  - name: tasks
    description: 异步任务查询与 SSE 进度
  - name: search
    description: 全局语义搜索
  - name: chat
    description: RAG 跨文档问答（SSE）
  - name: kb
    description: 知识库管理（文件夹 / 文档 / 配额）
  - name: health
    description: 健康检查

paths:
  # ============================ auth ============================
  /api/auth/register:
    post:
      tags: [auth]
      summary: 注册
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RegisterIn' }
      responses:
        '201':
          description: 注册成功，返回访问令牌
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TokenOut' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationError' }

  /api/auth/login:
    post:
      tags: [auth]
      summary: 登录
      description: password 可为明文，或前端用 RSA 公钥加密的密文（此时 enc=true）。
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/LoginIn' }
      responses:
        '200':
          description: 登录成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TokenOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '422': { $ref: '#/components/responses/ValidationError' }

  /api/auth/pubkey:
    get:
      tags: [auth]
      summary: 获取登录密码 RSA 加密公钥
      description: 前端用此公钥加密密码后以 enc=true 提交登录，避免明文传输。
      security: []
      responses:
        '200':
          description: PEM 格式 RSA 公钥
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PubKeyOut' }

  /api/auth/me:
    get:
      tags: [auth]
      summary: 获取当前登录用户
      responses:
        '200':
          description: 当前用户信息
          content:
            application/json:
              schema: { $ref: '#/components/schemas/UserOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }

  # ============================ feed ============================
  /api/feed:
    get:
      tags: [feed]
      summary: 获取资讯流（最新 50 条，读 Redis 环形列表）
      parameters:
        - name: limit
          in: query
          required: false
          schema: { type: integer, minimum: 1, maximum: 50, default: 50 }
      responses:
        '200':
          description: 资讯列表（时间倒序）
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FeedListOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }

  /api/feed/refresh:
    post:
      tags: [feed]
      summary: 手动触发资讯刷新（异步）
      description: 复用 6h 定时同一 Celery 任务；建议限流并仅授权用户可手动触发。
      responses:
        '202':
          description: 已下发刷新任务
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TaskCreatedOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /api/feed/{id}/favorite:
    post:
      tags: [feed]
      summary: 收藏资讯并入库（进 Qdrant，不占解析配额）
      parameters:
        - $ref: '#/components/parameters/FeedId'
      responses:
        '200':
          description: 已创建知识库文档并触发入库
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FavoriteOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402':
          description: 配额超限（文档数 / 容量）
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Msg' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409':
          description: 已收藏（返回既有文档）
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FavoriteOut' }

  # ============================ analyze ============================
  /api/analyze/github:
    post:
      tags: [analyze]
      summary: GitHub 项目深度解剖（异步，返回 task_id）
      description: 基于 GraphQL 拉档案/README/依赖/目录树，reasoning 档生成万字报告并入库。耗时 3-5min，经 SSE 跟进。
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/GithubAnalyzeIn' }
      responses:
        '202':
          description: 任务已创建
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TaskCreatedOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402':
          description: 解析次数配额超限（free 版每月 3 次）
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Msg' }
        '422': { $ref: '#/components/responses/ValidationError' }

  /api/analyze/site:
    post:
      tags: [analyze]
      summary: 技术站点熔炼为 MD/PPT（异步，返回 task_id）
      description: BFS 爬取（≤3 层）+ 正文抽取 → 生成层级 MD 或 reveal.js/PPTX。耗时 3-5min。
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SiteAnalyzeIn' }
      responses:
        '202':
          description: 任务已创建
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TaskCreatedOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402':
          description: 解析次数配额超限
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Msg' }
        '422': { $ref: '#/components/responses/ValidationError' }

  # ============================ tasks ============================
  /api/tasks:
    get:
      tags: [tasks]
      summary: 当前租户的任务列表
      parameters:
        - name: type
          in: query
          required: false
          schema: { type: string, enum: [github, site, ingest, feed] }
        - name: status
          in: query
          required: false
          schema: { type: string, enum: [pending, running, success, failed] }
        - name: limit
          in: query
          required: false
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
      responses:
        '200':
          description: 任务列表
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TaskListOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }

  /api/tasks/{id}:
    get:
      tags: [tasks]
      summary: 单个任务详情（轮询进度）
      parameters:
        - $ref: '#/components/parameters/TaskId'
      responses:
        '200':
          description: 任务详情
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TaskOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /api/tasks/{id}/stream:
    get:
      tags: [tasks]
      summary: 任务进度 SSE 流
      description: |
        返回 `text/event-stream`。每个事件 `data:` 为一个 JSON：
        ```
        data: {"type":"progress","stage":"抓取","progress":20,"status":"running"}
        data: {"type":"progress","stage":"撰写","progress":70,"status":"running"}
        data: {"type":"done","status":"success","result_doc_id":"<doc_id>"}
        data: {"type":"error","status":"failed","error":"<原因>"}
        ```
        帧类型 `type` ∈ `progress | done | error`。`stage` 取值如 抓取/解析/撰写/入库。
      parameters:
        - $ref: '#/components/parameters/TaskId'
      responses:
        '200':
          description: SSE 进度事件流
          content:
            text/event-stream:
              schema: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  # ============================ search ============================
  /api/search:
    get:
      tags: [search]
      summary: 全局语义搜索（向量召回 + 重排，< 1s）
      parameters:
        - name: q
          in: query
          required: true
          description: 自然语言查询
          schema: { type: string, minLength: 1 }
        - name: scope
          in: query
          required: false
          schema: { type: string, enum: [all, folder, tag], default: all }
        - name: folder_id
          in: query
          required: false
          schema: { type: string }
        - name: tag
          in: query
          required: false
          schema: { type: string }
        - name: topk
          in: query
          required: false
          schema: { type: integer, minimum: 1, maximum: 50, default: 8 }
      responses:
        '200':
          description: 命中结果（按相关性降序，含高亮片段）
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SearchOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }

  # ============================ chat ============================
  /api/chat:
    post:
      tags: [chat]
      summary: RAG 跨文档问答（SSE 流式 + 行内引用 + 防幻觉）
      description: |
        返回 `text/event-stream`。每个事件 `data:` 为一个 ChatChunk JSON
        （`type` ∈ `token | citations | done | not_found | error`）：
        ```
        data: {"type":"token","content":"AgentSys 通过调度器分发任务[1]。"}
        data: {"type":"citations","citations":[{"n":1,"doc_id":"...","chunk_id":"...","title":"...","source_url":"...","snippet":"...","offset":640}]}
        data: {"type":"done","content":""}
        ```
        防幻觉命中（召回为空 / 最高分 < RAG_MIN_SCORE）时：
        ```
        data: {"type":"not_found","content":"知识库中未找到相关资料"}
        data: {"type":"done","content":""}
        ```
        帧顺序：token*（多帧）→ citations → done；或 not_found → done；或任意时刻 error。
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ChatIn' }
      responses:
        '200':
          description: SSE 应答流（ChatChunk 序列）
          content:
            text/event-stream:
              schema: { $ref: '#/components/schemas/ChatChunk' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: 当前套餐未解锁高级 RAG（free 版）
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Msg' }

  # ============================ kb: folders ============================
  /api/kb/folders:
    get:
      tags: [kb]
      summary: 文件夹列表
      responses:
        '200':
          description: 文件夹列表
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/FolderOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      tags: [kb]
      summary: 新建文件夹
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/FolderIn' }
      responses:
        '201':
          description: 已创建
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FolderOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '422': { $ref: '#/components/responses/ValidationError' }

  /api/kb/folders/{id}:
    patch:
      tags: [kb]
      summary: 重命名 / 移动文件夹
      parameters:
        - $ref: '#/components/parameters/FolderId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/FolderIn' }
      responses:
        '200':
          description: 已更新
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FolderOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      tags: [kb]
      summary: 删除文件夹
      parameters:
        - $ref: '#/components/parameters/FolderId'
      responses:
        '204': { description: 已删除 }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  # ============================ kb: documents ============================
  /api/kb/documents:
    get:
      tags: [kb]
      summary: 文档列表（按文件夹 / 标签 / 排序过滤）
      parameters:
        - name: folder_id
          in: query
          required: false
          schema: { type: string }
        - name: tag
          in: query
          required: false
          schema: { type: string }
        - name: source_type
          in: query
          required: false
          schema: { type: string, enum: [feed, github, site, upload, note] }
        - name: sort
          in: query
          required: false
          schema: { type: string, enum: [created_desc, created_asc, title], default: created_desc }
        - name: page
          in: query
          required: false
          schema: { type: integer, minimum: 1, default: 1 }
        - name: size
          in: query
          required: false
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
      responses:
        '200':
          description: 文档分页列表
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DocListOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }

  /api/kb/documents/upload:
    post:
      tags: [kb]
      summary: 上传本地文档（PDF/Word/TXT/MD/代码），异步入库
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                folder_id:
                  type: string
      responses:
        '202':
          description: 已上传并下发入库任务
          content:
            application/json:
              schema: { $ref: '#/components/schemas/UploadOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402':
          description: 配额超限
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Msg' }

  /api/kb/documents/{id}:
    get:
      tags: [kb]
      summary: 文档详情（元数据）
      parameters:
        - $ref: '#/components/parameters/DocId'
      responses:
        '200':
          description: 文档详情
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DocumentOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    patch:
      tags: [kb]
      summary: 重命名 / 移动文档
      description: 提供 title 即重命名；提供 folder_id 即移动。
      parameters:
        - $ref: '#/components/parameters/DocId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/DocPatchIn' }
      responses:
        '200':
          description: 已更新
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DocumentOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      tags: [kb]
      summary: 删除文档（同步清理 Qdrant 向量与对象存储）
      parameters:
        - $ref: '#/components/parameters/DocId'
      responses:
        '204': { description: 已删除 }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /api/kb/documents/{id}/content:
    get:
      tags: [kb]
      summary: 文档正文内容（供阅读器渲染与引用跳转定位）
      parameters:
        - $ref: '#/components/parameters/DocId'
      responses:
        '200':
          description: 文档正文（Markdown / 纯文本）及定位信息
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DocContentOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /api/kb/documents/{id}/share:
    post:
      tags: [kb]
      summary: 创建文档分享链接（带过期）
      parameters:
        - $ref: '#/components/parameters/DocId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ShareIn' }
      responses:
        '201':
          description: 分享链接
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShareOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /api/kb/quota:
    get:
      tags: [kb]
      summary: 当前租户配额用量
      responses:
        '200':
          description: 配额
          content:
            application/json:
              schema: { $ref: '#/components/schemas/QuotaOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }

  # ============================ health ============================
  /api/health:
    get:
      tags: [health]
      summary: 健康检查
      security: []
      responses:
        '200':
          description: 服务及依赖状态
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HealthOut' }

components:
  securitySchemes:
    bearerJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: '登录/注册获取的 access_token，置于 `Authorization: Bearer <token>`。'

  parameters:
    FeedId:
      name: id
      in: path
      required: true
      schema: { type: string }
    TaskId:
      name: id
      in: path
      required: true
      schema: { type: string }
    DocId:
      name: id
      in: path
      required: true
      schema: { type: string }
    FolderId:
      name: id
      in: path
      required: true
      schema: { type: string }

  responses:
    Unauthorized:
      description: 未认证或令牌失效
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Msg' }
    NotFound:
      description: 资源不存在
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Msg' }
    Conflict:
      description: 资源冲突（如邮箱已注册）
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Msg' }
    RateLimited:
      description: 触发限流
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Msg' }
    ValidationError:
      description: 请求体校验失败
      content:
        application/json:
          schema: { $ref: '#/components/schemas/HTTPValidationError' }

  schemas:
    # ---- 通用 ----
    Msg:
      type: object
      properties:
        detail: { type: string }
      required: [detail]
    IdOut:
      type: object
      properties:
        id: { type: string }
      required: [id]
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            type: object
            properties:
              loc:
                type: array
                items:
                  anyOf:
                    - { type: string }
                    - { type: integer }
              msg: { type: string }
              type: { type: string }

    # ---- auth ----
    RegisterIn:
      type: object
      required: [email, password]
      properties:
        email: { type: string, format: email }
        password: { type: string, minLength: 6, maxLength: 128 }
        display_name: { type: string, default: '' }
    LoginIn:
      type: object
      required: [email, password]
      properties:
        email: { type: string, format: email }
        password:
          type: string
          description: 明文密码，或 enc=true 时为 RSA 加密的密文
        enc: { type: boolean, default: false }
    TokenOut:
      type: object
      required: [access_token, expires_in]
      properties:
        access_token: { type: string }
        token_type: { type: string, default: bearer }
        expires_in: { type: integer, description: 有效期（秒） }
    UserOut:
      type: object
      required: [id, email, plan, display_name, tenant_id]
      properties:
        id: { type: string }
        email: { type: string }
        plan: { type: string, enum: [free, pro, team] }
        display_name: { type: string }
        tenant_id: { type: string }
    PubKeyOut:
      type: object
      required: [public_key]
      properties:
        public_key: { type: string, description: PEM 格式 RSA 公钥 }

    # ---- feed ----
    FeedItem:
      type: object
      required: [id, title_zh, title_en, summary_zh, source, source_url, published_at]
      properties:
        id: { type: string }
        title_zh: { type: string, description: 中文标题（翻译后） }
        title_en: { type: string, description: 原英文标题 }
        summary_zh: { type: string, description: 中文精要 }
        source: { type: string, description: 来源（OpenAI/Anthropic/HF...） }
        source_url: { type: string, description: 原文 URL（强制留源） }
        thumbnail_url: { type: string, default: '', description: 英文原网页缩略图（MinIO 预签名 URL） }
        published_at: { type: string, description: ISO 时间 }
        tags:
          type: array
          items: { type: string }
          default: []
        is_fresh: { type: boolean, default: false, description: 本批最新（前端赤金脉冲高亮） }
        favorited: { type: boolean, default: false }
    FeedListOut:
      type: object
      required: [items, total]
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/FeedItem' }
        total: { type: integer }
        updated_at: { type: [string, 'null'] }
    FavoriteOut:
      type: object
      required: [document_id, status]
      properties:
        document_id: { type: string }
        status: { type: string, enum: [ingesting, ready], default: ingesting }
        task_id: { type: [string, 'null'] }

    # ---- analyze / tasks ----
    GithubAnalyzeIn:
      type: object
      required: [url]
      properties:
        url: { type: string, format: uri, description: GitHub 仓库地址 }
    SiteAnalyzeIn:
      type: object
      required: [url]
      properties:
        url: { type: string, format: uri }
        format: { type: string, enum: [md, ppt], default: md }
    TaskCreatedOut:
      type: object
      required: [task_id]
      properties:
        task_id: { type: string }
        status: { type: string, default: pending }
    TaskOut:
      type: object
      required: [id, type, status, stage, progress]
      properties:
        id: { type: string }
        type: { type: string, enum: [github, site, ingest, feed] }
        status: { type: string, enum: [pending, running, success, failed] }
        stage: { type: string, description: 阶段（抓取/解析/撰写/入库...） }
        progress: { type: integer, minimum: 0, maximum: 100 }
        error: { type: string, default: '' }
        result_doc_id: { type: [string, 'null'] }
        created_at: { type: [string, 'null'] }
    TaskListOut:
      type: object
      required: [items, total]
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/TaskOut' }
        total: { type: integer }

    # ---- search ----
    SearchHit:
      type: object
      required: [doc_id, chunk_id, title, source_type, snippet, score]
      properties:
        doc_id: { type: string }
        chunk_id: { type: string }
        title: { type: string }
        source_type: { type: string, enum: [feed, github, site, upload, note] }
        source_url: { type: string, default: '' }
        snippet: { type: string, description: 命中段落（前端高亮） }
        score: { type: number }
        heading_path: { type: string, default: '' }
        tags:
          type: array
          items: { type: string }
          default: []
    SearchOut:
      type: object
      required: [query, hits, took_ms]
      properties:
        query: { type: string }
        hits:
          type: array
          items: { $ref: '#/components/schemas/SearchHit' }
        took_ms: { type: integer }

    # ---- chat ----
    ChatIn:
      type: object
      required: [query]
      properties:
        query: { type: string }
        scope: { type: string, enum: [all, folder, tag], default: all }
        folder_id: { type: [string, 'null'] }
        tag: { type: [string, 'null'] }
    Citation:
      type: object
      required: [n, doc_id, chunk_id, title, snippet]
      properties:
        n: { type: integer, description: '行内引用编号 [n]' }
        doc_id: { type: string }
        chunk_id: { type: string }
        title: { type: string }
        source_url: { type: string, default: '' }
        snippet: { type: string }
        offset: { type: integer, default: 0, description: chunk 在文档内偏移，供前端跳转定位 }
    ChatChunk:
      type: object
      required: [type]
      description: SSE 帧；type=token 为逐字内容，citations/done/not_found/error 为控制帧。
      properties:
        type: { type: string, enum: [token, citations, done, not_found, error] }
        content: { type: string, default: '' }
        citations:
          type: array
          items: { $ref: '#/components/schemas/Citation' }
          default: []

    # ---- kb ----
    FolderIn:
      type: object
      required: [name]
      properties:
        name: { type: string }
        parent_id: { type: [string, 'null'] }
    FolderOut:
      type: object
      required: [id, name]
      properties:
        id: { type: string }
        name: { type: string }
        parent_id: { type: [string, 'null'] }
    DocumentOut:
      type: object
      required: [id, title, source_type]
      properties:
        id: { type: string }
        title: { type: string }
        source_type: { type: string, enum: [feed, github, site, upload, note] }
        source_url: { type: string, default: '' }
        summary: { type: string, default: '' }
        category: { type: string, default: '', description: 资讯/开源项目/技术文档/个人笔记 }
        status: { type: string, enum: [ingesting, ready, failed], default: ready }
        folder_id: { type: [string, 'null'] }
        tags:
          type: array
          items: { type: string }
          default: []
        size_bytes: { type: integer, default: 0 }
        created_at: { type: [string, 'null'] }
    DocListOut:
      type: object
      required: [items, total]
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/DocumentOut' }
        total: { type: integer }
    DocPatchIn:
      type: object
      description: 提供 title 重命名；提供 folder_id 移动（二者可同时）。
      properties:
        title: { type: string }
        folder_id: { type: [string, 'null'] }
    DocContentOut:
      type: object
      required: [doc_id, content]
      properties:
        doc_id: { type: string }
        title: { type: string }
        content: { type: string, description: Markdown / 纯文本正文 }
        format: { type: string, enum: [markdown, text, html], default: markdown }
    UploadOut:
      type: object
      required: [document_id, task_id, status]
      properties:
        document_id: { type: string }
        task_id: { type: string }
        status: { type: string, enum: [ingesting], default: ingesting }
    ShareIn:
      type: object
      properties:
        scope: { type: string, enum: [read], default: read }
        ttl_hours: { type: integer, default: 168 }
    ShareOut:
      type: object
      required: [token, url]
      properties:
        token: { type: string }
        url: { type: string }
        expire_at: { type: [string, 'null'] }
    QuotaOut:
      type: object
      required: [doc_count, used_bytes, plan_limit_docs, plan_limit_bytes, plan]
      properties:
        doc_count: { type: integer }
        used_bytes: { type: integer }
        plan_limit_docs: { type: integer, description: -1 表示无限 }
        plan_limit_bytes: { type: integer, description: -1 表示无限 }
        plan: { type: string, enum: [free, pro, team] }

    # ---- health ----
    HealthOut:
      type: object
      required: [status]
      properties:
        status: { type: string, enum: [ok, degraded], example: ok }
        version: { type: string }
        deps:
          type: object
          additionalProperties: { type: string }
          description: 各依赖（postgres/redis/qdrant/minio）连通状态