代币可见性与访问控制
本指南说明 VIO v4 中的代币可见性系统，包括不同可见性类型下谁可以接收代币，以及代币如何在组织之间流转。
1. 核心概念
1.1 组织层级
租户
├── 租户直属会员（不属于任何子公司）
└── 子公司
└── 子公司会员1.2 三种代币可见性类型
| 类型 | 用途 |
|---|---|
| Private | 仅限创建公司的内部使用 |
| Shared | 可与指定合作伙伴共享 |
| Public | 对所有人开放 |
1.3 关键术语
- Creating Company：创建该代币的公司（租户或子公司）
- Sharing List：创建 Shared 代币时配置的可共享接收方：
sharedWithTenants- 可访问该代币的租户sharedWithSubCompanies- 可访问该代币的子公司sharedWithUsers- 可访问该代币的指定用户
2. 我创建的代币 - 可以铸造/发送给谁？
假设你是 Company A 的管理员，并创建了一个代币：
2.1 铸造到公司
这个场景用于把代币批量发放给另一家公司的管理员，再由对方向自己的用户继续分发。
| 代币类型 | 可铸造到的公司 |
|---|---|
| Private | 仅限你自己的公司 ❌ 不能铸造给任何其他公司 |
| Shared | ✅ 自己的公司 + ✅ 共享列表中的公司 |
| Public | ✅ 任意公司 |
业务场景
- Private Token：员工积分等内部用途，不应流出公司
- Shared Token：与合作商户共建的联名积分，只在合作网络内流通
- Public Token：通用平台代币，可分发给所有合作方
2.2 发送给用户
这个场景用于直接把代币发送给终端用户（会员）。
| 代币类型 | 可发送给的用户 |
|---|---|
| Private | 仅限你自己公司的会员 ❌ 不能发送给其他公司的任何人 ❌ 不能发送给管理员（仅限 Member 角色） |
| Shared | ✅ 创建公司的会员 ✅ 已共享租户的直属会员（不包含其子公司会员） ✅ 已共享子公司的会员 ✅ sharedWithUsers 中明确列出的用户 |
| Public | ✅ 任何人 |
重要细节
- Private Token 限制最严格：接收方必须是创建该代币公司的 Member 角色，不能是 Admin
- 对于 Shared Tokens，“shared tenant members” 只包含租户的“直属会员”，不包含该租户子公司的会员。如果你也要覆盖子公司会员，必须显式把对应子公司加入共享列表
管理后台：查找接收人（Send / Bulk Send）
对于 Public 代币：
- 关键词 / 部分匹配搜索：会在你公司可见范围内查找用户（租户直属会员与子公司管理员）
- 完整邮箱或完整手机号：精确匹配时可解析到平台任意位置的用户
Bulk Send 会对每一行使用同样的解析方式（例如邮箱和金额），因此 Public 代币也可以找到外部用户。
3. 我收到的代币 - 可以转发给谁？
核心规则：当你转发别人发送给你的代币时（也就是不是你公司创建的代币），你只能发送给你自己公司里的直属会员。
假设你是 Company B 的管理员，并收到了一个由 Company A 创建 的代币：
3.1 收到 Private Token
不会发生
这种情况不会出现。Private 代币不能铸造或发送到创建公司之外，所以你不可能从其他公司收到 Private 代币。
3.2 收到 Shared 或 Public Token
当你转发别人给你的代币时，接收方只允许是 你自己公司的直属会员：
| 你的公司类型 | 可发送给的接收人 |
|---|---|
| Tenant Admin | 仅限你所在租户的直属会员（没有隶属子公司的会员） |
| Sub-Company Admin | 仅限你自己子公司的直属会员 |
重要说明
这是一个安全设计，用来防止代币在组织之间被无限制二次分发。无论原始代币的可见性是 Shared 还是 Public，只要你收到的是其他公司发来的代币，你都只能在自己公司内部转发给直属会员。
4. 完整权限矩阵
4.1 铸造到公司
| 我创建的代币类型 | 自己的公司 | 共享列表中的公司 | 任意其他公司 |
|---|---|---|---|
| Private | ✅ | ❌ | ❌ |
| Shared | ✅ | ✅ | ❌ |
| Public | ✅ | ✅ | ✅ |
4.2 发送给用户
| 代币类型（不论创建者） | 我公司内的会员 | 共享列表公司的会员 | 任意用户 |
|---|---|---|---|
| Private | ✅（仅 Member 角色） | ❌ | ❌ |
| Shared | ⚠️ 必须位于共享范围内 | ✅ | ❌ |
| Public | ✅ | ✅ | ✅ |
5. 典型业务场景
场景 1：员工内部积分（推荐：Private）
- 创建：HR 创建一个 Private Token “Employee Points”
- 分发：只能发给同一家公司的员工
- 流通：如果开启
isTransferable且启用TOKEN_TRANSFER功能，员工之间 可以 在公司内部互转 - 特点：完全内部流通，积分不会离开公司
场景 2：商场联盟积分（推荐：Shared）
- 创建：Mall A 创建一个 Shared Token “Alliance Points”
- 共享设置：把 Merchant B 和 Merchant C 加入共享列表
- 分发：A/B/C 的管理员都可以发给自己公司的会员
- 流通：A/B/C 的会员之间可互相转账
- 特点：只在合作网络内流通，外部用户无法参与
场景 3：通用平台代币（推荐：Public）
- 创建：平台创建一个 Public Token “VIO Coin”
- 分发：可发给任意公司、任意用户
- 流通：转账完全自由
- 特点：流动性最高，适合平台级代币
6. 常见问题
Q1：我收到了别人发来的 Shared 或 Public 代币，还能发给我公司的成员吗？
答： 可以，但只能发给你公司内的 直属会员：
- 如果你是 Tenant Admin：只能发给直属属于你租户的会员，不能发给子公司成员
- 如果你是 Sub-Company Admin：只能发给你自己子公司的会员
这个限制与代币原始可见性无关，即使原代币是 Shared 或 Public 也一样。
Q2：Private Token 可以在会员之间转账吗？
答： 可以。只要满足以下条件，会员之间 可以 在创建公司内部转移 Private Token：
- 该代币的
isTransferable已启用 - 租户的
TOKEN_TRANSFER功能开关已启用 - 接收方是创建该代币公司的 Member（不是 Admin）
如果任一设置关闭，则只有管理员可以发送 Private Token。
Q3：为什么子公司会员收不到一个“共享给其母租户”的 Shared Token？
答： 共享给租户，只包含该租户的“直属会员”（没有归属子公司的会员）。如果你也要覆盖子公司会员，需要显式把对应子公司加入 sharedWithSubCompanies。
Q4：代币创建后还能修改可见性吗？
答： 可以，你可以在管理后台的代币编辑界面中修改可见性和共享列表。
Q5：如果我把 Shared Token 改成 Private，会发生什么？
答： 已经持有该代币的用户仍会保留余额，但：
- 无法再把新代币铸造/发送给公司外部用户
- 已在公司外部持有该代币的用户不能再向任何人转移该代币
7. 可视化摘要
┌─────────────────────────────────────────────────────────────────────┐
│ Token Visibility Matrix │
├───────────────────┬───────────────┬───────────────┬─────────────────┤
│ │ PRIVATE │ SHARED │ PUBLIC │
├───────────────────┼───────────────┼───────────────┼─────────────────┤
│ Mint to Company │ Own company │ Own + Sharing │ Any company │
│ │ only │ list │ │
├───────────────────┼───────────────┼───────────────┼─────────────────┤
│ Send to User │ Own company │ Within sharing│ Anyone │
│ │ Members only │ network │ │
├───────────────────┼───────────────┼───────────────┼─────────────────┤
│ Forward After │ (Cannot │ Own company │ Own company │
│ Receiving │ receive) │ direct members│ direct members │
├───────────────────┼───────────────┼───────────────┼─────────────────┤
│ Typical Use Case │ Internal │ Partner │ Platform-wide │
│ │ employee │ alliance │ universal │
│ │ rewards │ points │ token │
└───────────────────┴───────────────┴───────────────┴─────────────────┘8. 相关功能
8.1 转账设置
除了可见性之外，代币还有会影响流通方式的转账设置：
| 设置 | 说明 |
|---|---|
| Allow transfers between users | 关闭后只有管理员可以发送代币，会员之间不能互转 |
跨租户转账 受 visibility 控制（在管理后台创建或编辑代币时，并没有单独的 “Allow cross-tenant transfers” 开关）：
| Visibility | 跨租户转账 |
|---|---|
| Private | 不允许 |
| Shared | 当接收方符合共享配置时允许 |
| Public | 平台范围内允许，但仍需通过接收方校验 |
保存时，系统会把 visibility 映射到内部跨租户标记（Public 或 Shared → 按需启用；Private → 关闭）。
8.2 Show Tokens in Parent Admin
当租户启用了 Show Tokens in Parent Admin 功能开关后：
- 上级组织管理员可以看到其子公司创建的 SHARED 代币
- 创建 SHARED 代币时，会自动共享给所有启用了该开关的祖先组织
INFO
该功能由 Super Admin 在租户级别配置。
Need Help?
如果你对代币可见性有疑问，或遇到了不符合预期的行为，请联系系统管理员或超级管理员。