案件云 Open API 集成 V2.0

通过 PAT Token 授权，用自然语言操作案件云。详细 API 文档见 references/api-reference.md。

前置配置

1. 用户在 OA「个人设置 > AI管理」生成 PAT Token（以 law086_pat_ 开头）
2. 将 API_BASE_URL 和 PAT_TOKEN 写入 .env 文件（与 SKILL.md 同级）
3. 若 Token 为占位值，提示用户替换

数据可见范围

• 个人空间：本人全部数据。
• 团队/律所管理员或拥有者：本 org 下全部数据。
• 团队/律所普通成员：只能看自己参与的数据。
• 律所拥有者（顶层律所 org + OWNER 角色，全所范围始终开启）：可见/可写范围自动展开为「顶层律所 + 所有直接子团队 org」（扁平一层）。
  • 读端点：全所可见（cases/clients/projects/finance/dashboard/search/calendar/team/records/contracts 等）。
  • 编辑端点（PATCH/PUT/上传）：可跨子团队编辑/上传全所任意记录（保留记录自身 org_id，编辑不改归属）。
  • 新建端点（POST /cases、/clients、/projects、/calendar、/contracts）：支持可选请求参数 org_id（hashid）把新记录归属到本所内任意子团队；不在全所集合则报错「目标组织不在本所范围」；未传默认 PAT 绑定 org。
  • 非 owner 的 PAT 行为零变化（写端点传非自身 org 会报错「目标组织不在本所范围」）。
  • 组织结构目前仅支持扁平一层，多级团队递归为二期；跨子团队 host/assit 改派未开放（指案件层面主办/协办律师的改派，需到 OA 网页端；待办层面 owner 已支持创建时指定主办人，见下方"主办人指派")。
  • 日程/待办跨子团队关联（owner 专属）：owner 给子团队案件推送待办/办案记录（POST /calendar type=1，或 PUT /calendar/{id} 改关联案件）时，可不传 org_id，后端会自动把待办归属到案件所在子团队（POST）；PUT 改关联案件时记录自身 org 不变，但允许关联到全所任意子团队案件。协办人(assit)校验按案件自身 org（属于案件所在子团队才合法）。非 owner 维持原严格校验（关联案件必须 ∈ 自身 org），行为不变。
  • 主办人指派（owner 专属）：律所拥有者通过 POST /calendar 推送待办/办案记录时，可指定主办人（huser），让被指派的员工成为待办主办并能在「我的待办」看到。主办人确定优先级：
    1. 传了 huser（hashid，来自 GET /team/members）→ 解码并校验属于目标 org 后使用
    2. 未传 huser 但传了 assit → huser = assit 解码后的第一个员工
    3. 都没传 → 回落调用者本人（add_uid 始终 = 调用者，记录"谁派发的"）
    • 非 owner：忽略传入的 huser，主办人恒为调用者本人（即使传了 huser 也会被丢弃）
    • 个人空间（org_id=0）：主办人恒为自己，不允许指定他人
    • 派活推荐用 huser 精确指定主办（与 PUT /calendar/{id} 行为一致）；assit 回归"协办"本职。owner 派活后不把 owner 加入 assit（owner 靠全所视图查看）
    • 同时传 huser 和 assit 时，huser 参数优先；assit 多人时取第一个作为兜底主办

更新 Skill

更新只需 git pull，不要删除重装（会丢失 .env 中的 PAT Token 配置）。详见 README.md。

API 调用

python3 scripts/api.py   [JSON_BODY]
# 示例：
python3 scripts/api.py GET "/cases?keyword=张三&g_status=1"
python3 scripts/api.py POST /calendar '{"title":"开庭","htime":"2026-05-10 14:00","endtime":"2026-05-10 15:00","type":0}'

脚本自动处理认证、中文编码和响应解析。所有时间使用北京时间 (CST, UTC+8)。

响应与错误处理

校验失败处理

当返回 code:"1"（业务错误）时，后端 msg 会返回字段级、可读性强的具体原因（如 "案件类型无效，只允许 1-5"、"当事人名称不能为空"、"案由长度不能超过 64"）。处理流程：

