# 客户公司

Version: 829db5245701f2f8

模块地址：https://dev.planahr.top/api/v1/client-library/tools；权限 clients:read / clients:write。写权限不包含读权限，均不扩大用户自身权限。

操作名：search、detail、create、update、documents。工具名称前缀 client_library_ 不用于 POST 的 operation。

GET 加 ?operation=操作名 只取单项 schema；?view=summary 只取目录。POST 不带查询参数，使用 {operation,input} 和 Content-Type: application/json。

```bash
curl 'https://dev.planahr.top/api/v1/client-library/tools?operation=search' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

- 先搜索避免重复；新岗位关联真实客户公司 ID，不以自由文本代替关联。
- 公司/岗位附件：documents({id,page?,pageSize?}) 只列分页元数据，需本模块 :read + sensitive:documents，同组织可读取且按用户审计。GET tools?operation=documents 的 binaryUpload 提供上传/下载地址与限制。POST /api/v1/client-library/{id}/documents 用 multipart/form-data，仅 file、version、requestId 三个字段，需本模块 :write 及原对象编辑权限；不是 JSON 工具，不传 Base64。先保存公司/岗位，再上传；默认每份 20 MiB，支持 PDF/Word/Excel/PowerPoint/PNG/JPEG。每次追加独立附件，不覆盖旧文件；原件不自动转成JD或正文。GET 同路径 /{documentId}?download=1 下载原件（相同 Bearer，需 :read + sensitive:documents）；download=0 可预览 PDF/图片。上传回执返回新版 version，重试保留原 version/requestId/文件名/内容；409 VERSION_CONFLICT 先读新版本，再用新请求 ID。上传人由登录身份确定，不能自报。文件字节不进入模型上下文，只有按需下载的外部文件。
- Office 附件上传成功后后台生成 PDF，列表的 preview.status 为 queued/converting/ready/failed/evicted；原件始终由 download=1 下载，ready 时 download=0 返回 PDF。PDF/图片直接预览，不生成副本。上传回执的状态是当时快照，后续以 documents 列表为准；不要重传原件来催转换，也不要高速轮询。失败原因在 preview.errorCode/message；用户要求重试且 retryAvailable=true 时，按 binaryUpload.previewRetry 用同一 Bearer POST /{documentId}/preview，JSON {}，需本模块 :read + sensitive:documents，不需要编辑权。202 表示已排队；只重建衍生 PDF，不修改附件或资料版本。文件字节不进入 JSON，不将加密或损坏文件误报成上传失败。

以下仅为虚构模板；ID、version 必须从真实读取结果取得，写入 requestId 为每个逻辑动作生成且重试保持不变。

### 搜索客户公司（只读）

POST /api/v1/client-library/tools

```json
{
  "operation": "search",
  "input": {
    "query": "示例公司",
    "page": 1,
    "pageSize": 20
  }
}
```