bid-doctor/docs/architecture/api-design.md

接口契约 v0.1

依据：架构 v0.3（§3.4 任务、§3.11 会话、§4.2 前端、§5.2 桌面约束）、data-model.md、03 功能需求、MVP 原型 v0.2 的 13 个页面。 契约文件：openapi.yaml（OpenAPI 3.1，64 个路径、81 个操作、81 个数据结构）。 范围：用户端（网页版 / 桌面版）的 MVP 主流程。运营后台是独立应用，接口另行定义。 API1–API5 已于 2026-11-03 全部按建议确认（docs/decisions.md），见 §9。

0. 结论速览

• 一份契约，两端同时开发：前端用 openapi-typescript 从 openapi.yaml 生成类型，用 mock 服务器先跑；后端按它写 Pydantic 模型。后端骨架搭好后，改为以 FastAPI 生成的文档为准（API1）。
• 两种鉴权，同一套接口：网页版用 cookie，并加 CSRF 头；桌面版用 Bearer 令牌（架构 §5.2 第 3 条）。
• 错误统一用 RFC 9457 格式，带一个稳定的 code，前端按 code 判断，不解析文案（§5）。
• 会扣点的接口都要带「预期扣点」：前端把告诉用户的扣点数传上来，服务端算的和它不一致就拒绝，不扣点（API4）。这样用户看到的扣点说明和实际扣点永远一致（红线 9）。
• 进度用事件流推送，轮询兜底：事件只是「有变化」的提示，以资源的 GET 结果为准。事件流用 fetch 读取，不用浏览器的 EventSource，因为 EventSource 带不了 Bearer 头（API2）。
• 大文件分片上传、断点续传，和平台无关（架构 §5.2 第 7 条）。格式、加密、页数在上传完成时就拦截，不建任务、不扣点（FR-M2-01）。

1. 基本约定

事项	约定
地址	{服务器}/api/v1。网页版同源；桌面版用用户选择的服务器地址
格式	JSON，字段名用 snake_case（和数据库、Python 一致）；生成的 TypeScript 类型也是 snake_case，不做转换
编号	UUID 字符串
时间	RFC 3339，带时区。显示格式（「11月20日 09:30」）由前端处理（Q10）
金额	字符串，如 "1280000.00"，单位元，避免浮点误差
枚举	英文小写加下划线，值和数据库的 CHECK 约束一致；中文显示名由前端维护
列表	一个项目内的列表（清单项、问题、文档、分包）一次返回全部，最多几百条；跨项目、会一直增长的列表（项目、额度流水、通知）用游标分页：?cursor=&limit=，返回 next_cursor
动作	不是增删改的操作，用 POST /资源/{id}/动作，例如 /findings/{id}/resolve、/parse-jobs/{id}/cancel
版本	路径里的 v1。同一版本内只加字段、不删不改；前端忽略不认识的字段和枚举值

2. 鉴权与会话

	网页版	桌面版
登录后	服务端设置 cookie bd_session（HttpOnly、Secure、SameSite=Lax）和 bd_csrf（前端可读）	响应体里返回 token，只返回这一次；存进系统钥匙串
每个请求	自动带 cookie；写操作（POST、PUT、PATCH、DELETE）还要带请求头 X-CSRF-Token，值等于 bd_csrf	Authorization: Bearer <token>
退出	POST /auth/logout 吊销会话	同左

• 登录、注册都用 client_kind 声明是哪一端。
• 异地多设备并发登录（FR-M6-04）：同一账号已有其他设备在线时，登录返回 409 concurrent_session，附在线设备列表（设备、IP 归属地、最近活跃时间）；用户确认后带 force: true 重发，其他设备被挤下线（API3）。被挤下线的设备下一个请求收到 401 session_revoked，reason: concurrent_login，前端提示「你的账号在其他设备登录」。
• 发验证码不泄露注册状态：号码有没有注册，POST /auth/sms-codes 都返回 202。验证码校验通过后，登录接口才会告诉用户「这个号码还没注册」。
• 权限点：GET /me 返回当前用户的权限点列表（AR12），前端只用它决定按钮显示与否，服务端每个接口照样检查。MVP 只有所有者，拥有全部权限点。

3. 主流程和接口的对应

