VIO v4 超级管理后台 - 用户指南
欢迎使用 VIO v4 超级管理后台。本指南介绍平台级管理功能：租户、用户及全局配置。
访问受限
本门户仅限具有 super_admin 角色的用户访问。
1. 登录
面向平台管理员使用的超级管理员登录页。
如何使用：
- 在浏览器中打开超级管理后台 URL
- 输入超级管理员邮箱
- 输入密码
- 点击 "Sign In" 进入平台仪表盘
会话管理
门户采用安全的基于令牌的认证，并会自动刷新会话：
| 令牌类型 | 有效期 | 用途 |
|---|---|---|
| Access Token | 15 分钟 | API 鉴权 |
| Refresh Token | 7 天 | 换取新的 Access Token |
自动刷新会话
Access Token 过期时，系统会自动用 Refresh Token 换取新 Access Token，无需打断操作。因此在最多 7 天内有活动时可保持登录，不会被登出。
多设备支持
超级管理员账号支持在多台设备同时登录。在新设备登录不会影响其他设备的会话。
2. 仪表盘
平台级仪表盘，展示所有租户、用户与系统指标。
如何使用：
- 查看平台总体统计
- 监控租户活跃度与健康度
- 查看全平台交易量
- 使用常用管理任务的快捷入口
3. 租户
管理平台上的全部租户。
如何使用：
- 查看所有租户列表（含每个租户自动分配的 PIN Prefix）
- 搜索与筛选租户
- 创建新租户（会自动生成唯一的 2 位 PIN 前缀）
- 查看租户详情与配置
- 启用或停用租户
创建租户并同时创建管理员
创建新租户时，可选择同时创建一名管理员。为便于操作，「创建管理员」区块默认展开。
- 点击 "Create Tenant"
- 填写租户名称
- 在 "Create Admin User" 区块（默认展开）中填写管理员信息：
- Admin Email：管理员登录邮箱（若创建管理员则必填）
- Admin Phone：备用登录方式（邮箱与手机至少填一项）
- Admin Password：至少 6 个字符
- Display Name：管理员显示名（可选）
- 点击 "Create"，同时创建租户与管理员
管理员可选
可以不创建管理员 — 若不需要，可收起该区块。之后仍可在 Users 模块添加管理员。
管理员角色
随租户创建的管理员会自动获得 tenant_admin 角色，并设为租户负责人（owner）。
4. 租户详情
查看与管理单个租户的详细信息。
如何使用：
- 查看租户信息与状态（基本信息中含自动分配的 PIN Prefix）
- 查看租户使用统计
- 管理租户配置
- 查看租户代币与用户
- 进入租户相关设置
创建子公司并同时创建管理员
在租户详情页可在该租户下创建子公司。与创建租户类似，可同时为子公司可选创建管理员；"Create Admin User" 区块默认展开。
- 在 Sub-Companies 区域点击 "Add Sub-Company"
- 填写子公司信息：
- Name：子公司名称（必填）
- Slug：URL 友好标识（通常由名称自动生成）
- 在 "Create Admin User" 区块（默认展开）填写：
- Admin Email：管理员登录邮箱
- Admin Phone：备用登录方式
- Admin Password：至少 6 个字符
- Display Name：显示名（可选）
- 点击 "Create"，同时创建子公司与管理员
管理员可选
可不创建管理员 — 不需要时可收起该区块。
管理员角色
随子公司创建的管理员会自动获得 sub_company_admin 角色，并设为该子公司管理员。
计费设置
在租户详情页可配置租户计费：
主币种
设置所有计费与结算计算使用的主币种。该币种将统一用于：
- 维护费
- 按计费模型的可变服务费
- 跨租户结算
- 发票生成
- 结算报表
支持的币种
平台支持 14 种币种：HKD、THB、USD、EUR、MYR、SGD、CNY、JPY、KRW、VND、PHP、IDR、AUD、GBP。
修改主币种
修改租户主币种时会弹出确认框，确保你了解影响：
- 点击币种下拉选择新币种
- 确认框会列出受影响项：
- 所有计费计算将使用新币种
- 维护费将按新币种收取
- 结算报表金额将按新币种展示
- 确认后应用新主币种
WARNING
修改主币种会影响后续所有计费与结算。历史交易为审计目的保留原币种。维护费币种与主币种绑定，不能单独修改。
计费模型
可配置一种或多种计费模型及对应费率：
- Token-based：按发行或消耗的代币计费
- Redemption-based：用户核销礼券时计费
- Consumption-based：礼券在门店使用时计费
每种模型支持三种费率类型：
| 费率类型 | 说明 | 示例 |
|---|---|---|
| Per Unit | 每笔固定金额 | 每次核销 0.50 HKD |
| Percentage | 交易金额百分比 | 礼券面值的 2.5% |
| Token Value Percentage | 代币价值百分比（代币价格 × 代币法币汇率），自动转换为租户计费币种 | 每次核销收取代币价值的 1% |
Token Value Percentage 费率类型适用于需按代币等价法币收费的场景。若代币锚定的法币（如 USD）与租户的计费币种（如 HKD）不同，系统会以 HKD 为中介自动换算代币法币价值后再按百分比计费。若礼券无关联代币价格，则退回至设置的 最低收费。
支持小数费率
所有计费费率输入支持小数，例如每枚代币 0.25 或百分比 1.5%。系统最多接受 2 位小数以便精确配置。
维护费
设置固定月维护费，并可配置账单日。
功能开关
租户详情页含 Feature Flags，可开关多项租户能力。其中两项控制跨层级代币与礼券可见性：
| 开关 | 说明 |
|---|---|
| Show Tokens in Parent Admin | 在组织层级 A（租户或子公司）启用后，其分支下任意公司创建的 SHARED 代币，在 A 级管理后台中可见。 |
| Show Vouchers in Parent Admin | 行为同上，针对 SHARED 礼券。 |
工作原理：
- 开关设置在查看方（希望看到下级内容的组织），而非创建方。
- 当子公司创建 SHARED 代币或礼券时，系统会沿组织树向上查找，并自动与所有启用了对应开关的祖先共享。
- 示例：层级为
Tenant → A → B → C，若 Tenant 与 A 均启用Show Tokens in Parent Admin，则 C 创建的 SHARED 代币对 A 与 Tenant 均可见。若 A 未启用，则 C 的代币仅对 Tenant 可见。
TIP
上述开关只影响 SHARED 可见性内容。PRIVATE 仍限于创建组织；PUBLIC 对所有人可见。
同样开关也可在各级 Sub-Company 详情页配置，用于控制该子公司对其后代的可见性规则。
5. 会员端配置
配置租户的会员端体验，包括导航栏与首页内容。
如何进入：
Tenants → 点击某租户 → 在租户详情页的 Member App Configuration 区域选择 "Navbar Configuration" 或 "Home Page Configuration"。
导航栏配置
- 查看当前导航配置及会员端导航实时预览
- 点击 "+ Add Navigation Item" 增删导航项
- 拖拽排序
- 点击某项 "Edit" 配置标签、图标与可见性
- 点击 "Save Changes" 发布更新后的导航栏
首页配置
- 查看当前首页区块
- 增删内容块
- 配置精选项与横幅
- 设置展示顺序与可见性
- 预览并发布变更
6. 用户
查看并管理全平台用户。
如何使用：
- 查看所有平台用户
- 按姓名、邮箱或租户搜索
- 按角色或状态筛选
- 查看用户详情与活动
- 管理用户账号
创建用户
- 右上角点击 "+ Create User"
- 填写用户信息：
| 字段 | 必填 | 说明 |
|---|---|---|
| Role | 是 | Member、Tenant Admin 或 Super Admin |
| Tenant | 是 | 用户所属租户 |
| 邮箱与手机二选一 | 用户邮箱 | |
| Phone | 邮箱与手机二选一 | 用户手机（含国家代码） |
| Password | 是 | 至少 6 位，含 1 个大写字母与 1 个特殊字符 |
| Display Name | 否 | 显示名 |
- 点击 "Create" 完成
7. 礼券
查看全平台、全部租户的礼券。礼券模块含三个标签：
| 标签 | 说明 |
|---|---|
| All Vouchers | 跨租户查看与搜索礼券，可按租户与可见性（Private、Shared、Public）筛选 |
| All Claims | 跟踪全平台礼券领取与核销 |
| Analytics | 全平台礼券表现指标与统计 |
如何使用：
- 浏览全平台礼券列表
- 按名称搜索
- 按租户或可见性筛选
- 查看详情：分类、面值、已领数量、状态等
- 切换标签查看领取记录与分析
8. 结算报表
查看并管理全平台租户的结算报表。
如何使用：
- 查看全平台结算摘要
- 按租户或周期筛选结算
- 生成合并报表
- 处理待结算项
- 导出财务数据
报表标签
结算报表页含多个标签，用于财务分析：
| 标签 | 说明 |
|---|---|
| Platform Overview | 高层指标：平台总收入、结算量与关键 KPI |
| Tenant Settlements | 各租户结算明细 |
| Cross-Tenant Flow | 跨租户礼券使用与结算的可视化与明细 |
| Transactions | 带分页与筛选的交易明细列表 |
| Invoices | 租户计费已生成发票 |
Tenant Settlements 标签
展示各租户及其子公司的汇总：
| 列 | 说明 |
|---|---|
| Tenant | 租户名称与 slug（展开后为子公司名称） |
| Billing Model | 生效的计费模型 |
| Currency | 租户主币种 |
| Maintenance Fee | 固定月平台费 |
| Variable Service Fees | 按交易计提的费用（各计费模型合计） |
| Cross-Tenant Receivable | 其他租户应付给你方的金额 |
| Cross-Tenant Payable | 你方应付给其他方的金额 |
| Volume (CT) | Cash Token 体量（1 CT = 1 HKD） |
| Net Settlement | 最终净结算金额 |
| Actions | 租户或子公司的 Generate Invoice 按钮 |
子公司结算： 展开租户行后，在选定周期内有结算活动的子公司会以嵌套行显示。各子公司有自己的维护费、可变服务费、跨租户应收/应付、体量、净结算及各自的 Generate Invoice。所选周期内无结算数据的子公司不会出现。
数据一致性
此处数字与各租户在自己管理后台 Settlement 页面看到的一致，计算方式相同：
- Maintenance Fee：来自租户计费设置，汇总到平台时换算为 HKD
- Variable Service Fees：各笔交易的平台费之和，按租户计费币种
- Cross-Tenant Receivable：应收（其他租户用户使用你方礼券等）
- Cross-Tenant Payable：应付给礼券所有者等
金额展示币种
金额按各租户配置的主币种显示。Currency 列标明该租户使用的币种。
跨租户结算详情
对存在跨租户活动的租户查看结算详情时，会额外显示：
- Cross-Tenant Context：结算涉及跨租户礼券使用时说明上下文
- HKD Equivalents：为跨币种汇总，金额同时展示 HKD（Cash Token）等价
- Exchange Rate Info：展示交易时点使用的汇率，便于核对
Cross-Tenant Flow 标签
可视化平台上不同租户之间礼券使用与结算流向。
结算计算方法
超级管理后台与各租户管理后台采用一致算法，确保数字对齐：
平台费计算
Maintenance Fee：从租户计费设置读取（计费币种），再换算为 HKD 供平台聚合。
Variable Service Fees：所有交易中
platformFee之和，按租户计费模型费率计算，存放在租户计费币种。对于 percentage 和 token value percentage 费率类型，若代币锚定法币与租户计费币种不一致，系统会通过 HKD 中介换算代币法币价值后再按比例计费。净结算公式：
Net Settlement = Platform Fees + Cross-Tenant Payable - Cross-Tenant Receivable 其中： Platform Fees = Maintenance Fee + Variable Service Fees
币种换算链路
结算金额会自动换算到各租户主币种。HKD（Cash Token）作为跨币种换算中介：
原币种 → HKD（Cash Token 中介）→ 租户主币种当礼券结算币种与租户主币种不一致时，系统在交易时点换算并以租户主币种入库。
对于基于代币价值的费率计算（percentage 与 token_value_percentage 费率类型），若代币锚定法币与租户计费币种不同（如代币锚定 USD，计费币种为 HKD），代币法币价值也会通过 HKD 中介换算后再应用费率：
代币法币价值（如 USD）→ HKD → 租户计费币种（如 HKD）
费用 = 换算后价值 × 费率 / 100跨租户结算与汇率
跨租户使用且币种不同时，系统自动按汇率换算以保证结算准确：
如何工作
- 交易入账：发生时将结算金额换算为租户的 主币种（计费设置中配置）。同时计算 HKD（Cash Token）等价用于跨币种聚合。若礼券或代币以其他币种创建，经 HKD 中介换算。
- 主币种强制：某租户的所有结算记录以该租户主币种存储。跨租户场景中，使用方记录用使用方主币种，券主应收记录用券主主币种。
- HKD 作为聚合币种：跨租户金额同时保存 HKD（Cash Token）等价。
- 展示：报表中按各租户配置的主币种显示。
跨租户示例
- Tenant A（THB）创建面值 1,000 THB 的礼券
- Tenant B（HKD）的用户核销该礼券
- 系统按当前汇率换算：1,000 THB → 220 HKD（Cash Token）
- Tenant B 的交易记录：存为 220 HKD（其主币种）
- Tenant A 的应收记录：存为 1,000 THB（其主币种）
- 两条记录均保存 Cash Token（HKD）等价以便跨租户聚合
汇总页脚
报表页脚合计始终以 HKD 展示，以保证跨币种口径一致。
一致聚合
计算跨租户应收/应付汇总时，系统使用 cashTokenAmount（HKD 等价），避免直接将不同币种金额相加出错。
Transactions 标签
提供全平台结算相关交易的明细列表，支持搜索、筛选与分页。
展开行详情
点击租户行可展开：
- Sub-Company Breakdown（如有）：各子公司结算指标表
- 平台费拆分（维护费 + 可变费）
- 跨租户明细及 HKD 等价
- 计费相关活动（交易笔数）
- 净结算公式
- View Invoices 快速跳到 Invoices 标签
生成发票
在 Tenant Settlements 标签可为单个租户或子公司生成发票：
- 租户： 在该租户行的 Actions 列点击 Generate Invoice
- 子公司： 先展开租户行，再在子公司行 Actions 点击 Generate Invoice
弹窗中选择计费区间（开始、结束日期）。发票仅针对所选租户或子公司。要对所有租户批量生成，前往 Invoices 标签使用 Generate Batch。
发票编号
全局唯一编号格式 INV-YYYYMM-XXXX：
YYYY：四位年份MM：两位月份XXXX：当月序号（全平台共用，按月重置）
示例：INV-202603-0001、INV-202603-0002 …
发票 PDF
生成的 PDF 含：
- Header：发票号、日期、到期日、状态
- Bill To：租户名称、邮箱、地址
- Billing Period：起止日期、计费模型
- Usage Summary：总核销数、消费量、跨租户交易
- Line Items：费用明细
- Summary：平台费、跨租户应付/应收、应付总额
PDF 币种
PDF 中金额按租户配置的主币种显示，并使用常见货币符号（如 HKD 用 HK$，USD 用 $）。
Invoices 标签
展示全平台已生成发票，可查看、下载与管理记录。
9. 租户计费
管理平台侧全部租户的计费。
如何使用：
- 查看所有租户计费状态
- 生成租户发票
- 配置计费方案与价格
- 跟踪付款状态
- 处理计费争议
配置租户计费
各租户计费在其 租户详情页配置：
- Primary Currency：所有计费项目的统一币种
- Billing Models：哪些交易类型产生费用
- Rate Configuration：按笔或按比例费率（支持小数，如 0.25 或 1.5%）
- Maintenance Fee：固定月平台费（支持小数）
币种一致性
设置租户主币种后：
- 所有结算记录以此币种存储（交易时点自动换算）
- 新建礼券默认结算币种为此币种
- 平台费按此币种金额计算
- 结算报表以此币种展示
- 发票以此币种开具
- 跨租户结算分别按各方主币种入账并做适当换算
10. Brand Tags（品牌标签）
管理租户可在礼券中选择的集中品牌池。品牌均为平台级资源 — 租户不能自建品牌，只能从此池选用。
如何使用：
- 在品牌池查看全部平台品牌标签
- 新建品牌：名称、说明、Logo 图
- 编辑现有品牌（名称、说明、Logo、启用状态）
- 删除品牌（同时从所有租户已选列表中移除）
- 查看各品牌被哪些租户使用
创建品牌标签
- 点击 "Create Brand Tag"
- 输入品牌名（必填，最多 50 字符）
- 上传 Logo 图（可选，最大 2MB，JPG/PNG）
- 填写说明（可选）
- 点击 "Create" 加入平台池
仅支持上传图片
Logo 必须为上传文件；不支持 URL，以便安全与展示一致。
查看租户使用情况
查看某品牌被哪些租户使用：
- 在品牌卡片上点击 "View Tenants"
- 弹窗显示：
- 已将该品牌加入选择的租户列表
- 各租户添加日期
- 状态（Active/Inactive）
- 使用该品牌的租户总数
品牌生命周期
| 操作 | 结果 |
|---|---|
| Create | 品牌进入平台池，所有租户可选用 |
| Edit | 变更立即对所有已选该品牌的租户生效 |
| Deactivate | 仍保留在各租户选择中，但新选择时平台上不再推荐使用 |
| Delete | 从所有租户选择与平台池中移除 |
删除品牌
删除品牌会自动从所有已选租户中移除，不可恢复。若仅需保留租户侧关联，可优先考虑停用而非删除。
租户侧流程
- 超级管理员在本页维护品牌池
- 租户管理员在管理后台 「Platform Brand Tag」 标签浏览
- 将需要的品牌加入 「My Brand Tag」
- 创建礼券时只能从 「My Brand Tag」 中选品牌
11. API Keys（平台 API 密钥）
管理平台级 API 密钥与访问权限。
如何使用：
- 查看全部平台 API 密钥
- 生成新密钥
- 配置权限与 scope
- 撤销泄露密钥
- 监控使用情况
12. Settings（平台设置）
配置全平台默认值与全局设置。
如何使用：
- 查看礼券使用相关设置 — PIN 前缀现为按租户管理（创建租户时自动分配）。各租户唯一的 2 位前缀可在租户列表与租户详情中看到。
- 查看平台信息（名称、版本、环境）
- 查看数据库连接状态
- 配置 Web3 Asset Service（代币、NFT、钱包管理）
Need Help？
如需平台级支持，请联系 VIO 技术支持团队。