SDK 能力与客户端迁移
pip install wanlink_sdk-0.1.0rc1-py3-none-any.whl。导入 ClientConfig, WanLinkClient, EmployeeProof, SDKError。配置的 app_password 是 SecretStr;不要打印 model_dump、原请求或响应中的秘密。一个客户端固定企业应用;A/B 使用不同实例。Client 可作为 context manager,结束释放 HTTP 连接。
| 能力 |
SDK 入口 |
D 接入位置 / 保留职责 |
| Token/作用域/HTTP/错误 |
WanLinkClient.context/call |
platform.WanLink 只做 Actor 与业务入口权限适配 |
| 员工认证/状态/改密 |
authenticate / validate_employee / change_employee_password |
D 签发与撤销自己的 Cookie,不把 AppToken 给浏览器 |
| 最终权限 |
check_permission / authorize / effective_permissions |
D 每次实时核验;批量一次请求,不重算角色 |
| 权限目录展示 |
permission_catalog / update_permission_metadata |
无创建或授权方法 |
| 组织人员岗位任职 |
directory.list_resources / execute_command |
D 保留页面选择上下文、操作权限与幂等记录 |
| 全量快照 |
directory.frozen |
校验冻结水位、分页、条数与 SHA;应用自己提交镜像 |
| 增量 |
download_changes |
返回 DeltaWindow;应用同事务提交变更和持久游标,再 checkpoint |
| 审批模板 |
approvals.catalog / download |
SDK 校验平台人员化投影,D 存 SQL |
| 运行时 |
approvals.resolve / launch / continuation / eligibility |
D 保留自己的实例、冻结结构、意见、客户业务效果 |
| 回调与回执 |
verify_notification / validate_event / build_receipt / approvals.receipt |
D 耐久 inbox、去重、调度、SQL、失败恢复 |
目录命令 operation 为 organization.create/update/parent/move/disable,employee.create/update/organization/move/disable/restore,position.create/update/move/disable/restore,appointment.assign/end/transfer。target 为稳定 UUID,更新传当前 version;organization 涉及树版本按正式参数传入。岗位组织不可转挂;删除是停用。
底层 call 仅允许登记的 AppToken 路径,不允许完整 URL、查询拼接、覆盖认证 header 或跳转。真正的只读分页最多三次有界重试;写入不自动重发。请求编号使用 UUID;同一幂等业务重试必须保持编号与内容,不能重新生成密码或新编号绕过冲突。未知提交应先对账。新人一次性密码由调用者安全显示和交付,不进入日志,SDK 不保存它。
错误 .code 是稳定本地类别;.platform_code / .request_id 保存上游安全坐标;.message 是安全中文提示。TransportError.category=NETWORK_ERROR;非 JSON 是 NON_JSON_RESPONSE;其他格式错误 CONTRACT_ERROR;正式拒绝 PLATFORM_REJECTION。网络写失败 outcome_unknown=True,不能据此断言平台回滚。
EmployeeProof 仅保存平台验证后的企业、应用、员工和两代次。不要从请求正文伪造 proof。SDK 不建立员工会话,也不使用过期本地 ALLOW 缓存。