步骤（原型页面）	接口
注册 / 登录（login）	POST /auth/sms-codes → POST /auth/register 或 POST /auth/login → GET /me
工作台（workbench）	GET /projects，每行带「下一步」next_action、就绪状态、正在跑的任务；GET /quota 给顶栏额度
新建项目、上传招标文件（project-new）	POST /projects → POST /uploads → PUT /uploads/{id}/parts/{n} × N → POST /uploads/{id}/complete → POST /projects/{id}/documents → POST /documents/{id}/parse-jobs（预扣 1 次）
解析进度（parsing）	GET /events 收 job.progress；断线时轮询 GET /parse-jobs/{id}；POST /parse-jobs/{id}/cancel；失败后重试再调一次 POST /documents/{id}/parse-jobs
选包（lots）	GET /projects/{id}/lots → PUT /projects/{id}/bidding-lots；手工增删改分包
读标（checklist）	GET /projects/{id}/checklist、GET /projects/{id}/checklist/items；原文查看器用 GET /documents/{id}/file?variant=normalized、GET /documents/{id}/pages；选句补出处用 GET .../pages/{n}/sentences → POST /projects/{id}/citations；修改、采纳、删除、恢复、补遗更新、修改记录、确认清单
上传投标文件、发起检查（bid-check）	上传同上，role = bid_volume；GET /projects/{id}/check-preview 给出扣点说明 → POST /projects/{id}/check-runs
查标（results）	GET /check-runs/{id}、GET /check-runs/{id}/findings → POST /findings/{id}/resolve、/reopen（U 键）、POST /check-runs/{id}/findings/bulk-resolve；需人工核对用 GET/PUT /projects/{id}/manual-checks；POST /feedback
报告（report）	POST /check-runs/{id}/reports → 事件 report.ready → GET /reports/{id}/file
项目概览（project）	GET /projects/{id}、基本信息字段的修改和补遗确认、GET /projects/{id}/documents、GET /projects/{id}/check-runs、POST /projects/{id}/transitions（递交 / 归档及撤销）、DELETE /projects/{id}
额度（quota）	GET /quota、GET /quota/entries、GET /plans、POST /activation-requests
资质库（qualifications）	/qualifications 的增删改；附件先上传，再 POST /qualifications/{id}/files

4. 几个关键设计

4.1 扣点：预览 + 预期扣点

• 发起检查前，前端调用 GET /projects/{id}/check-preview。服务端按 01 §4 和 P1 算出这次的计费方式（扣点 / 24 小时内免扣 / 免费版）、扣几次、免扣窗口到什么时候，以及能不能开始（没有招标文件、额度用完等）。按钮旁的扣点说明就用这份数据。
• 发起时带 expected_charge。如果服务端当下算的和它不一致（比如用户停在页面上时，24 小时窗口刚好过了），就返回 409 billing_changed，附最新的预览，不扣点。前端刷新说明，让用户再点一次。
• 解析同理：POST /documents/{id}/parse-jobs 也接受 expected_charge。
• 重复点击不会重复扣点：同一份文档、同一个项目同时只能有一个在跑的任务（数据库部分唯一索引），重复发起返回 409 job_already_running，附正在跑的任务编号。

4.2 任务与事件

• 解析任务、检查批次、报告生成都是后台任务：发起接口立刻返回任务对象（status = queued）。
• GET /events 是当前用户的事件流：job.progress、job.finished、report.ready、notification.created、quota.changed、project.changed。
  • 每条事件带 id。重连时带上 Last-Event-ID，服务端尽量补发；补不了（Valkey 里的缓冲已过期）就发 resync，前端重新拉取当前页面的数据。
  • 事件可能丢、可能重复。前端收到后只做一件事：让 TanStack Query 里对应的查询失效、重新请求。
• 断线兜底：页面上有进行中的任务时，每 5 秒轮询一次任务的 GET。
• 失败原因 error 只给用户看的文字和 refunded（是否已退回额度），不含文档内容和内部堆栈。

4.3 上传

1. POST /uploads：传文件名、大小和用途（项目文件或资质附件），可选传 sha256。超出套餐的单文件大小上限，直接返回 409，detail 写明上限值。
2. PUT /uploads/{id}/parts/{n}：逐片上传，片大小由服务端决定。重复上传同一片会覆盖，所以断点续传时可以先 GET /uploads/{id} 看收到了哪些片。
3. POST /uploads/{id}/complete：合并分片，按文件头识别真实格式，读取页数。不支持的格式、加密、损坏、电子投标平台的加密格式、页数超限，都在这里返回 422。扩展名和真实格式不一致时只做提示（extension_mismatch，07 F2）。
4. 挂到项目上：POST /projects/{id}/documents。投标分册重新上传时填 replaces_document_id，生成新版本。

