{"openapi":"3.0.3","info":{"title":"战胜癌症 科研 API","version":"0.23.0","description":"癌症靶向药研究咨询工作台的对外接口。所有输出均为计算假设与证据综述，不构成效力、安全性、疗效或治疗建议。科研接口需要认证：浏览器使用会话 Cookie，脚本使用 Authorization: Bearer <token>（在设置页签发）。","contact":{"name":"见站点「关于」页配置的主体信息"}},"servers":[{"url":"http://127.0.0.1:4173","description":"本地部署"}],"tags":[{"name":"public","description":"无需认证：健康信息与实例元数据"},{"name":"auth","description":"注册、登录与 API 令牌"},{"name":"research","description":"需要认证与相应权限的科研能力"}],"components":{"securitySchemes":{"sessionCookie":{"type":"apiKey","in":"cookie","name":"of_session"},"bearerToken":{"type":"http","scheme":"bearer","description":"在设置页签发，仅显示一次"}},"schemas":{"Variant":{"type":"object","required":["gene","variant"],"properties":{"gene":{"type":"string","example":"EGFR","description":"HGNC 基因符号"},"variant":{"type":"string","example":"L858R","description":"蛋白改变。支持 p.Thr315Ile 等三字母写法，服务端归一化为一字母"},"vaf":{"type":"number","minimum":0,"maximum":1,"example":0.42},"zygosity":{"type":"string","example":"subclonal"}}},"Profile":{"type":"object","required":["sample_id","tissue","variants"],"properties":{"sample_id":{"type":"string","maxLength":64,"description":"内部编号。不要填入姓名、住院号或身份证号"},"tissue":{"type":"string","maxLength":100,"example":"lung adenocarcinoma"},"variants":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","required":["gene","variant"],"properties":{"gene":{"type":"string","example":"EGFR","description":"HGNC 基因符号"},"variant":{"type":"string","example":"L858R","description":"蛋白改变。支持 p.Thr315Ile 等三字母写法，服务端归一化为一字母"},"vaf":{"type":"number","minimum":0,"maximum":1,"example":0.42},"zygosity":{"type":"string","example":"subclonal"}}}}}},"Job":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"sampleId":{"type":"string"},"tissue":{"type":"string"},"tier":{"type":"string","enum":["fast","standard","deep"]},"status":{"type":"string","enum":["queued","running","succeeded","declined","failed","cancelled"]},"queuePosition":{"type":"integer","description":"仅排队中的任务有此字段"},"seed":{"type":"integer"},"command":{"type":"string","description":"服务端实际执行的完整命令行，用于复现"},"engineVersion":{"type":"string"},"descriptorMode":{"type":"string","enum":["rdkit","group_contribution"]},"geometryEnabled":{"type":"boolean"},"runtimeMs":{"type":"integer"},"summary":{"type":"object","properties":{"declined":{"type":"boolean"},"outcome":{"type":"string"},"targets":{"type":"integer"},"candidates":{"type":"integer"},"actionable":{"type":"integer"},"setAside":{"type":"integer"}}}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/api/health":{"get":{"tags":["public"],"summary":"服务与队列状态","responses":{"200":{"description":"ok"}}}},"/api/meta":{"get":{"tags":["public"],"summary":"实例元数据：版本、角色配额、算力档位可用性、知识库快照","responses":{"200":{"description":"ok"}}}},"/api/glossary":{"get":{"tags":["public"],"summary":"字段、参数、分数轴与拒答代码的口径说明","responses":{"200":{"description":"ok"}}}},"/api/knowledge":{"get":{"tags":["public"],"summary":"患者知识条目（含来源、核对日期与复核到期）","parameters":[{"name":"topic","in":"query","schema":{"type":"string","enum":["all","basics","testing","treatment","support","sideeffects","prevention"]}}],"responses":{"200":{"description":"ok"}}}},"/api/knowledge/ask":{"post":{"tags":["public"],"summary":"检索式问答。逐句绑定引用；命中不足时返回 status=abstained 拒答","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","maxLength":80}}}}}},"responses":{"200":{"description":"answered / abstained / emergency"}}}},"/api/research/tools":{"get":{"tags":["public"],"summary":"科研工具台的工具清单：数据源、许可、示例与输入说明","responses":{"200":{"description":"ok"}}}},"/api/research/query":{"post":{"tags":["research"],"summary":"调用一个科研数据源。需登录，每账号每分钟 60 次；format=tsv 时返回可下载的制表符文件","security":[{"bearerToken":[]},{"sessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tool","query"],"properties":{"tool":{"type":"string","example":"dossier","description":"工具 ID，见 /api/research/tools"},"query":{"type":"string","maxLength":200,"example":"KRAS"},"refresh":{"type":"boolean","description":"跳过缓存重新获取"},"format":{"type":"string","enum":["json","tsv"]}}}}}},"responses":{"200":{"description":"ok"},"400":{"description":"未知工具或检索式无效"},"401":{"description":"需要登录"}}}},"/api/careplan/form":{"get":{"tags":["public"],"summary":"确诊后导航的表单定义：癌种、分期、该癌种的关键检测指标与选项。全部为封闭词表，无自由文本字段","parameters":[{"name":"cancer","in":"query","schema":{"type":"string","example":"breast"},"description":"带上癌种时额外返回该癌种的指标清单"}],"responses":{"200":{"description":"ok"}}}},"/api/careplan":{"post":{"tags":["public"],"summary":"已确诊患者的报告解读与就医准备。不诊断、不推荐用药、不预测预后；服务端不保存任何提交内容","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cancer"],"properties":{"cancer":{"type":"string","example":"breast","description":"癌种标识，见 /api/knowledge/cancer-types"},"stage":{"type":"string","enum":["unknown","early","locally_advanced","metastatic","recurrent"]},"markers":{"type":"object","additionalProperties":{"type":"string"},"description":"键为指标 ID，值为该指标提供的选项之一；其他取值一律返回 400"},"treatments":{"type":"array","items":{"type":"string"}},"concerns":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"ok"},"400":{"description":"取值不在封闭词表内"}}}},"/api/knowledge/drugs":{"get":{"tags":["public"],"summary":"按癌种查已获批药物；不带 cancer 参数时返回药物清单总览与各癌种收录情况","parameters":[{"name":"cancer","in":"query","schema":{"type":"string","example":"breast"},"description":"癌种标识，见 /api/knowledge/cancer-types"}],"responses":{"200":{"description":"ok"},"404":{"description":"未收录该癌种"}}}},"/api/knowledge/drug":{"get":{"tags":["public"],"summary":"按中文通用名、英文通用名或商品名查单个药物","parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","maxLength":60,"example":"曲妥珠单抗"}}],"responses":{"200":{"description":"ok"},"404":{"description":"清单中没有这个名字"}}}},"/api/knowledge/cancer-types":{"get":{"tags":["public"],"summary":"已收录癌种清单与中文别名","responses":{"200":{"description":"ok"}}}},"/api/knowledge/refresh":{"post":{"tags":["auth"],"summary":"立即从 NCI 重建按癌种药物清单。需登录，每账号 30 分钟内最多 3 次","security":[{"bearerToken":[]},{"sessionCookie":[]}],"responses":{"200":{"description":"ok"},"429":{"description":"过于频繁"}}}},"/api/news":{"get":{"tags":["public"],"summary":"最新研究进展。按信息源抓取的癌症治疗与药物研发条目，含来源、发布时间与原文链接","parameters":[{"name":"category","in":"query","schema":{"type":"string","enum":["all","regulatory","trial","research","preprint","industry","guideline"]}},{"name":"source","in":"query","schema":{"type":"string"},"description":"信息源 ID，见 /api/news/sources"},{"name":"lang","in":"query","schema":{"type":"string","enum":["all","zh","en"]}},{"name":"q","in":"query","schema":{"type":"string","maxLength":60}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":60}}],"responses":{"200":{"description":"ok"}}}},"/api/news/sources":{"get":{"tags":["public"],"summary":"信息源清单与收录口径","responses":{"200":{"description":"ok"}}}},"/api/news/daily":{"get":{"tags":["public"],"summary":"某一天的进展日报存档","parameters":[{"name":"date","in":"query","required":true,"schema":{"type":"string","example":"2026-09-02"}}],"responses":{"200":{"description":"ok"},"404":{"description":"这一天没有日报"}}}},"/api/news/refresh":{"post":{"tags":["auth"],"summary":"立即抓取一轮信息源。需登录，每账号 10 分钟内最多 6 次","security":[{"bearerToken":[]},{"sessionCookie":[]}],"responses":{"200":{"description":"ok"},"429":{"description":"过于频繁"}}}},"/api/auth/register":{"post":{"tags":["auth"],"summary":"注册。邀请码或机构邮箱域名开通机构权限；其余邮箱默认直接开通注册科研用户并登录（开放注册关闭时进入人工审核）","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password","name","organization","purpose","accept"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":10,"description":"至少 10 位，含字母与数字"},"name":{"type":"string"},"organization":{"type":"string"},"purpose":{"type":"string","minLength":15,"description":"研究用途说明，随账号留存"},"inviteCode":{"type":"string"},"accept":{"type":"array","description":"register 闸门下每份文书的签署，取自 /api/meta 的 consents.documents","items":{"type":"object","required":["id","version"],"properties":{"id":{"type":"string"},"version":{"type":"string"}}}}}}}}},"responses":{"201":{"description":"created"},"400":{"description":"校验失败"},"409":{"description":"邮箱已注册"},"412":{"description":"文书未签署，响应含待展示的文书列表"}}}},"/api/auth/login":{"post":{"tags":["auth"],"summary":"登录，返回 HttpOnly 会话 Cookie","responses":{"200":{"description":"ok"},"401":{"description":"凭据错误"}}}},"/api/auth/token":{"post":{"tags":["auth"],"summary":"签发 API 令牌（仅显示一次）","security":[{"sessionCookie":[]}],"responses":{"201":{"description":"created"}}},"delete":{"tags":["auth"],"summary":"吊销当前 API 令牌","security":[{"sessionCookie":[]}],"responses":{"200":{"description":"ok"}}}},"/api/ingest":{"post":{"tags":["research"],"summary":"解析 VCF / MAF / TSV / CSV / JSON 为待确认的变异表","security":[{"bearerToken":[]},{"sessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["filename","content"],"properties":{"filename":{"type":"string"},"content":{"type":"string"}}}}}},"responses":{"200":{"description":"解析结果，含被跳过的行与原因"},"403":{"description":"权限不足"}}}},"/api/jobs":{"get":{"tags":["research"],"summary":"任务列表","security":[{"bearerToken":[]},{"sessionCookie":[]}],"responses":{"200":{"description":"ok"}}},"post":{"tags":["research"],"summary":"提交设计任务（异步，立即返回 job）","security":[{"bearerToken":[]},{"sessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profile"],"properties":{"profile":{"$ref":"#/components/schemas/Profile"},"tier":{"type":"string","enum":["fast","standard","deep"],"default":"fast"},"title":{"type":"string"},"note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"seed":{"type":"integer","default":20260812}}}}}},"responses":{"202":{"description":"已入队","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"401":{"description":"未认证"},"429":{"description":"超出配额或并发上限"}}}},"/api/jobs/{id}":{"get":{"tags":["research"],"summary":"任务详情","security":[{"bearerToken":[]}],"responses":{"200":{"description":"ok"}}},"patch":{"tags":["research"],"summary":"修改标题、备注与标签","security":[{"bearerToken":[]}],"responses":{"200":{"description":"ok"}}},"delete":{"tags":["research"],"summary":"删除任务及其变异数据","security":[{"bearerToken":[]}],"responses":{"200":{"description":"ok"}}}},"/api/jobs/{id}/result":{"get":{"tags":["research"],"summary":"完整机器可读结果","security":[{"bearerToken":[]}],"responses":{"200":{"description":"ok"}}}},"/api/jobs/{id}/report":{"get":{"tags":["research"],"summary":"下载 Markdown 报告","security":[{"bearerToken":[]}],"responses":{"200":{"description":"text/markdown"}}}},"/api/jobs/{id}/cancel":{"post":{"tags":["research"],"summary":"取消排队或运行中的任务","security":[{"bearerToken":[]}],"responses":{"200":{"description":"ok"}}}},"/api/analyze":{"post":{"tags":["research"],"summary":"同步分析（提交并等待完成）。长任务请改用 /api/jobs","security":[{"bearerToken":[]},{"sessionCookie":[]}],"responses":{"200":{"description":"完整结果"},"401":{"description":"未认证"}}}}}}