1. 读取 msg，定位到出错的字段或参数
2. 按提示修正对应字段（如枚举值不在合法范围就替换为合法值、必填项缺失就补全）
3. 修正后直接重试，不要把原始失败原因直接抛给用户

端点速查

参数和响应字段的详细说明见 references/api-reference.md。

关键概念

日程与办案记录的关系

日程和办案记录是同一张表（sr_record）的不同视图。所有创建和更新统一走 calendar 端点：

• POST /calendar — 创建日程/待办/办案记录（唯一入口）
• PUT /calendar/{id} — 更新任何记录（状态、人员、时间、阶段等，统一入口）
• GET /calendar — 查看日程和记录列表（按日期范围，或按 type+linkid 查案件/项目/客户记录）
• GET /records/{id} — 按ID直接查单条记录详情

用户意图 → API 映射（创建记录类）

无论用户怎么描述，创建任何记录都调 POST /calendar：

关键规则：只要提到具体案件/项目/客户名称，就必须搜索获取 ID 并传入 linkid+type。只有完全没提任何实体时才用 type:0。

日程关联（重要）

创建日程时必须主动识别用户语境中的关联实体，通过 linkid+type 建立关联。type 为必填字段。

规则：只要用户提到具体的案件、项目或客户名称，就必须先搜索获取其 id，然后在创建日程时传入 linkid 和对应的 type。禁止在已识别到实体的情况下传 type:0。

识别优先级：案件(1) > 项目(2) > 客户(3)。linkid 直接使用实体返回的 id 字段值（hashid 字符串，如 "J3GGbB3j"），不要转成 int。

示例：用户说"江西建工案明天开庭"→ 搜索案件 → POST /calendar '{"title":"开庭","htime":"...","endtime":"...","type":1,"linkid":"B31ewk3n"}'

重名案件消歧（重要）

当 GET /cases?keyword=X 命中 ≥2 条时，必须先列出候选让用户确认选择，取定后再 POST /calendar 或继续后续操作，禁止凭猜测直接关联。命中 1 条可直接进行（仍展示一句确认）。

展示格式（利用响应中的 org_name 字段消歧，仅顶层律所 owner 的响应才含此字段）：

• owner（响应含 org_name）：序号. [团队名] 案件名（案号 anhao）
• 普通用户（响应无 org_name）：序号. 案件名（案号 anhao）

关键：仅当响应项含 org_name 时才展示团队名前缀；普通用户响应没有该字段，按原行为（案件名/案号）消歧即可。

time_cost vs htime/endtime

• htime/endtime = 日程起止时间（什么时候开会）
• time_cost = 实际工时（分钟），用于统计。"花费了2.5小时"→ time_cost=150，不是改 endtime

日程查询时间范围

始终用 start_date/end_date（YYYY-MM-DD），禁用 today/this_week（服务端不准）。默认查本周。

财务查询指南

应收款和收款记录接口返回全量数据（不分页），必须通过参数筛选来限定范围：

按时间筛选：使用 yd_time_range（约定收款日期）或 ss_time_range（实收日期），值为 JSON {"start":"YYYY-MM-DD","end":"YYYY-MM-DD"}，最长跨度 1 年。

常用筛选参数：

禁止使用 year、status（在 receiverecord 中无效）等不存在的参数。日期筛选必须用 yd_time_range/ss_time_range/kp_date，不接受 start_date/end_date（那是 summary 接口的参数）。

团队日程

is_team=1 查看团队日程（需团队版以上），uids 用 /team/members 返回的 hashid。展示用 htime_text/huser_text/type_text 等后端预处理好字段。

创建流程（客户/项目）

创建客户或项目前，必须先调 create-form 端点获取完整表单 schema（含枚举选项、级联树、自定义字段等）。流程：

1. AI 调用 GET /clients/create-form 或 GET /projects/create-form 获取表单 schema
2. AI 根据 schema 将用户描述映射为正确的枚举值和分类 ID
3. AI 展示确认信息（人类可读格式），等待用户确认
4. 用户确认后，AI 调用 POST /clients 或 POST /projects 创建
5. 创建成功后返回实体编号（客户返回 code/c_num，项目返回 pr_code/p_num）

关键：schema 中的枚举选项和级联树由后端动态返回，AI 必须依据 schema 中的值进行映射，不能凭猜测。

