验货权限与认领机制

本文讲解扫码验货的权限控制，包括如何认领发货单以及权限问题排查。

两条通路

验货有两种入口，权限逻辑不一样：

通路一：扫码/手动输入验货（扫码入口）

用户扫描箱单上的二维码或手动输入箱子唯一码后，系统流程如下：

1. 解析入口 Token，获取箱子信息
2. 检查该发货单的认领状态：
   • 已认领 → 直接进入验货页面
   • 未认领 → 自动尝试认领到当前用户的团队，成功后进入验货

这个流程对用户几乎无感——扫码后系统自动完成认领，不需要手动操作。

通路二：分享链接认领（分享入口）

发货方分享发货单链接给收货方时，收货方需要手动完成认领。认领分两步：

第一步：验货码校验

• 在认领页面输入发货方提供的 6 位验货码
• 校验通过后获得一个临时的验货会话（有效期 15 分钟）

第二步：确认认领

• 点击「确认认领」按钮完成认领
• 认领后自动跳转到发货单详情页

二者区别：扫码入口自动认领，分享入口手动两步认领。

权限体系

核心规则

• 发货方不能验自己的货。发货单的创建者（发货人）无法对该发货单执行验货操作，必须由收货方完成
• 发货方团队成员虽然可以查看发货单，但也不能验货——因为他们的团队不是收货方团队
• 验货操作必须由已认领该发货单的收货团队完成

团队权限

• 验货需要该发货单已被你的收货团队认领
• 一张发货单只能被一个收货团队认领（先到先得）
• 同一张发货单可以存在多个分享链接（多次分享给不同客户），但只有第一个完成认领的团队获得验货权限

成员权限

• 认领后，收货团队内的所有成员（包括管理员和普通成员）都可以验货
• 不同的成员可以并行验不同的箱子（如成员 A 验第 1-5 箱，成员 B 验第 6-10 箱）
• 验货记录会标注验货人，方便追溯谁验了哪个箱子

单团队场景

当前系统一个用户只能属于一个团队。认领时直接以当前所在团队作为收货团队，无需选择。

扫码后提示「无权限」的情况

情况一：已被其他团队认领

表现：提示「该发货单已被其他团队认领」或「该发货单已绑定其他团队」。

原因：一张发货单只能被一个收货团队认领。发货方可能同时发给了多个客户，但第一个完成认领的团队抢到了。

解决：联系发货方确认是否发对了人。如果发错了，发货方需重新创建发货单并分享给你（原发货单已认领无法撤销）。

---

情况二：成员被禁用

表现：之前能验货，现在突然没有权限了。

原因：团队管理员/创始人禁用了你的成员权限。

解决：联系团队创始人或管理员，了解禁用原因并请求恢复权限。

---

情况三：没加入任何团队

表现：扫码后始终提示无权限。

原因：你的账号还没有加入任何团队。系统不知道你属于哪个组织。

解决：创建自己的团队，或者请合作方邀请你加入他们的团队。

---

情况四：当前账号是发货方

表现：发货方扫码或输入编码后，提示不能认领。

原因：验货权限认领机制要求由收货方来完成认领，发货方不能认领自己发出的货。

解决：通过分享功能将发货单分享给真实收货方，由收货方扫码输入验货码完成认领后再验货。

权限问题排查流程

遇到权限问题，按以下顺序排查：

扫码无权限
    ↓
1. 我是否已加入一个团队？
    → 否：请先创建或加入一个团队
    → 是：进入下一步
    ↓
2. 我的团队是否已认领该发货单？
    → 否：通过分享链接输入验货码认领
    → 是：进入下一步
    ↓
3. 我的账号是否被团队管理员禁用？
    → 是：联系管理员恢复权限
    → 否：进入下一步
    ↓
4. 我是否是发货单的发货人？
    → 是：不能验自己的货，请分享给收货方
    → 否：进入下一步
    ↓
5. 检查网络和系统状态
    → 退出重进、检查网络

安全机制说明

验货码保护

• 6 位数字验证码，每次分享时系统自动生成，不可关闭
• 5 次输入错误后锁定 30 分钟，防止暴力破解
• 有效期 7 天，过期后需重新生成分享
• 验证码在服务器端经过 SHA-256 哈希处理，不会明文存储

一单一团队

• 一张发货单只能被一个收货团队认领
• 认领后其他团队无法再认领，即使有验证码也不行
• 这是为了防止数据混乱——A 团队和 B 团队同时验同一张单是灾难

分享可撤销

• 发货方可以撤销分享，但仅在未认领状态下有效
• 如果已经有人认领了，撤销操作会提示冲突，无法执行
• 撤销后即使链接被转发也无法查看
• 可以重新生成新的分享链接和验货码

多人并行验货

团队场景下的最大优势：多人可以同时验货，互不干扰。

• 成员 A 扫码验第 1 箱，成员 B 扫码验第 5 箱——完全并行
• 系统实时展示每箱的验货进度
• 验货完成的箱子自动标记，团队成员可见

这极大提高了大批量验货的效率。

常见问题

Q：团队成员 A 验过的箱子，成员 B 还能再看吗？

A：可以查看验货记录（包括结果、照片），但不能修改或重新验货。一个箱子被验一次后就锁定了。

Q：如果收错了货（不是发给我们的），能拒收吗？

A：先确认是否认领了错误的发货单。如果真的不是发给你的，联系发货方处理即可，不需要走验货流程。

Q：一个收货方可以同时认领多个发货方的货吗？

A：可以。你的团队可以认领来自不同发货方的多张发货单。每张发货单独立管理，互不影响。