# 公司与人脉

Version: 829db5245701f2f8

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

操作名：search、detail、mapRead、mapCandidateLinks、mapNode、mapHistory、mapDiff、create、update、follow、mapDraft、mapPublish、mapNodeCreate、mapNodeUpdate、mapMove、mapDepart、mapDelete、mapDeleteRequest、mapDeleteReview、mapRestore、mapRestoreRevision、mapArchiveDraft。工具名称前缀 company_library_ 不用于 POST 的 operation。

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

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

- 先 search 避免重建，company.id 与 clients.id 为同一整数；新行业公司不要求岗位或候选人。创建人、资料维护人、客户经理和管理员管理公司主档；同组织同事可补充地图，不能跨组织。旧连接不自动扩权，按需申请 companies:read / companies:write。
- mapRead({companyId,versionId?,revision?,asOf?,sinceRevision?,sinceCatalog?}) 返回版本目录及不含备注的结构；未指定版本读取北京时间已生效正式版。传回上次 revision 和 catalog，未变化返回极小回执；versionId/isCurrent 改变需重新读取。只在可见且需要时低频刷新，不反复抓取整图。mapNode 单独读一个节点含备注，需 companies:read + sensitive:notes；candidateRef 是链接，不直接给电话/微信或简历。公司附件沿用 clients 模块及 sensitive:documents。
- 研究人物后续可通过 mapNodeUpdate.data.candidateRef 关联已有候选人，但已绑定身份不能随意换绑、同一候选人不能绑定两个不同人物；冲突需先核对身份，不按姓名自动合并。data.validFrom / validTo 可补充或更正真实任职日期，未知为 null，仍保留修改历史。
- mapCandidateLinks({candidateRef,page?,pageSize?}) 需 companies:read，分页查询该候选人在当前正式组织及草稿中的任职链接，不含联系方式、备注或附件。创建/上传候选人后可询问是否关联公司，不强制添加：核对身份后，对已有研究人物用 mapNodeUpdate.data.candidateRef，新增任职用 mapNodeCreate 带 candidateRef，复用稳定人物身份；先查询已有链接，勿重复录入。不改上传人、负责人或招聘流程。
- mapDraft 从正式版本建立草稿，mapPublish 需维护人、当前 revision、confirmed=true 和 effectiveDate。同一天仅一个组织版本，日常补充用 mapNodeUpdate；重大调整在草稿里做。历史/待生效版只读；基准版改变返回 MAP_BASE_CHANGED，应保留已做改动供人工核对，基于最新正式版重建草稿，不强行覆盖。未来版不会自动合并后续补充。
- 节点 kind 为 department/person，parentId=null 是公司根；personId 是稳定人物身份，节点代表一次任职。candidateRef 可选已有库内ID；不自动建简历或改归属。mapMove 保留旧任职并建新任职；兼任用 mapNodeCreate 带同一 personId。事实日期未知用 null，不猜今天。knownBy 用公司 detail.members 的有效 membership ID，jobIds 仅新关联本公司的已有岗位。
- 普通节点编辑用 nodeVersion，其他节点并发修改不冲突；publish/分支删除/恢复还需全图 revision。mapDelete 只允许自己的无关联未被他人维护叶子，或维护人确认整分支；其他同事用 mapDeleteRequest，维护人 mapDeleteReview 查看最新影响后确认。mapRestore 恢复同批误删，mapRestoreRevision 追加修订而非抹掉历史；都不删候选人、岗位或附件。所有修改有操作者、精确时间和事实日期；先取实时 schema，再提交 JSON。

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