创建流程（案件）

创建案件走直接 POST + enums 引导范式（不走 create-form 两步流程）。流程：

1. AI 调用 GET /enums 获取枚举字典（取 case_type 案件类型、case_unit_type 受理单位类型等）
2. AI 收集用户输入：type（案件类型 1-5）+ privyc_data（当事人，至少一个含 name）+ 其他可选字段
3. AI 按枚举值把人类可读描述（如"民事案件"）映射为数字（如 1），把当事人原被告关系映射为 type(1=原告方/委托方、2=被告方/对方)
4. AI 展示人类可读的确认信息（案件类型、当事人列表、案由、审理程序等），等待用户确认
5. 用户确认后，AI 调用 POST /cases 创建
6. 创建成功后返回 { case_code, c_num, id, case_name }

必填：type（1-5 整数）+ privyc_data（JSON 字符串，至少一个对象含非空 name）。

自动生成（客户端不要传）：case_code、c_num（留空按组织序号生成）、案件名（未传 case_name 时按"原告名 诉 被告名"拼接，识别不出原被告用"类型+日期"兜底）、主办律师（自动写入 related_worker = PAT 调用者）。

关键：当事人原被告关系决定自动生成的案件名拼接，尽量引导用户指明谁是原告/委托方（type=1）、谁是被告/对方（type=2）。

合同查询指南

合同列表接口返回全量数据（不分页），与客户/项目关联。

数据权限：

• 普通员工：只能看到自己跟进的客户或项目关联的合同
• 管理员：可看到组织下所有合同，支持 follow_uid 按跟进人筛选

筛选参数：

合同状态：1=未执行, 2=履行中, 3=已终止

合同字段说明：

新增/更新合同：cl_id 和 pr_id 至少填一个（均为 hashid 或数字 ID），其他字段（title/amount/sign_at/end_time/status/cp_content 等）可选。

识别用户筛选意图（根据用户描述中的实体类型选择正确的搜索参数）：

关键字无结果时的降级策略（仅管理员）：当使用 keyword 模糊搜索（即用户未明确指定是客户/项目/跟进人）返回空数据时，如果当前用户是管理员，可以尝试按跟进人搜索：先 GET /team/members 查找姓名匹配的成员 UID，再用 GET "/contracts?follow_uid=xxx" 查询。如果用户已经明确指定了"客户"、"项目"或"跟进人"，则不走此降级流程，直接告知用户未找到结果。

案件附件管理

AI Agent 可以为案件上传文件、查看附件列表、获取文件访问链接。

上传文件：使用 POST /cases/{code}/files，发送 multipart/form-data，包含 file 字段（文件本身）。可选参数：

• record_id（hashid）— 关联到指定日程/办案记录，文件在日程详情中可见

文件限制：

• 允许的文件类型: jpg,jpeg,bmp,png,rar,zip,7z,doc,docx,rtf,txt,xls,xlsx,pdf,mp3,m4a,ppt,pptx,eml,csv
• 文件大小: 最大 10MB
• 文件名: 最大 128 字符
• 每日上传: 基础版 10 个/天，其他版本 100 个/天
• 超出限制时会提示"请到 OA 网页端上传"

识别用户意图：

关联日程的流程：用户说"把XX文件附加到今天的日程"时，需先通过日程获取 record_id，再上传文件并传入 record_id。注意日程必须已关联案件（type:1），这样才能确定 case_code。

高危操作

• PATCH /cases/{code} 中变更 process_code（审理程序变更影响流程）、current_stage_id（切换当前阶段）、unit_name+unit_type（变更受理单位）→ 均需先向用户确认
• POST /cases 创建案件属写操作 → 创建前必须向用户展示案件名、当事人、类型等人类可读信息并确认

不支持的操作

当前 Open API 不支持删除类操作（删除案件、删除日程、删除客户、删除项目等），也没有对应端点。当用户提出删除需求，或请求的业务场景没有相应的 API 端点时，直接回复：

该操作暂不支持在 AI 助手中完成，请在 OA 网页端或 APP 中进行相应操作。

不要尝试调用不存在的端点，也不要模拟删除行为。

使用示例