卓安Claw 接口清单 v0.1

版本：v0.1（草案，待评审）
日期：2026-11-06
适用范围：卓安Claw V1 云端 API、Agent 接口、同步接口、Webhook
依据：《业务流蓝图 v0.1》《角色与权限矩阵 v0.1》《数据对象与状态机 v0.1》《页面与交互清单 v0.1》《待确认事项总表 v0.1》
状态：需求讨论稿，不改代码；本文是接口契约草案，不是最终 OpenAPI

---

0. 结论摘要

1. 接口分 8 组：身份组织、客户线索、预约分诊接诊、案件诊疗、文档知识、商务财务、审批管理、Agent 与同步。
2. 所有接口走服务端权限校验；前端隐藏不算权限。
3. 所有写接口带 Idempotency-Key；关键对象带版本号/ETag，冲突返回 409。
4. 每个接口标注数据级别（A/B/C/D）和 TBD 编号；C 类接口默认不出私有云。
5. Agent 只通过受控工具接口访问业务数据，不直连数据库。
6. 同步采用增量变更 + WebSocket/SSE 推送；离线队列重放。
7. 接口未定的部分用 TBD-* 标记，开发前按《待确认事项总表》清零。

---

1. 接口规范

1.1 基础

项	约定
Base URL	https://{zhuoan-domain}/api/v1
协议	HTTPS；JSON；UTF-8
时间	ISO 8601，Asia/Shanghai
金额	整数分（amount_cents），币种 CNY
ID	字符串，全局唯一；不在 URL 暴露自增主键
版本	URL 版本 /v1；对象版本用 version / ETag
分页	page / page_size（默认 20，最大 100）或 cursor
排序	sort=field,-field
筛选	明确字段参数；禁止任意 SQL
请求 ID	X-Request-Id（客户端生成或服务端生成）
幂等	写接口带 Idempotency-Key；支付/审批/上传必须
并发	If-Match 或 X-Expected-Version；冲突 409
限流	按用户/租户；429 + Retry-After

1.2 认证与授权

• 认证：企业微信 OAuth/OIDC；自建账号兜底；Bearer Token；短期 access + refresh。
• Token claims：user_id、org_id、branch_id、dept_id、roles、scopes、session_id。
• 授权：服务端策略引擎；每次请求带 data_class 和 case_id（如适用）。
• 越权：403；不返回“存在但无权”的详情。
• 审计：所有写操作、敏感读、导出、Agent 调用。

1.3 响应格式

{
  "code": 0,
  "message": "ok",
  "data": {},
  "request_id": "req_...",
  "server_time": "2026-11-06T15:00:00+08:00"
}

错误：

{
  "code": 40301,
  "message": "无权访问该案件",
  "data": null,
  "request_id": "req_...",
  "details": { "reason": "case_team_required" }
}

1.4 错误码

HTTP	业务码	含义
400	40001	参数错误
401	40101	未登录/Token 失效
403	40301	无权限
404	40401	对象不存在或无权查看
409	40901	版本冲突
409	40902	重复提交/幂等冲突
422	42201	业务规则不满足（如归档五项未齐）
429	42901	限流
500	50001	服务内部错误

1.5 数据级别

• 请求/响应中的敏感对象带 data_class: A|B|C|D。
• C 类接口在网关层标记 c_only_local: true；外部模型调用一律拒绝。
• 文件下载 URL 为短期签名 URL；C 类带水印与审计。

---

2. 接口分组

2.1 身份与组织

方法	路径	用途	权限	数据级	TBD
GET	/auth/wecom/authorize	企业微信授权跳转	公开	A	D-01, G-05
POST	/auth/wecom/callback	换取 Token	公开	A	G-05
POST	/auth/refresh	刷新 Token	登录用户	A	—
POST	/auth/logout	退出/撤销会话	登录用户	A	—
GET	/me	当前用户与角色	登录用户	A	—
GET	/org/branches	分所列表	登录用户	A	—
GET	/org/departments	部门列表	登录用户	A	—
GET	/org/users	员工列表	管理者/HR	B	B-01
POST	/org/users/{id}/roles	分配角色/数据范围	总管理员	B	A-07, A-08
GET	/org/users/{id}/permissions	查看权限	管理者	B	—

2.2 客户与线索

