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 缓存。