上传会话 24 小时后过期，没挂到项目上的文件自动清理。分片经过 api 写入对象存储；本地磁盘和 S3 用同一套接口，私有化环境也一样。

4.4 原文和出处

• 原文用 pdf.js 渲染：GET /documents/{id}/file?variant=normalized 返回短时有效的下载地址，pdf.js 直接加载，不需要带鉴权头（架构 §5.2 第 5 条）。
• 出处对象自带原句、页码和坐标框，阅读器直接画高亮，不用再取文字层。normalized_sha256 和文档的哈希不一致时不画（data-model §5.1）。
• 人工补出处：在阅读器里选中句子（GET /documents/{id}/pages/{n}/sentences），再 POST /projects/{id}/citations 建一条出处，最后把它挂到清单项上（采纳或替换出处）。

4.5 修改清单和处理问题

• 并发修改：清单项和项目字段的 GET 返回 ETag。修改时带上 If-Match，版本不一致返回 412。MVP 只有一个人，这个头是选填的；团队版上线后改为必填。
• 改清单项：PATCH 只传要改的字段。服务端把改过的字段记进 edited_fields，AI 原值保留在 ai_values 里。已确认的清单被修改后回到草稿（FR-M2-08）。
• 处理问题：
  • resolve 返回问题本身和项目最新的就绪状态（open_fatal_count），项目头直接更新，不用再请求一次；
  • 忽略必须写原因，致命问题「确认无误」也必须写说明（U4），否则返回 422 note_required；
  • 只有最近一次检查的问题可以处理，历史批次返回 409 run_superseded；
  • 批量处理只限「提示」级，混进了别的级别就整批拒绝，返回不符合的问题编号。
• 已递交、已归档的项目只读：所有修改接口都返回 409 project_read_only。撤销递交或撤销归档之后才能改（FR-M6-02）。

4.6 不在接口里出现的东西

对照产品红线：

• 没有任何接口返回或接收「建议报价」。报价相关的字段只有招标文件写明的限价，以及从投标文件里读到的金额（红线 6）。
• 问题、报告的字段里没有「通过 / 合格」这类结论字段；就绪状态只用于提示，不阻止导出和递交（红线 3、4）。
• 没有用户可以填的模型地址或模型选择（T1）。

5. 错误

所有错误都用 application/problem+json：

{
  "type": "about:blank",
  "title": "额度不足",
  "status": 409,
  "code": "quota_exhausted",
  "detail": "本期解析额度已用完。专业版续费或加量请联系客服。",
  "request_id": "req_01J…"
}

• title 和 detail 是给用户看的中文；前端按 code 决定怎么处理，不解析文案。
• 字段校验错误：422 validation_failed，errors 里逐个字段列出 field（如 spec.tech_param.value）、code、message。
• 访问别的企业的资源一律返回 404，不返回 403（架构 §3.3）。
• request_id 也放在响应头 X-Request-ID 里，用户反馈问题时可以报这个编号。

HTTP	code	含义
401	unauthenticated session_expired session_revoked	没登录、会话过期、被吊销（含被挤下线）
403	csrf_failed forbidden	CSRF 头不对；没有这个权限点
404	not_found phone_not_registered
409	concurrent_session	已有其他设备在线（API3）
409	quota_exhausted billing_changed plan_limit_exceeded	额度、计费、套餐限制
409	job_already_running job_finished	任务状态冲突
409	project_read_only invalid_transition run_superseded item_not_pending document_in_use 等	业务状态不允许这个操作
412	precondition_failed	If-Match 版本不一致
422	validation_failed note_required citation_required bulk_only_hint	输入不合法
422	file_format_unsupported file_encrypted file_corrupted bid_file_platform_encrypted upload_checksum_mismatch	上传的文件有问题，不扣点
429	rate_limited	验证码、登录太频繁；响应头带 Retry-After
500 / 503	internal_error service_unavailable	不扣点；任务类的会自动退回

完整的错误码清单在每个接口的响应说明里；写后端时收进 core/errors.py，作为唯一的定义来源。

6. 契约里没写死、留给实现的

• 分片大小（建议 8MB）、上传会话的过期时间、下载地址的有效期（建议 5 分钟）；
• 列表的默认排序以外的排序方式；
• 事件缓冲多长时间（建议 10 分钟）；
• next_action 的具体推导规则，写在 project 模块里，和原型工作台的「下一步」一致。

7. 以后的版本怎么接