方法	路径	用途	权限	数据级	TBD
GET	/leads	线索列表	客服/客户经理	B	—
POST	/leads	新建线索	客服	B	—
GET	/leads/{id}	线索详情	客服/客户经理	B	—
PATCH	/leads/{id}	编辑线索	客服/客户经理	B	—
POST	/leads/{id}/assign	分配	客服/主管	B	A-07
POST	/leads/{id}/pool	退回公海	客服/客户经理	B	—
POST	/leads/{id}/convert	转客户	客户经理	B	—
GET	/customers	客户列表	客户经理/谈案/承办	B	A-03
POST	/customers	新建客户	客服/客户经理	B	—
GET	/customers/{id}	客户详情	案件相关角色	B	—
GET	/customers/{id}/timeline	客户时间线	案件相关角色	B/C	—
POST	/customers/{id}/contacts	新增联系人	客户经理	C	—

2.3 预约、分诊、接诊

方法	路径	用途	权限	数据级	TBD
GET	/appointments	预约列表	客服/客户经理	B	C-01
POST	/appointments	新建预约	客服	B	C-01
PATCH	/appointments/{id}	改期/取消	客服/客户经理	B	C-01
POST	/appointments/{id}/check-in	签到	客服	B	—
GET	/triage	分诊看板	客服主管/管理者	B	C-02
POST	/triage/{id}/recommend	推荐律师	客服主管/管理者	B	C-02, A-07
POST	/triage/{id}/confirm	确认分诊	客服主管/管理者	B	C-02, A-02
GET	/encounters	接诊队列	谈案/承办	C	C-03
POST	/encounters	新建接诊	谈案/承办	C	C-03
PATCH	/encounters/{id}	更新接诊记录	谈案/承办	C	C-03
POST	/encounters/{id}/complete	完成接诊	谈案/承办	C	C-03

2.4 案件与诊疗

方法	路径	用途	权限	数据级	TBD
GET	/cases	案件列表	案件相关角色	B	A-03, A-04
POST	/cases	建案	承办/管理者	B	A-03, A-04
GET	/cases/{id}	案件详情	案件团队	C	A-04
PATCH	/cases/{id}	编辑案件	主办/管理者	C	A-04
POST	/cases/{id}/stage	推进阶段	主办/管理者	C	A-04
POST	/cases/{id}/members	添加团队成员	主办/管理者	C	B-06
POST	/cases/{id}/conflict-check	冲突检索	承办	C	A-02
GET	/cases/{id}/diagnostics	检查单列表	案件团队	C	C-03
POST	/cases/{id}/diagnostics	开检查单	承办	C	C-03
POST	/diagnostics/{id}/report	回传检查报告	承办	C	C-03
GET	/cases/{id}/diagnosis	诊断结论	案件团队	C	C-05
POST	/cases/{id}/diagnosis	保存诊断（新版本）	承办/谈案	C	C-05
GET	/cases/{id}/plans	方案列表	谈案/承办	C	A-01, C-06
POST	/cases/{id}/plans	新建方案	谈案/承办	C	A-01, C-06
POST	/plans/{id}/confirm	客户确认/锁定版本	谈案/承办	C	C-06
GET	/cases/{id}/care-path	办案路径	案件团队	C	C-04
POST	/cases/{id}/care-path/items/{itemId}	勾选/变异	承办	C	C-04
GET	/cases/{id}/logs	办案动态	案件团队	C	—
POST	/cases/{id}/logs	新增动态	承办	C	—
GET	/cases/{id}/reviews	三级复核	案件团队/合伙人	C	C-04
POST	/cases/{id}/reviews	发起复核	承办	C	C-04
GET	/cases/{id}/consultations	会诊	案件团队/合伙人	C	C-04
POST	/cases/{id}/consultations	发起会诊	承办/管理者	C	C-04
POST	/cases/{id}/closing	申请结案	承办	C	A-05
POST	/cases/{id}/archive	申请归档	承办/管理者	C	A-05
POST	/cases/{id}/quality-review	发起质评	管理者	C	A-06
POST	/cases/{id}/followups	新建随访	客户经理	B	—

2.5 文档与知识

