08 - API 设计（REST 契约）¶

本文是人读的 API 契约；机器可读的事实源是 packages/shared 中的 zod schema（类型、请求校验、错误码枚举均由它生成/校验）。二者冲突时以代码为准，并在同一 commit 内回改本文档。架构背景（鉴权形态、工作区隔离、通知路由、SSE 链路）见 03-architecture.md §8、§11。

1. 通用约定¶

2. 错误码¶

2.1 HTTP 状态码语义¶

2.2 错误码枚举（packages/shared 定义，与代码同源）¶

通用

文件与解析

发票 / 附件 / 批次

工作区 / 邮箱 / 通知

财务门户

3. 端点定义¶

3.1 认证与用户（better-auth 接管）¶

/auth/*、/admin/* 由 better-auth 处理（绕过 Nest 守卫与 zod 管道），错误结构为库自有格式，前端统一经官方 React client 调用。关键端点：

3.1.1 邀请码（平台建号）¶

开放注册关闭。新用户须有效 8 位邀请码（字符集 A-Z2-9 去 0O1I）。

错误码：INVITE_REQUIRED / INVITE_INVALID / INVITE_EXPIRED / INVITE_EXHAUSTED / INVITE_REVOKED / INVITE_NOT_FOUND。

set-password 在 better-auth 中是 serverOnly、不经 HTTP 暴露；OAuth-only 用户补「邮箱密码」登录方式走 Nest 桥接 POST /account/password（登录态，body { newPassword }，至少 8 位；要求 session 新鲜，默认 24h）。

3.2 工作区与成员（/workspaces，无需 X-Workspace-Id）¶

3.3 上传与解析任务¶

// POST /uploads 响应示例
{
  "items": [
    { "file": "滴滴出行.pdf", "accepted": true, "taskId": "0192a7f0-…" },
    { "file": "误删重传.pdf", "accepted": true, "restored": true },
    { "file": "旧发票.jpg", "accepted": false, "reason": "DUPLICATE_FILE" },
    { "file": "note.exe", "accepted": false, "reason": "FILE_TYPE_UNSUPPORTED" },
  ],
}

3.4 发票与附件¶

GET /invoices 列表项含只读 reminders 数组（docs/03 §5.5 决策层）：每项为 { ruleId, severity: info|warning|critical, title, message, provider }，由规则 provider（必要时叠加 System One 决策模型，provider 记为 rule/jev/clef）对金额、票面关键字段、分类、商品词与附件类型实时求值，不落库；无违规为空数组。列表项另含 requirements: { ruleId, status }[]，显示需人工处理的材料规则已持久化状态；历史发票尚未生成材料要求时可为空数组。休闲娱乐业或礼品的明确关键词直接产生 critical；模型仅对模糊休闲词给出待人工复核的 warning。

列表项含只读 invoiceKind（规范化票种，docs/12 §2.4；历史数据为 null），以及只读 attachments 数组（只读、排除软删）：{ id, attachmentType, originalName, sourceFileId, routes }，供发票库悬停预览截图/行程单；routes 为行程类附件的路段摘要数组 { city, origin, destination }[]（docs/12 §7，多段行程按段展开：非悬停用首段「城市-起点-终点」命名，悬停展示全部；无路线为空数组）。文件经 /files/workspace-files/:sourceFileId/download 受控下载。

GET /attachments 列表项含只读 previewAvailable（boolean）：该附件源文件是否已有服务端渲染的首页缩略图（PDF）。为 true 时前端经 /files/workspace-files/:sourceFileId/thumbnail 取图填卡片缩略图；为 false（非 PDF、渲染失败或历史数据未生成）时回退文件图标，PDF 仍可悬停/点击走原件预览。

3.5 批次与导出¶

3.6 邮箱账户 / 规则 / 通知 / 额度 / 统计¶

invoice_material 的通知正文包含工作区、发票号码、商户或票面内容、金额与问题；机器人 Webhook 对共享频道及 active owner/manager 的个人频道再附上传人姓名。普通个人频道与站内通知不显示上传人；NotificationDelivery 持久记录的仍是同一业务事件，投递时按频道生成可见正文。

个人 type=dingtalk 频道也接受 HTTPS connector.dingtalk.com/webhook/flow/<id> 自动化流程地址，其他 connector 路径不在白名单。此入口发送兼容钉钉机器人结构的 Markdown JSON，不使用旧机器人加签参数；签名密钥留空。流程配置使用 Text 参数格式、关键词匹配，以及后续「发送消息到该群组」的「源数据解析」。工作区/组织频道可按该明确地址自动识别协议。

钉钉 invoice_material 有详情链接时使用 msgtype=actionCard，载荷 actionCard={title,text,singleTitle:"查看详情",singleURL}；文字摘要和字段顺序与飞书材料卡片共用，不展示冗长票号，金额/问题加粗。没有详情链接时使用相同排版的 Markdown。旧机器人加签参数仍置于 URL；工作流入口同样可通过源数据解析接收机器人兼容消息。

将材料要求从 resolved/waived 改为 open 会增加 generation 并发送一条新事件，正文仍含完整票面摘要和源文件上传时间；问题说明包含人工重新打开动作及请求中填写的备注。对已经 open 的要求再次设 open 不重复创建事件。

通知深链接登录后保留目标工作区/发票，仅规范 UUID 被接受；无权限工作区不查询目标发票。详情支持已入批发票，软删/跨工作区仍返回 404。viewer 在详情只能读取，API 状态操作按上传者或管理者授权。待发送个人频道在投递时再次验证 active 工作区成员关系，失效频道记 skipped；机器人缺失成功业务码的响应按失败处理并重试。

finance_claim_progress 事件 payload 的 previousStatus/status 使用去除空状态字段和首尾空白后的组合值；活动/历史列表转换中的纯格式差异不产生事件，真实状态往返仍按 revision 创建独立事件。

飞书 invoice_material 的 Webhook 请求为 msg_type=interactive、card.schema=2.0，card.header.title 是带色标题「📌 发票材料提醒」，card.body.elements[0].text 以 text_size=heading-4 加粗「问题类型 · 发票内容」摘要，后续 lark_md 详情各行带语义表情，按工作区、商户、金额、具体问题、可见的上传人、源文件上传时间排序；问题显示完整规则理由，仅金额数值与问题加粗，不重复内容，也不展示票号。底部蓝色 primary 按钮「查看详情」通过 open_url 打开 /?workspaceId=<uuid>&invoiceId=<uuid>。首页验证工作区成员关系后定位发票；GET /invoices/:id 在 workspace context 下返回与列表项相同的 InvoiceView，跨工作区、软删或不存在返回 404。飞书财务提醒仍为 text，其他渠道不使用卡片。飞书签名字段 timestamp/sign 及投递成功判定与文本消息相同。 | GET | /invoices/:id/requirements | viewer | 五类材料要求及 open/resolved/waived 状态、解决人/时间、可选证明附件。 | | POST | /invoices/:id/evidence-attachments | 上传者或 manager+ | multipart file，上传 PDF/JPG/PNG（≤10MB）并直接挂载为当前发票的 proof 附件；返回 { attachmentId, originalName }。同一文件重复上传当前发票返回已有附件，文件已被其他记录使用则拒绝；不进入 OCR 解析队列。 | | PATCH | /invoices/:id/requirements/:ruleId | 上传者或 manager+ | 请求体含 status（resolved、waived 或 open）、可选 note 和 evidenceAttachmentId；证明附件必须已挂载到本工作区当前发票，写入状态历史。扫码验证与固定资产认定可人工完成或重新打开。 | | GET | /quota/summary | viewer | 各额度剩余/已用（口径见 02 文档） | | POST/PATCH/DELETE | /quota/plans | member / manager | 额度计划 CRUD（共享空间额度 manager+） | | GET | /quota/plans/:id/snapshots | viewer | 余额快照序列（M3） | | GET | /usage/summary | viewer | 平台用量汇总：按 provider/operation/unitKind 聚合，周期 YYYY-MM（docs/03 §5.7）；与报销额度无关 | | GET | /usage/events | viewer | 平台用量明细（分页，按工作区 RLS 隔离） | | GET/POST/PATCH/DELETE | /usage/entitlements | viewer / owner | 组织级用量配额 CRUD（写需 owner）：{ provider, period, includedUnits, overagePolicy } | | GET/PUT/DELETE | /ocr-credential | 登录用户 | 用户自备百度 OCR 凭据（docs/03 §5.7）：GET 返回凭据掩码 + 当月免费额度；PUT 保存（信封加密）；DELETE 删除；明文永不回显（红线 4） | | GET | /stats/dashboard | viewer | 页头指标：待报销总额与张数（同口径 parsed）、累计已解析数、未匹配附件数、队列积压 | | GET | /admin/dashboard | system admin | 管理大屏全局聚合（docs §5.8）：用户/租户、各 API 用量与成本、各功能使用；?days=7\|14\|30（默认 14）。跨组织只读，服务角色聚合 | | GET | /healthz | 无鉴权 | 探活，恒 200（不探测下游） |

3.7 角色能力速查（与 04 文档 §3 能力映射一致）¶

4. SSE 事件流¶

• GET /events（text/event-stream；session cookie 同域自动携带，无需 ticket）
• 订阅范围：按请求者成员关系过滤——仅下发其所属工作区的事件；个人通知（recipient_user_id）定向下发。worker PUBLISH {workspaceId | recipientUserId, type, payload} → api 订阅后扇出。
• 心跳：每 25s 注释帧 : ping（同时用于 Caddy/中间设备保活与断连探测）。
• 重连：浏览器 EventSource 自动重连；重连成功后前端补拉 /tasks、/notifications 兜底错过的事件。

event: task.updated
id: 0192a7f1-…
data: {"taskId":"0192a7f0-…","workspaceId":"0191…","status":"done","invoiceId":"0192…"}

: ping

5. 版本与变更管理¶

• /api/v1 内只做向后兼容变更：加字段、加端点、加错误码、加事件类型；不改既有字段语义、不删端点、不收窄角色。
• 破坏性变更 → 升 /api/v2，v1 至少保留一个大版本周期并在响应头 Deprecation/Sunset 标注。
• 契约变更流程：改 packages/shared 的 zod schema + 本文档 + 受影响端点的集成测试，三者同一 commit（对齐 AGENTS.md 文档同步规则）。