以后要加的	接口上的准备
团队版：项目成员、角色	ProjectDetail.members 已经有了；以后加 /projects/{id}/members 的增删改，If-Match 改为必填
一人多企业、切换企业	POST /auth/switch-tenant 换一个绑定到另一个成员身份的会话（§3.14）
飞书、企业微信、SSO 登录	/auth/{provider}/start 和 /auth/{provider}/callback，登录结果的格式不变
线上支付	/orders 一组新接口，不改额度接口
标书生成（M4）、查重（M5）	新的任务类型，复用任务、事件、扣点预览这套模式

8. 怎么用这份契约

• 前端：packages/api-client 用 openapi-typescript 从 openapi.yaml 生成类型，用 openapi-fetch 调用。后端还没好时，用基于契约的 mock 服务器（如 Prism）开发页面。
• 后端：按契约写 Pydantic 模型和路由。集成测试里比对 FastAPI 生成的文档和契约，有差异就失败。
• 契约检查：现在只做了结构检查（引用都能解析、operationId 不重复、路径参数都声明了、必填字段都存在）。工程骨架里在 CI 加上 Redocly 或 Spectral 的完整校验。

9. 决策（已确认）

#	事项	结论
API1	契约以谁为准	现在以 openapi.yaml 为准，前后端据此同时开发。后端骨架搭好后，改为以 FastAPI 生成的文档为准：把生成结果存成 openapi.json 提交到仓库，CI 检查它是不是最新的；契约有改动时在合并请求里就能看到。之后 openapi.yaml 不再维护，和 schema-draft.sql 的处理方式一样
API2	事件流怎么读	用 fetch 读 SSE 流，不用 EventSource。理由：EventSource 带不了 Authorization 头，桌面版用不了
API3	异地多设备并发登录怎么「提示并限制」	新设备登录时提示「账号已在其他设备登录」，用户确认后挤掉旧设备。另一种做法是旧设备不退出就不让新设备登录，但用户换了电脑、忘了退出时就登不上了
API4	扣点说明和实际扣点不一致时	拒绝并刷新说明，不扣点（§4.1）。用户看到「不扣点」，结果却扣了，这种情况必须杜绝
API5	报告怎么生成	后台生成，完成后推送事件。用 Chromium 生成 PDF 要几秒到十几秒，不放在请求里同步做（架构：api 只做短事务）

10. 实现进度（工程骨架）

骨架阶段只实现了「上传 → 解析 → 显示清单」这条最小链路要用的接口。server/tests/test_contract.py 保证已实现的接口都在契约里；契约里还没实现的，按模块列在这里，实现一个划掉一个。

模块	已实现	还没实现
登录与账号	发验证码、注册、登录（含挤下线确认）、退出、GET /me	修改显示名、在线会话列表和下线、注销账号
额度与套餐	GET /plans、GET /quota	额度流水、开通申请
项目	列表（不含筛选和分页）、新建、详情（含解析出的基本信息字段和关键日期）	基本信息字段修改与补遗确认、状态变更、删除、分包的增删改和选包
上传与文档	分片上传全套、挂到项目、文档列表和详情、逐页摘要、一页的句子、签名下载、发起解析、解析进度、取消、人工建出处	删除文档
清单	清单概况（含确认人、删除数、按类别计数）、清单项列表（按区域、类别筛选，可含已删除）、清单项详情（ETag）、修改（If-Match 选填）、采纳、删除恢复、人工新增、替换出处、修改记录、确认清单、版本	补遗更新确认（等补遗解析）；列表的 lot_scope（等选包）
检查、报告、资质	—	全部（查标阶段）
通知与事件	事件流、通知列表	标为已读、反馈

读标修改类接口的实现约定（2026-11-03）：

• 修改记录来自审计：每次修改都写一条审计事件，history 直接读它们。解析不逐条写审计（一份文件几百条），所以 AI / 规则提取的那一刻由接口在最后补一条 checklist_item.extract，操作人是「系统」。
• AI 原值：人工第一次改某个字段时，把改前的值记在 ai_values.original 里，重新解析也保留，界面可以显示「AI 原为……」。
• 重新解析不推翻人工决定：已删除（丢弃）的条目对上了就保持删除；采纳过的留在正式清单；人工补过或换过出处的（edited_fields 含 citations）不被这次解析的出处覆盖。
• 确认清单：只收正式清单里未删除的条目；内容哈希和上一个确认版本一样时复用上一版，不新增版本号；已确认又重复点确认不写审计。