方法	路径	用途	权限	数据级	TBD
POST	/documents	上传文件（初始化）	按对象权限	C	E-08, G-09
POST	/documents/{id}/versions	上传新版本	按对象权限	C	—
GET	/documents/{id}	文件元数据	按对象权限	C	—
GET	/documents/{id}/download-url	短期下载 URL	按对象权限	C	B-03
GET	/knowledge/docs	知识列表	按知识权限	A/B	—
POST	/knowledge/docs	发布知识	管理者/授权角色	A/B	—
GET	/knowledge/search	知识检索	按知识权限	A/B/C	G-08
POST	/templates/{id}/generate	模板生成文书	谈案/承办	C	—

2.6 商务与财务

方法	路径	用途	权限	数据级	TBD
GET	/contracts	合同列表	客户经理/谈案/财务	B	—
POST	/contracts	新建合同	谈案	B	E-04
POST	/contracts/{id}/sign	发起签署	谈案	B	E-04, E-05
GET	/payments	回款列表	客户经理/财务	B	—
POST	/payments	登记回款	客户经理	B	C-07
POST	/payments/{id}/approve	财务审核	财务	B	C-07
POST	/refunds	登记退款	客户经理	B	C-07
POST	/refunds/{id}/approve	财务审核	财务	B	C-07
POST	/invoices	发票登记	财务	B	E-06
POST	/finance/import/preview	Excel 导入预览	财务	B	E-06
POST	/finance/import/commit	Excel 导入提交	财务	B	E-06
GET	/finance/reconciliation	导入对账	财务	B	E-06

2.7 审批与管理

方法	路径	用途	权限	数据级	TBD
GET	/approvals	审批列表	按角色	B	E-01, E-02
POST	/approvals	发起审批	按角色	B	E-01
POST	/approvals/{id}/actions	通过/驳回/撤回	审批人	B	E-01
GET	/admin/dictionaries	字典	管理者	A/B	—
POST	/admin/dictionaries	维护字典	总管理员	A/B	—
GET	/admin/triage-rules	分诊规则	管理者	B	C-02
POST	/admin/triage-rules	维护分诊规则	总管理员	B	C-02
GET	/admin/care-path-templates	办案路径模板	管理者	B	C-04
POST	/admin/care-path-templates	维护模板	总管理员	B	C-04
GET	/admin/audit-logs	审计日志	总管理员/合规	C	B-04
GET	/admin/model-policy	模型/出域策略	总管理员	B	B-02, E-09
POST	/admin/model-policy	维护策略	总管理员	B	B-02, E-09

2.8 Agent 与同步

方法	路径	用途	权限	数据级	TBD
POST	/agent/context	获取案件上下文	继承用户	A/B/C	G-07
POST	/agent/tools/{tool}	调用工具	继承用户	A/B/C	G-07
GET	/agent/runs/{id}	查看 Agent 运行	本人/管理者	B/C	—
POST	/agent/runs/{id}/confirm	确认草稿	本人	B/C	—
GET	/agent/events	事件订阅（SSE）	登录用户	B	D-04
POST	/agent/knowledge/search	知识检索	继承用户	A/B/C	G-08
GET	/sync/changes	增量变更	登录用户	B/C	G-06
POST	/sync/push	客户端变更上传	登录用户	B/C	G-06
GET	/sync/conflicts	冲突列表	登录用户	B/C	G-06
POST	/sync/conflicts/{id}/resolve	解决冲突	本人/管理者	B/C	G-06

2.9 Webhook

方法	路径	用途	来源	TBD
POST	/webhooks/wecom	企业微信回调	企业微信	E-07
POST	/webhooks/esign	电子签回调	CA 厂商	E-04
POST	/webhooks/oa	OA 迁移/同步回调	OA	E-02
POST	/webhooks/model	模型回调（异步）	模型网关	G-07

---

3. Agent 工具契约

工具	输入	输出	写操作	确认	权限
crm.get_context	case_id/customer_id	上下文包（摘要、时间线、待办、清单、文档索引）	否	—	继承用户
crm.create_followup_draft	customer_id, content, at	草稿 ID	草稿	人确认	客户经理
crm.create_talk_draft	customer_id, transcript	谈案记录草稿	草稿	人确认	谈案/客户经理
crm.update_stage_draft	case_id, target_stage, summary	变更建议	草稿	人确认	主办/管理者
crm.create_plan_draft	case_id, product, facts	方案草稿	草稿	人确认	谈案/承办
crm.generate_document	template_id, case_id, fields	文书草稿	草稿	人确认	谈案/承办
crm.check_conflict	persons[]	风险结果	否	—	承办
crm.list_checklist	case_id	清单项	否	—	案件团队
crm.mark_checklist_draft	case_id, item_id, status, reason	勾选建议	草稿	人确认	承办
crm.create_closing_draft	case_id	结案报告草稿	草稿	人确认	承办
crm.query_metrics	scope, period	指标结果	否	—	管理者/财务

