{
  "openapi": "3.0.3",
  "info": {
    "title": "MuguaApi",
    "version": "1.0.0",
    "description": "独立部署的木瓜法宝 OpenAI 风格接口，只对外提供法律咨询和案件分析两个业务能力。\n\n### 鉴权方式\n\n- 所有业务接口都要求 `Authorization: Bearer sk-xxxx`\n- `/health`、`/docs`、`/openapi.json` 无需鉴权\n\n### 请求约束\n\n- `legal-chat` 支持 `application/json` 或 `multipart/form-data`\n- `case-analysis` 的 `element_extract` 支持 `application/json` 或 `multipart/form-data`\n- `case-analysis` 的 `full_analysis` 只支持 `application/json`\n- `enable_network=true` 时，`legal-chat` 不允许同时上传文件\n- `enable_network=true` 时，`legal-chat` 响应会自动附带联网检索结果\n- **合同初查**、**合同审查**：`files[]` **仅 1 个文件**，且仅 **`.docx`**\n- **合同大纲**、**合同生成**、**法律文书**、法律咨询、案情分析等：上传支持 **`.docx`、`.doc`、`.pdf`**（与响应体 `output_format=docx` 无关）\n\n### 标准错误码对照表\n\n| HTTP 状态码 | `error.type` | 含义 |\n| --- | --- | --- |\n| `400` | `invalid_request_error` | 请求参数不合法、字段缺失、文件格式或请求方式不符合要求 |\n| `401` | `authentication_error` | 未携带 Bearer Token、Token 格式错误或 API Key 无效 |\n| `402` | `billing_error` | API Key 可用调用次数不足 |\n| `429` | `rate_limit_error` | 请求频率超限，响应头会返回 `Retry-After` 和 `RateLimit-*` |\n| `500` | `server_error` | 服务内部异常，例如计费规则缺失 |\n| `502` | `server_error` | 上游模型服务异常或返回空内容 |\n| `503` | `server_error` | Redis 等依赖服务不可用 |\n"
  },
  "servers": [
    {
      "url": "http://api.mugua.muguafabao.com",
      "description": "当前访问地址"
    }
  ],
  "tags": [
    {
      "name": "System",
      "description": "系统诊断接口"
    },
    {
      "name": "Legal Chat",
      "description": "法律咨询接口"
    },
    {
      "name": "Case Analysis",
      "description": "案件分析接口"
    },
    {
      "name": "Contract Review",
      "description": "合同审查接口（初查 + 审查）"
    },
    {
      "name": "Contract Draft",
      "description": "合同起草接口（大纲 + 生成）"
    },
    {
      "name": "Legal Doc Draft",
      "description": "法律文书起草接口（大纲 + 生成）"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "使用 `Authorization: Bearer sk-xxxx` 传递 API Key。"
      }
    },
    "headers": {
      "RetryAfter": {
        "description": "建议在多少秒后重试。",
        "schema": {
          "type": "string",
          "example": "1"
        }
      },
      "RateLimitLimit": {
        "description": "当前窗口内允许的最大请求数。",
        "schema": {
          "type": "string",
          "example": "2"
        }
      },
      "RateLimitRemaining": {
        "description": "当前窗口内剩余可用请求数。触发限流时通常为 `0`。",
        "schema": {
          "type": "string",
          "example": "0"
        }
      },
      "RateLimitReset": {
        "description": "当前限流窗口在多少秒后重置。",
        "schema": {
          "type": "string",
          "example": "1"
        }
      }
    },
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok"
            ],
            "description": "健康检查结果。"
          }
        },
        "example": {
          "status": "ok"
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "message",
              "type"
            ],
            "properties": {
              "message": {
                "type": "string",
                "description": "错误说明，适合直接展示给调用方或写入日志。"
              },
              "type": {
                "type": "string",
                "enum": [
                  "invalid_request_error",
                  "authentication_error",
                  "billing_error",
                  "rate_limit_error",
                  "server_error"
                ],
                "description": "标准化错误分类。"
              }
            }
          }
        },
        "example": {
          "error": {
            "message": "缺少必要参数：prompt",
            "type": "invalid_request_error"
          }
        }
      },
      "LegalChatJsonRequest": {
        "type": "object",
        "required": [
          "prompt"
        ],
        "properties": {
          "prompt": {
            "type": "string",
            "description": "用户问题正文。不能为空。",
            "example": "请分析劳动仲裁申请前需要准备哪些材料？"
          },
          "stream": {
            "type": "boolean",
            "default": false,
            "description": "是否返回流式 SSE 响应。"
          },
          "enable_network": {
            "type": "boolean",
            "default": false,
            "description": "是否启用联网检索。开启后不能同时上传文件。"
          }
        }
      },
      "LegalChatMultipartRequest": {
        "type": "object",
        "required": [
          "prompt"
        ],
        "properties": {
          "prompt": {
            "type": "string",
            "description": "用户问题正文。不能为空。"
          },
          "stream": {
            "type": "boolean",
            "default": false,
            "description": "是否返回流式 SSE 响应。"
          },
          "enable_network": {
            "type": "boolean",
            "default": false,
            "description": "联网模式下不可与文件上传同时使用。"
          },
          "files[]": {
            "type": "array",
            "description": "上传文件数组，字段名必须是 `files[]`。支持 .docx、.doc、.pdf；.doc 依赖服务端 antiword/catdoc/LibreOffice 等。",
            "items": {
              "type": "string",
              "format": "binary"
            }
          }
        }
      },
      "CompletionStatus": {
        "type": "string",
        "enum": [
          "completed"
        ],
        "description": "非流式成功响应固定为 `completed`。"
      },
      "SearchResult": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "搜索结果标题。"
          },
          "link": {
            "type": "string",
            "description": "搜索结果链接。"
          },
          "snippet": {
            "type": "string",
            "description": "搜索结果摘要。"
          }
        }
      },
      "LegalChatCompletionResponse": {
        "type": "object",
        "required": [
          "id",
          "object",
          "request_id",
          "created_at",
          "status",
          "output_text"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "本次响应 ID。"
          },
          "object": {
            "type": "string",
            "enum": [
              "legal_chat.completion"
            ],
            "description": "固定对象类型。"
          },
          "request_id": {
            "type": "string",
            "format": "uuid",
            "description": "请求唯一标识，可用于排障和审计。"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "UTC 时间，ISO 8601 格式。"
          },
          "status": {
            "$ref": "#/components/schemas/CompletionStatus"
          },
          "output_text": {
            "type": "string",
            "description": "最终法律咨询文本。"
          },
          "search_results": {
            "type": "array",
            "description": "联网检索结果列表。仅在 enable_network=true 时返回。",
            "items": {
              "$ref": "#/components/schemas/SearchResult"
            }
          },
          "search_result_count": {
            "type": "integer",
            "description": "联网检索结果数量。仅在 enable_network=true 时返回。",
            "example": 3
          }
        },
        "example": {
          "id": "d4da3f58-8d32-4f88-9174-0c66a1d87b6d",
          "object": "legal_chat.completion",
          "request_id": "d4da3f58-8d32-4f88-9174-0c66a1d87b6d",
          "created_at": "2026-03-04T05:44:24.495012Z",
          "status": "completed",
          "output_text": "建议先准备劳动合同、工资流水、考勤记录等材料，再确定仲裁请求。",
          "search_results": [
            {
              "title": "劳动仲裁申请流程指南",
              "link": "https://example.com/labor-arbitration",
              "snippet": "介绍劳动仲裁申请材料和办理流程。"
            }
          ],
          "search_result_count": 1
        }
      },
      "CaseAnalysisMode": {
        "type": "string",
        "enum": [
          "element_extract",
          "full_analysis"
        ],
        "description": "案件分析模式枚举。"
      },
      "Party": {
        "type": "object",
        "description": "当事人信息。至少建议提供 `name`。",
        "properties": {
          "name": {
            "type": "string",
            "description": "当事人姓名或名称。"
          },
          "role": {
            "type": "string",
            "description": "当事人角色，例如原告、被告、第三人。"
          }
        },
        "additionalProperties": true,
        "example": {
          "name": "张三",
          "role": "原告"
        }
      },
      "CaseReason": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "案由 ID；未传时服务端可自动生成。"
          },
          "name": {
            "type": "string",
            "description": "案由名称。"
          },
          "description": {
            "type": "string",
            "description": "案由补充说明。"
          }
        },
        "example": {
          "id": "1",
          "name": "民间借贷纠纷",
          "description": "围绕借款本金、利息、还款义务展开。"
        }
      },
      "Fact": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "事实 ID；未传时服务端可自动生成。"
          },
          "name": {
            "type": "string",
            "description": "事实描述。"
          }
        },
        "example": {
          "id": "1",
          "name": "2024 年 6 月 1 日被告向原告借款 20 万元。"
        }
      },
      "Demand": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "诉求 ID；未传时服务端可自动生成。"
          },
          "currentPart": {
            "type": "string",
            "description": "提出该诉求的当事人。"
          },
          "currentDemand": {
            "type": "string",
            "description": "具体诉求内容。"
          }
        },
        "example": {
          "id": "1",
          "currentPart": "张三",
          "currentDemand": "请求判令李四返还借款本金 20 万元及利息。"
        }
      },
      "FocusPoint": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "争议焦点 ID；未传时服务端可自动生成。"
          },
          "title": {
            "type": "string",
            "description": "争议焦点标题。"
          },
          "explanation": {
            "type": "string",
            "description": "争议焦点说明。"
          },
          "impactAppeal": {
            "type": "string",
            "description": "对诉求或案件结果的影响。"
          },
          "relatedRegulation": {
            "type": "string",
            "description": "相关法律名称，格式建议为《法律名称》。"
          },
          "numberOfTerms": {
            "type": "string",
            "description": "相关法条条号，格式建议为“第XX条”。"
          }
        },
        "example": {
          "id": "c6eae2ad-9374-4f83-9a5d-f2ee96437d7e",
          "title": "借款关系是否成立",
          "explanation": "需要结合借条、聊天记录及转账凭证综合判断。",
          "impactAppeal": "直接影响返还本金及利息请求是否能够成立。",
          "relatedRegulation": "《中华人民共和国民法典》",
          "numberOfTerms": "第六百六十七条"
        }
      },
      "EvidenceItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "证据项 ID。"
          },
          "name": {
            "type": "string",
            "description": "证据名称。"
          },
          "purpost": {
            "type": "string",
            "description": "证据用途说明。字段名沿用现有兼容格式 `purpost`。"
          }
        },
        "example": {
          "id": "1",
          "name": "银行转账记录",
          "purpost": "证明借款本金实际支付。"
        }
      },
      "EvidenceGroup": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "证据组 ID；未传时服务端可自动生成。"
          },
          "title": {
            "type": "string",
            "description": "证据组标题。"
          },
          "evidenceNo": {
            "type": "array",
            "description": "该组下的证据明细。",
            "items": {
              "$ref": "#/components/schemas/EvidenceItem"
            }
          }
        },
        "example": {
          "id": "23fcebd2-d4d3-4c82-b4cc-2d7f6358d694",
          "title": "证明借款关系和付款事实的证据",
          "evidenceNo": [
            {
              "id": "1",
              "name": "借条",
              "purpost": "证明双方借款合意。"
            }
          ]
        }
      },
      "ElementExtractOutput": {
        "type": "object",
        "required": [
          "parties",
          "case_reasons",
          "facts",
          "demands"
        ],
        "properties": {
          "parties": {
            "type": "array",
            "description": "提取出的当事人列表。",
            "items": {
              "$ref": "#/components/schemas/Party"
            }
          },
          "case_reasons": {
            "type": "array",
            "description": "提取出的案由列表。",
            "items": {
              "$ref": "#/components/schemas/CaseReason"
            }
          },
          "facts": {
            "type": "array",
            "description": "提取出的案件事实列表。",
            "items": {
              "$ref": "#/components/schemas/Fact"
            }
          },
          "demands": {
            "type": "array",
            "description": "提取出的诉求列表。",
            "items": {
              "$ref": "#/components/schemas/Demand"
            }
          }
        }
      },
      "FullAnalysisOutput": {
        "type": "object",
        "required": [
          "focus_points",
          "case_analysis",
          "evidence_list"
        ],
        "properties": {
          "focus_points": {
            "type": "array",
            "description": "争议焦点分析结果。",
            "items": {
              "$ref": "#/components/schemas/FocusPoint"
            }
          },
          "case_analysis": {
            "type": "string",
            "description": "案件概要和核心法律分析文本。"
          },
          "evidence_list": {
            "type": "array",
            "description": "证据清单分组。",
            "items": {
              "$ref": "#/components/schemas/EvidenceGroup"
            }
          }
        }
      },
      "ElementExtractJsonRequest": {
        "type": "object",
        "required": [
          "analysis_mode"
        ],
        "properties": {
          "analysis_mode": {
            "type": "string",
            "enum": [
              "element_extract"
            ],
            "description": "固定为 `element_extract`。"
          },
          "stream": {
            "type": "boolean",
            "default": false,
            "description": "是否返回流式 SSE 响应。"
          },
          "input": {
            "type": "string",
            "description": "案件原始文本。无文件上传时至少需要提供该字段。"
          },
          "case_type": {
            "type": "string",
            "description": "案件类型提示，可选。"
          }
        },
        "example": {
          "analysis_mode": "element_extract",
          "stream": false,
          "input": "原告张三主张被告李四于 2024 年 6 月借款 20 万元，至今未归还。",
          "case_type": "民间借贷纠纷"
        }
      },
      "ElementExtractMultipartRequest": {
        "type": "object",
        "required": [
          "analysis_mode"
        ],
        "properties": {
          "analysis_mode": {
            "type": "string",
            "enum": [
              "element_extract"
            ],
            "description": "固定为 `element_extract`。"
          },
          "stream": {
            "type": "boolean",
            "default": false,
            "description": "是否返回流式 SSE 响应。"
          },
          "input": {
            "type": "string",
            "description": "案件原始文本。与 `files[]` 二选一或同时使用。"
          },
          "case_type": {
            "type": "string",
            "description": "案件类型提示，可选。"
          },
          "files[]": {
            "type": "array",
            "description": "上传文件数组，字段名必须是 `files[]`。支持 .docx、.doc、.pdf；.doc 依赖服务端 antiword/catdoc/LibreOffice 等。",
            "items": {
              "type": "string",
              "format": "binary"
            }
          }
        }
      },
      "FullAnalysisRequest": {
        "type": "object",
        "required": [
          "analysis_mode",
          "case_reasons",
          "facts",
          "demands"
        ],
        "properties": {
          "analysis_mode": {
            "type": "string",
            "enum": [
              "full_analysis"
            ],
            "description": "固定为 `full_analysis`。"
          },
          "stream": {
            "type": "boolean",
            "default": false,
            "description": "是否返回流式 SSE 响应。"
          },
          "parties": {
            "type": "array",
            "description": "当事人列表。可选。",
            "items": {
              "$ref": "#/components/schemas/Party"
            }
          },
          "selected_party_names": {
            "type": "array",
            "description": "指定从哪些当事人视角出发分析；为空或省略表示使用全部 parties。",
            "items": {
              "type": "string"
            }
          },
          "case_reasons": {
            "type": "array",
            "description": "案由列表，必填。",
            "items": {
              "$ref": "#/components/schemas/CaseReason"
            }
          },
          "facts": {
            "type": "array",
            "description": "事实列表，必填。",
            "items": {
              "$ref": "#/components/schemas/Fact"
            }
          },
          "demands": {
            "type": "array",
            "description": "诉求列表，必填。",
            "items": {
              "$ref": "#/components/schemas/Demand"
            }
          }
        },
        "example": {
          "analysis_mode": "full_analysis",
          "stream": false,
          "parties": [
            {
              "name": "张三",
              "role": "原告"
            },
            {
              "name": "李四",
              "role": "被告"
            }
          ],
          "selected_party_names": [
            "张三"
          ],
          "case_reasons": [
            {
              "id": "1",
              "name": "民间借贷纠纷",
              "description": "围绕借款本金、利息、还款义务展开。"
            }
          ],
          "facts": [
            {
              "id": "1",
              "name": "被告于 2024 年 6 月向原告借款 20 万元。"
            },
            {
              "id": "2",
              "name": "原告通过银行转账方式支付借款。"
            }
          ],
          "demands": [
            {
              "id": "1",
              "currentPart": "张三",
              "currentDemand": "请求返还借款本金 20 万元及利息。"
            }
          ]
        }
      },
      "CaseAnalysisElementExtractResponse": {
        "type": "object",
        "required": [
          "id",
          "object",
          "request_id",
          "created_at",
          "status",
          "analysis_mode",
          "output"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "本次响应 ID。"
          },
          "object": {
            "type": "string",
            "enum": [
              "case_analysis.response"
            ],
            "description": "固定对象类型。"
          },
          "request_id": {
            "type": "string",
            "format": "uuid",
            "description": "请求唯一标识。"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "UTC 时间，ISO 8601 格式。"
          },
          "status": {
            "$ref": "#/components/schemas/CompletionStatus"
          },
          "analysis_mode": {
            "type": "string",
            "enum": [
              "element_extract"
            ]
          },
          "output": {
            "$ref": "#/components/schemas/ElementExtractOutput"
          }
        },
        "example": {
          "id": "d8bdab5e-3b06-40d1-9590-348e2d177f6c",
          "object": "case_analysis.response",
          "request_id": "d8bdab5e-3b06-40d1-9590-348e2d177f6c",
          "created_at": "2026-03-04T05:44:24.495012Z",
          "status": "completed",
          "analysis_mode": "element_extract",
          "output": {
            "parties": [
              {
                "name": "张三"
              },
              {
                "name": "李四"
              }
            ],
            "case_reasons": [
              {
                "id": "1",
                "name": "民间借贷纠纷",
                "description": "围绕借款及利息请求展开。"
              }
            ],
            "facts": [
              {
                "id": "1",
                "name": "被告向原告借款 20 万元。"
              },
              {
                "id": "2",
                "name": "借款到期后被告未还款。"
              }
            ],
            "demands": [
              {
                "id": "1",
                "currentPart": "张三",
                "currentDemand": "请求返还借款本金及利息。"
              }
            ]
          }
        }
      },
      "CaseAnalysisFullAnalysisResponse": {
        "type": "object",
        "required": [
          "id",
          "object",
          "request_id",
          "created_at",
          "status",
          "analysis_mode",
          "output"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "本次响应 ID。"
          },
          "object": {
            "type": "string",
            "enum": [
              "case_analysis.response"
            ],
            "description": "固定对象类型。"
          },
          "request_id": {
            "type": "string",
            "format": "uuid",
            "description": "请求唯一标识。"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "UTC 时间，ISO 8601 格式。"
          },
          "status": {
            "$ref": "#/components/schemas/CompletionStatus"
          },
          "analysis_mode": {
            "type": "string",
            "enum": [
              "full_analysis"
            ]
          },
          "output": {
            "$ref": "#/components/schemas/FullAnalysisOutput"
          }
        },
        "example": {
          "id": "81450ff0-01d0-430a-a6c6-bd5d114f80fa",
          "object": "case_analysis.response",
          "request_id": "81450ff0-01d0-430a-a6c6-bd5d114f80fa",
          "created_at": "2026-03-04T05:44:24.495012Z",
          "status": "completed",
          "analysis_mode": "full_analysis",
          "output": {
            "focus_points": [
              {
                "id": "c6eae2ad-9374-4f83-9a5d-f2ee96437d7e",
                "title": "借款关系是否成立",
                "explanation": "需要结合借条、聊天记录及转账凭证综合判断。",
                "impactAppeal": "直接影响返还本金及利息请求是否能够成立。",
                "relatedRegulation": "《中华人民共和国民法典》",
                "numberOfTerms": "第六百六十七条"
              }
            ],
            "case_analysis": "从现有事实看，原告已初步形成借款关系证据链，但仍需补强利息约定和催收记录。",
            "evidence_list": [
              {
                "id": "23fcebd2-d4d3-4c82-b4cc-2d7f6358d694",
                "title": "证明借款关系和付款事实的证据",
                "evidenceNo": [
                  {
                    "id": "1",
                    "name": "借条",
                    "purpost": "证明双方借款合意。"
                  }
                ]
              }
            ]
          }
        }
      },
      "RiskItem": {
        "type": "object",
        "properties": {
          "original_text": {
            "type": "string",
            "description": "有问题的合同原文"
          },
          "risk_description": {
            "type": "string",
            "description": "风险说明"
          },
          "suggested_modification": {
            "type": "string",
            "description": "建议修改内容"
          }
        }
      },
      "OutlineSection": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "index": {
            "type": "integer"
          },
          "sub_title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        }
      }
    }
  },
  "paths": {
    "/health": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "健康检查",
        "description": "用于负载均衡、监控或部署探活。",
        "responses": {
          "200": {
            "description": "服务运行正常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/legal-chat/completions": {
      "post": {
        "tags": [
          "Legal Chat"
        ],
        "summary": "法律咨询",
        "description": "单轮法律咨询接口。当 `stream=false` 时返回标准 JSON；当 `stream=true` 时返回 `text/event-stream`。当 `enable_network=true` 时，响应会自动附带联网检索结果。",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LegalChatJsonRequest"
              }
            },
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/LegalChatMultipartRequest"
              },
              "encoding": {
                "files[]": {
                  "style": "form",
                  "explode": true
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "咨询成功。根据 `stream` 参数，返回 JSON 或 SSE。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LegalChatCompletionResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "SSE 事件流，包含 `response.created`、`response.search_results`（可选）、`response.output_text.delta`、`response.completed` 和 `[DONE]`。"
                },
                "example": "event: response.created\ndata: {\"id\":\"...\",\"status\":\"in_progress\"}\n\nevent: response.search_results\ndata: {\"search_results\":[{\"title\":\"...\",\"link\":\"...\",\"snippet\":\"...\"}],\"search_result_count\":1}\n\nevent: response.output_text.delta\ndata: {\"delta\":\"建议先准备劳动合同\"}\n\nevent: response.completed\ndata: {\"id\":\"...\",\"status\":\"completed\",\"output_text\":\"...\"}\n\ndata: [DONE]\n\n"
              }
            }
          },
          "400": {
            "description": "请求参数错误。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "message": "缺少必要参数：prompt",
                    "type": "invalid_request_error"
                  }
                }
              }
            }
          },
          "401": {
            "description": "鉴权失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "message": "缺少有效的 Authorization Bearer Token",
                    "type": "authentication_error"
                  }
                }
              }
            }
          },
          "402": {
            "description": "余额不足。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "message": "可用调用次数不足",
                    "type": "billing_error"
                  }
                }
              }
            }
          },
          "429": {
            "description": "请求超出限流。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "message": "请求频率过高，请稍后再试",
                    "type": "rate_limit_error"
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            }
          },
          "500": {
            "description": "服务内部异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "message": "法律咨询接口异常: ...",
                    "type": "server_error"
                  }
                }
              }
            }
          },
          "502": {
            "description": "上游模型服务异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "message": "模型服务返回内容为空",
                    "type": "server_error"
                  }
                }
              }
            }
          },
          "503": {
            "description": "依赖服务不可用。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "message": "Redis 限流服务不可用: Authentication required.",
                    "type": "server_error"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/case-analysis/generate": {
      "post": {
        "tags": [
          "Case Analysis"
        ],
        "summary": "案件分析",
        "description": "案件分析接口，支持 `element_extract` 和 `full_analysis` 两种模式。`element_extract` 支持 JSON 或文件上传；`full_analysis` 仅支持 JSON。",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/ElementExtractJsonRequest"
                  },
                  {
                    "$ref": "#/components/schemas/FullAnalysisRequest"
                  }
                ],
                "discriminator": {
                  "propertyName": "analysis_mode",
                  "mapping": {
                    "element_extract": "#/components/schemas/ElementExtractJsonRequest",
                    "full_analysis": "#/components/schemas/FullAnalysisRequest"
                  }
                }
              }
            },
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/ElementExtractMultipartRequest"
              },
              "encoding": {
                "files[]": {
                  "style": "form",
                  "explode": true
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "分析成功。根据 `stream` 参数，返回 JSON 或 SSE。",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/CaseAnalysisElementExtractResponse"
                    },
                    {
                      "$ref": "#/components/schemas/CaseAnalysisFullAnalysisResponse"
                    }
                  ],
                  "discriminator": {
                    "propertyName": "analysis_mode",
                    "mapping": {
                      "element_extract": "#/components/schemas/CaseAnalysisElementExtractResponse",
                      "full_analysis": "#/components/schemas/CaseAnalysisFullAnalysisResponse"
                    }
                  }
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "SSE 事件流。`element_extract` 和 `full_analysis` 会按不同事件名分段输出。"
                },
                "example": "event: response.created\ndata: {\"id\":\"...\",\"status\":\"in_progress\",\"analysis_mode\":\"full_analysis\"}\n\nevent: case_analysis.focus_points\ndata: {\"focus_points\":[...]}\n\nevent: response.completed\ndata: {\"id\":\"...\",\"status\":\"completed\",\"analysis_mode\":\"full_analysis\",\"output\":{...}}\n\ndata: [DONE]\n\n"
              }
            }
          },
          "400": {
            "description": "请求参数错误。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "message": "analysis_mode 仅支持 element_extract 或 full_analysis",
                    "type": "invalid_request_error"
                  }
                }
              }
            }
          },
          "401": {
            "description": "鉴权失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "message": "无效的 API Key",
                    "type": "authentication_error"
                  }
                }
              }
            }
          },
          "402": {
            "description": "余额不足。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "message": "可用调用次数不足",
                    "type": "billing_error"
                  }
                }
              }
            }
          },
          "429": {
            "description": "请求超出限流。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "message": "请求频率过高，请稍后再试",
                    "type": "rate_limit_error"
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            }
          },
          "500": {
            "description": "服务内部异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "message": "案情分析接口异常: ...",
                    "type": "server_error"
                  }
                }
              }
            }
          },
          "502": {
            "description": "上游模型服务异常。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "message": "案情分析未生成有效结果",
                    "type": "server_error"
                  }
                }
              }
            }
          },
          "503": {
            "description": "依赖服务不可用。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "message": "Redis 限流服务不可用: Authentication required.",
                    "type": "server_error"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/contract-review/preliminary": {
      "post": {
        "tags": [
          "Contract Review"
        ],
        "summary": "合同初查",
        "description": "上传**单个**合同文件（.docx），识别合同类型和各方主体（甲方、乙方、第三方）。`files[]` 仅 1 个。stream=true 时返回 text/event-stream：先 response.created；再 contract_review.preliminary.phase（step=contract_type|parties）与 contract_review.preliminary.model_delta（模型原文增量，便于展示过程）；随后与非流式相同的结构化字段事件，最后 response.completed。流式为两步顺序 stream（非并行），总耗时可长于同步接口。",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "files[]"
                ],
                "properties": {
                  "files[]": {
                    "type": "array",
                    "maxItems": 1,
                    "minItems": 1,
                    "items": {
                      "type": "string",
                      "format": "binary"
                    },
                    "description": "单个 .docx 合同文件"
                  },
                  "stream": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "初查成功；stream=true 时为 text/event-stream（SSE）。",
            "content": {
              "application/json": {
                "example": {
                  "id": "xxx",
                  "object": "contract_review.preliminary",
                  "status": "completed",
                  "contract_type": "买卖合同",
                  "parties_a": [
                    {
                      "name": "xxx公司"
                    }
                  ],
                  "parties_b": [
                    {
                      "name": "yyy公司"
                    }
                  ],
                  "third_parties": []
                }
              }
            }
          },
          "400": {
            "description": "参数错误。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "message": "缺少必要参数：files[] 或一次最多上传 1 个文件",
                    "type": "invalid_request_error"
                  }
                }
              }
            }
          },
          "401": {
            "description": "鉴权失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "message": "无效的 API Key",
                    "type": "authentication_error"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/contract-review/analyze": {
      "post": {
        "tags": [
          "Contract Review"
        ],
        "summary": "合同审查",
        "description": "上传**单个**合同文件（.docx），结合合同类型、各方主体和立场进行风险审查。`files[]` 仅 1 个。stream=true 时为 SSE：与非流式相同的一次 analyze 结果，risk_items 分块推送（event: contract_review.analysis.risk_items），最后 response.completed。",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "files[]"
                ],
                "properties": {
                  "files[]": {
                    "type": "array",
                    "maxItems": 1,
                    "minItems": 1,
                    "items": {
                      "type": "string",
                      "format": "binary"
                    },
                    "description": "单个 .docx 合同文件"
                  },
                  "contract_type": {
                    "type": "string"
                  },
                  "parties_a": {
                    "type": "string",
                    "description": "JSON数组字符串"
                  },
                  "parties_b": {
                    "type": "string",
                    "description": "JSON数组字符串"
                  },
                  "third_parties": {
                    "type": "string",
                    "description": "JSON数组字符串"
                  },
                  "stance": {
                    "type": "string",
                    "description": "甲方/乙方/第三方/中立"
                  },
                  "stream": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "审查成功。",
            "content": {
              "application/json": {
                "example": {
                  "id": "xxx",
                  "object": "contract_review.analysis",
                  "status": "completed",
                  "risk_items": [
                    {
                      "original_text": "...",
                      "risk_description": "...",
                      "suggested_modification": "..."
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "参数错误。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "message": "缺少必要参数：files[] 或一次最多上传 1 个文件",
                    "type": "invalid_request_error"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/contract-draft/outline": {
      "post": {
        "tags": [
          "Contract Draft"
        ],
        "summary": "合同大纲",
        "description": "根据起草要求和参考文件生成合同大纲。参考文件仅作用语与结构参考，模型不会把参考文件中的具体当事人名称、证件号、金额日期等写入大纲描述。stream=true 时为 SSE：与非流式相同结果，按 contract_type、各 section 分事件推送，最后 response.completed。",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "requirements"
                ],
                "properties": {
                  "requirements": {
                    "type": "string",
                    "description": "起草要求"
                  },
                  "contract_type": {
                    "type": "string",
                    "description": "指定合同类型（可选）"
                  },
                  "files[]": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    },
                    "description": "参考文件（可选）；.docx/.doc/.pdf；仅供结构与用语参考，不照搬其中主体信息与具体数字"
                  },
                  "stream": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "大纲生成成功；stream=true 时为 text/event-stream。",
            "content": {
              "application/json": {
                "example": {
                  "id": "xxx",
                  "object": "contract_draft.outline",
                  "status": "completed",
                  "contract_type": "买卖合同",
                  "outline": [
                    {
                      "id": "uuid",
                      "index": 1,
                      "sub_title": "总则",
                      "description": "..."
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/contract-draft/generate": {
      "post": {
        "tags": [
          "Contract Draft"
        ],
        "summary": "生成合同文件",
        "description": "根据大纲和起草要求生成完整合同。支持 JSON 和 multipart/form-data（带文件上传）。参考文件仅作用语、条款逻辑与格式参考，正文中的甲乙方名称、地址、账号、金额、日期等须用下划线占位，不从参考文件自动填入。output_format 可选 text（默认，返回 JSON）或 docx（非流式返回二进制下载）。stream=true 时为 SSE：与非流式相同一次生成，Markdown 正文分片 response.output_text.delta；output_format=docx 时 completed 事件含 file_base64、filename。",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "outline"
                ],
                "properties": {
                  "requirements": {
                    "type": "string"
                  },
                  "contract_type": {
                    "type": "string",
                    "description": "可选；若传须为预定义合同类型场景名"
                  },
                  "outline": {
                    "type": "string",
                    "description": "大纲JSON数组字符串"
                  },
                  "output_format": {
                    "type": "string",
                    "enum": [
                      "text",
                      "docx"
                    ],
                    "default": "text",
                    "description": "输出格式：text 返回 JSON，docx 返回文件下载"
                  },
                  "stream": {
                    "type": "boolean",
                    "default": false
                  },
                  "files[]": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    },
                    "description": "参考文件（可选）；.docx/.doc/.pdf；仅供用语与格式参考，不自动填入参考文件中的主体信息与具体数字"
                  }
                }
              }
            },
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "outline"
                ],
                "properties": {
                  "requirements": {
                    "type": "string"
                  },
                  "contract_type": {
                    "type": "string",
                    "description": "可选；若传须为预定义合同类型场景名"
                  },
                  "outline": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/OutlineSection"
                    }
                  },
                  "output_format": {
                    "type": "string",
                    "enum": [
                      "text",
                      "docx"
                    ],
                    "default": "text",
                    "description": "输出格式：text 返回 JSON，docx 返回文件下载"
                  },
                  "stream": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "合同生成成功。output_format=text 时返回 JSON，output_format=docx 时返回 DOCX 文件。",
            "content": {
              "application/json": {
                "example": {
                  "id": "xxx",
                  "object": "contract_draft.document",
                  "status": "completed",
                  "output_text": "# 买卖合同\n\n## 一、总则\n..."
                }
              },
              "application/vnd.openxmlformats-officedocument.wordprocessingml.document": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          }
        }
      }
    },
    "/v1/legal-doc-draft/generate": {
      "post": {
        "tags": [
          "Legal Doc Draft"
        ],
        "summary": "生成法律文书",
        "description": "传入起草要求和附属文件，直接生成完整法律文书（无大纲步骤）。可通过 template 指定参考模板。output_format 可选 text（默认，返回 JSON 含 Markdown）或 docx（非流式返回二进制下载）。stream=true 时为 SSE：与非流式相同一次 generate，正文分片 delta；docx 时 completed 含 file_base64、filename。",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "requirements"
                ],
                "properties": {
                  "requirements": {
                    "type": "string",
                    "description": "起草要求（用户的文书需求描述）"
                  },
                  "template": {
                    "type": "string",
                    "description": "文书模板代码（可选，如 civil_complaint）"
                  },
                  "output_format": {
                    "type": "string",
                    "enum": [
                      "text",
                      "docx"
                    ],
                    "default": "text",
                    "description": "输出格式：text 返回 JSON，docx 返回文件下载"
                  },
                  "stream": {
                    "type": "boolean",
                    "default": false
                  },
                  "files[]": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    },
                    "description": "附属文件（可选）；.docx/.doc/.pdf"
                  }
                }
              }
            },
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "requirements"
                ],
                "properties": {
                  "requirements": {
                    "type": "string",
                    "description": "起草要求（用户的文书需求描述）"
                  },
                  "template": {
                    "type": "string",
                    "description": "文书模板代码（可选，如 civil_complaint）"
                  },
                  "output_format": {
                    "type": "string",
                    "enum": [
                      "text",
                      "docx"
                    ],
                    "default": "text",
                    "description": "输出格式：text 返回 JSON，docx 返回文件下载"
                  },
                  "stream": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "文书生成成功。output_format=text 时返回 JSON，output_format=docx 时返回 DOCX 文件。",
            "content": {
              "application/json": {
                "example": {
                  "id": "xxx",
                  "object": "legal_doc_draft.document",
                  "status": "completed",
                  "output_text": "# 民事起诉状\n\n原告：张三\n被告：李四\n\n..."
                }
              },
              "application/vnd.openxmlformats-officedocument.wordprocessingml.document": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          }
        }
      }
    }
  }
}