WanLink New AppToken 协议使用说明
这是 SDK 0.1.0rc1 对当前公开 HTTP 合同的发行说明。路径登记见 platform-api,精确目录数据模型随 SDK 的 directory_schema.py 发布。平台模块 public.json 与正式合同是权威;本说明不开放任何额外接口。网页、企业管理员 Cookie、root 接口和模块内部 Python 调用不属于 SDK。
公共传输与身份
请求为 UTF-8 JSON,Content-Type: application/json。生产地址使用 HTTPS,开发回环允许 HTTP。客户端不跟随重定向,不把凭据或 Token 交给浏览器;每个 WanLinkClient 固定一个企业应用。X-Request-ID 为 UUID;记录响应 request_id 和具体错误 code,不能记录 Authorization、应用密码或一次性员工密码。
POST /api/app/token 的正文只有 app_id(规范 UUID 字符串)、app_password(非空秘密字符串);返回 access_token、token_type、expires_at、expires_in、enterprise_id、app_id。GET /api/app/me 无正文,返回 enterprise_id、app_id、kind、request_id。后续使用 Authorization: Bearer AppToken。企业和应用作用域由服务端确定,不能在查询或正文中另传企业 ID 覆盖。
应用如记录员工操作者,声明必须取自已验证的应用会话。使用 SDK EmployeeProof 保存 employee_id、auth_generation、enterprise_generation 和固定企业应用。不能相信浏览器提交的同名字段。身份有效不等于权限允许,业务接口仍执行在线最终权限查询。
员工身份与密码
下列路径均在 /api/app 下,输入字段精确匹配,拒绝额外字段。员工 ID 是 UUID,两项 generation 是正整数。
| POST 路径 |
JSON 输入 |
成功含义 |
| /employees/authenticate |
phone、password |
authentication 含企业/员工身份及两代次;应用另建自己的会话 |
| /employees/validate |
employee_id、auth_generation、enterprise_generation |
当前企业、员工及两代次仍有效 |
| /employees/password |
上述三个证明字段、current_password、new_password、confirmation |
凭据与认证代次一致更新,所有应用中的旧员工认证失效;要求重新登录 |
手机号按当前中国大陆 11 位手机号合同;新密码 8 至 1024 个 Unicode 码点,ASCII 数字/大写/小写/特殊符号至少两类。合法 Unicode 输入与是否计入密码类别分别处理;历史哈希继续验证。员工凭据不等于企业管理员凭据,不能登录平台后台。应用不存在管理员代改密码接口。
SDK authenticate 还核对当前员工显示资料及企业范围。change_employee_password(proof,current,new,confirmation,request_id) 不保存新密码;成功后应用必须清除自己的旧 Cookie。网络未知提交时先按现行凭据重新确认,不盲目反复改密。
组织、人员、岗位与任职写入
所有 ID 均为服务端稳定 UUID;name 为非空名称;version/tree_revision 是先查询得到的正整数,不能固定写 1。业务删除表示停用。direction 为 up 或 down;同级移动只改排序,不能暗改父组织或任职。
| 路径(/api/app 前缀) |
方法 |
精确 JSON 字段 |
| /organizations |
POST |
tree_revision,parent_id,name |
| /organizations/{node_id} |
PATCH |
tree_revision,name |
| /organizations/{node_id}/move |
POST |
tree_revision,direction |
| /organizations/{node_id}/parent |
PUT |
tree_revision,parent_id |
| /organizations/{node_id}/disable |
POST |
tree_revision |
| /personnel |
POST |
name,work_number,phone,organization_id,operation_id |
| /personnel/{employee_id} |
PATCH |
version,name,work_number,phone |
| /personnel/{employee_id}/organization |
PUT |
version,organization_id |
| /personnel/{employee_id}/move |
POST |
version,direction |
| /personnel/{employee_id}/disable 或 /restore |
POST |
version |
| /positions |
POST |
name,description,organization_id |
| /positions/{position_id} |
PATCH |
version,name,description |
| /positions/{position_id}/move |
POST |
version,direction |
| /positions/{position_id}/disable |
POST |
version |
| /positions/{position_id}/restore |
POST |
version,organization_id(必须为 null,沿用原组织) |
| /positions/{position_id}/appointments |
POST |
employee_id,position_version,reason |
| /appointments/{appointment_id}/end |
POST |
version,reason |
| /appointments/{appointment_id}/transfer |
POST |
version,reason,target_position_id,target_version |
员工工号是 1–64 位字符串,允许字母、数字、点、下划线和连字符,必须保留前导零。手机号与工号在企业内唯一,停用仍占用。AppToken 新增员工不接受 password/password_mode;服务端生成独立随机密码,仅首次响应 initial_password。相同 operation_id、相同内容重放返回原员工且不再次给明文;不同内容返回冲突。丢失一次性密码需企业管理员按正式流程重置,不能重新建同一员工。
组织根节点不可停用;活动子节点、员工或任一应用启用岗位占用时拒绝。AppToken 不开放组织恢复。岗位创建后组织不可转挂,原组织停用时不能恢复岗位;有活动任职不能停岗。任职允许多人多岗,但同员工同岗位最多一条活动记录。调岗只原子结束所选旧任职并新建目标任职,不改变员工主要组织。员工停用影响该企业全部应用的认证、任职及最终权限;恢复不复活历史关系。
查询使用 GET /organizations(完整组织树含 tree_revision)、/organizations/{node_id}、/personnel、/positions、/appointments。分页列表返回 items、total 等各自登记字段;使用 directory.list_resources 或 directory.frozen 取得经校验的完整镜像,不能把列表第一页当完整目录。读失败与空集合分开。
最终权限与目录元数据
| 路径 |
方法 |
用途 |
| /authorization/check |
POST |
employee_id、code;单项 ALLOW / DENY / UNREGISTERED |
| /authorization/batch |
POST |
employee_id、codes;1–500 个完整应用内编码,响应保持输入顺序与重复项 |
| /employees/{employee_id}/permissions |
GET |
当前员工在本应用的完整最终有效权限 |
| /permissions |
GET |
本应用权限目录、页面、属性和说明 |
| /permissions/metadata |
PATCH |
items 数组,批量修改已有权限的展示资料,不能创建权限或授权 |
完整自定义编码如 m.09 保留整体,不加企业/应用前缀、不按最后一个点截断。SDK 不缓存 ALLOW,不展开组织/岗位/角色来替代最终权限表。权限创建、停启、角色与来源维护仍由企业管理员操作;服务端明确拒绝的 14 条路径列入 API 目录但不进入 SDK 可调用白名单。没有角色来源查询或平台全量投递账本查询的 AppToken 能力。
完整快照与增量
GET /directory/snapshot 不带查询和正文,返回同一冻结水位的 manifest 或完整集合。SDK directory.frozen() 按 manifest 下载 /directory/snapshots/{snapshot_id}/{collection} 的各页,逐项核对作用域、条数、版本、规范 SHA、引用关系与完成状态。返回 snapshot、records;它不提交数据库。
目录有效负载四类:Organization、Employee、Position、Appointment。代码随包发布精确 Pydantic JSON schema,未知字段拒绝,时间必须 UTC,is_active 为布尔,version 正整数。员工 phone/work_number 为字符串;员工主要组织与岗位组织分别存储,任职 ended_at 与活动状态一致。
增量:GET /directory/window?cursor=原游标 冻结 through;GET /directory/changes?cursor=原游标&through=水位&limit=100 逐批下载。cursor/through 为不透明字符串,不解析或跨企业应用复用。download_changes 返回 DeltaWindow(changes、to_cursor、tree_revision、batches),空窗口 tree_revision 可以为 None,此时保留原树修订。应用在同一 SQL 事务中提交镜像与新游标,提交后 POST /directory/checkpoint,正文 cursor。下载成功不能提前推进持久游标。
过期游标按正式 WL.DIRECTORY.SYNC.04 进入完整快照恢复;快照/下载失败保留原镜像,不先清库。只读分页最多三次有界重试,写入不自动重发。平台已提交、本地提交未知时保留原操作编号并对账。
审批人员化投影与业务实例
GET /approval-templates 返回当前应用已发布目录。GET /approval-templates/{template_id}/versions/{version} 返回不可变发布 definition 及可变人员 binding、projection_revision;静态节点 employee_ids 已由平台解析,应用只做同 scope 姓名映射。动态发起人、自选等待真实上下文,不能把组织/岗位/角色重新作为应用授权体系下发或本地重算。
以下 POST 位于同一模板版本路径:
| 后缀 |
精确输入 |
作用 |
| /resolve |
context |
正式预览,不创建业务实例 |
| /launch |
instance_id,context |
返回绑定应用实例及发起事实/命中路径的签名 launch_proof |
| /continuation |
instance_id,launch_proof |
保持原实例路径,核验当前人员投影 |
| /continuation/eligibility |
instance_id,launch_proof,projection_revision,node_id,employee_id |
当前办理资格;版本变化不能用客户端布尔标记绕过 |
context 仅含 initiator_employee_id 和 selected_employee_ids。后者以自选节点 ID 为键、单个员工 ID 字符串为值,例如 {"select_review":"<employee UUID>"};当前每个自选节点只选一名候选员工,不能传数组。无自选时 selected_employee_ids 为 {}。不传金额、任意业务字段或客户端自报部门。部门取主要组织,岗位取同企业本应用全部活动任职;IN 任一匹配,NOT_IN 全部不匹配。发起事实和分支冻结,后续当前办理资格仍在线核验。普通静态下载 execution=null 不等于不可展示。
应用负责实例、意见、任务、客户业务效果及同事务保存。launch 不是应用业务提交;成功写本地实例后才能报告提交成功。历史 definition 摘要变化不能覆盖原记录,人员修订不能倒退;无人可办时明确阻断,不能静默跳过节点。
通知、去重与 applied
平台调用应用自行提供的接收 URL,以下载的接收 Bearer 验证;该 Bearer 与应用访问平台的 AppToken 不同。接收 X-WanLink-Event-ID 必须等于正文 event_id,occurred_at 带时区且不能超过未来五分钟。历史事件重试允许旧时间;不能简单按五分钟 TTL 丢掉真实积压消息。企业/应用必须与当前配置一致。
已知公开字段:event_id、enterprise_id、app_id、template_id、template_version、projection_revision、change_type、request_id、occurred_at、source、source_app_id、actor_id。测试 receiver_test 与业务事件、应用主动 reconcile 分开。应用先持久化收件箱并按 event_id/内容摘要去重;未知或冲突内容不得伪记成功。
消费者下载最新模板→核验→本地事务提交投影和持久状态→POST /approval-events/{event_id}/receipt。回执包含 receipt_id、instance_id、template_version、projection_revision、outcome、error_code;应用实例标识稳定,receipt_id 根据事件/实例/结果/修订稳定生成。成功 outcome=applied,平台确认 recorded=true 后才标回执完成。回执网络失败保留 RECEIPT_PENDING,重启后复用同一回执而非回滚已提交投影。
平台投递 delivered、本地收到、下载、SQL应用、平台 applied 是不同阶段。没有平台全量投递查询时显示未采集,不用本地数量冒充平台总量。SDK 示例消费者使用自己的小型耐久收件箱演示边界;正式标准应用业务数据库仍只支持 SQL Server。