工具铁律：Agent 不审批、不签字、不付款、不物理删除；所有写操作默认草稿。

---

4. 事件类型

事件	触发	订阅方
lead.assigned	线索分配	客户经理、主管
appointment.created	新建预约	客服、谈案
triage.confirmed	分诊确认	谈案、承办
encounter.completed	接诊完成	承办、管理者
diagnosis.confirmed	诊断确认	承办、谈案
plan.confirmed	方案确认	谈案、承办、财务
contract.signed	合同生效	客户经理、财务
payment.approved	回款通过	客户经理、财务、承办
case.stage_changed	案件阶段推进	案件团队、管理者
checklist.overdue	清单逾期	承办、管理者
closing.approved	结案通过	承办、管理者、财务
archive.completed	归档完成	客户经理、管理者
followup.due	随访到期	客户经理

---

5. TBD 对照

接口组	相关 TBD
身份组织	D-01, G-05, B-01, A-07, A-08
客户线索	A-03, A-07
预约分诊接诊	C-01, C-02, C-03, A-02
案件诊疗	A-03, A-04, A-05, A-06, C-03, C-04, C-05, C-06
文档知识	B-03, E-08, G-08, G-09
商务财务	C-07, E-04, E-05, E-06
审批管理	E-01, E-02, E-03, B-04
Agent 同步	B-02, D-04, E-09, G-06, G-07
Webhook	E-02, E-04, E-07, G-07
客户小程序	H-01, H-02, H-03, H-05, H-06, H-09, H-10, H-11

---

6. 下一步

1. 先清 B0 的 13 项，接口才能定稿；尤其是 A-01、A-03、A-04、C-01、D-01、D-02、D-05、E-01、E-02、F-01、G-01、G-10、A-02。
2. B0 清零后，把本清单升级为 OpenAPI 草案，进入技术设计。
3. B1/B2 项按接口组逐步清零；未定项在代码/配置中标注 TBD。
4. 仍不改代码。

---

---

7. 补充：客户小程序接口（2026-11-06 新增）

方法	路径	用途	权限	数据级	TBD
POST	/portal/auth/wechat	微信登录换 session	公开	A	H-01
POST	/portal/bind/qr	扫码绑定	客户	B	H-02, H-12
POST	/portal/bind/contract	合同号绑定	客户	B	H-02
POST	/portal/bind/verify-otp	短信验证	客户	B	H-02
GET	/portal/cases	我的案件	客户	B	H-03
GET	/portal/cases/{id}/progress	案件进度	客户	B	H-03
GET	/portal/cases/{id}/updates	公开动态	客户	B	H-03
GET	/portal/cases/{id}/documents	共享文书	客户	C	H-05, H-10
GET	/portal/documents/{id}/download-url	下载（水印/短期）	客户	C	H-10
GET	/portal/messages	通知	客户	B	H-09
POST	/portal/messages	留言/联系请求	客户	B	H-08
GET	/portal/profile	我的/绑定	客户	B	H-11
POST	/portal/unbind	解绑	客户	B	H-11
POST	/admin/cases/{id}/publication	设置公开档位	管理者	B	H-03
POST	/admin/cases/{id}/updates	创建客户版动态	承办/客户经理	C	H-05
POST	/admin/updates/{id}/publish	发布	管理者	C	H-05
POST	/admin/updates/{id}/withdraw	撤回	管理者	C	H-05
POST	/admin/documents/{id}/share	共享文书	管理者	C	H-05, H-10
GET	/admin/portal-bindings	绑定列表	客户经理/管理者	B	H-06
POST	/admin/portal-bindings/{id}/revoke	撤销绑定	管理者	B	H-06
GET	/admin/portal-access-logs	访问审计	管理者	C	H-10

---

本文为接口契约草案，不构成开发承诺；最终以 OpenAPI 与评审纪要为准。