代理迁移使用指南
这篇文档给后台操作者使用。它不解释接口和数据库，只说明三件事：
- 什么时候可以迁移代理。
- 弹窗里为什么要求补授权、填价格、处理结算或余额。
- 遇到阻断时应该怎么处理，怎样提前避免。
基本规则
代理在一棵树里工作。上级决定下级能管理哪些软件、能卖哪些卡类型、成本价是多少、拥有哪些权限，以及这些权限能不能继续下发。
因此，迁移不是简单改一个上级：
- 迁移后，新父级链路必须能承接源代理原有能力。
- 代售结算必须已经支付结清。
admin 是整棵代理树的根，会显示在代理树和代理列表中，也可以作为普通代理的上级。admin 自身不能迁移，也不能删除。
迁移前检查
迁移前建议按下面顺序检查：
| 检查项 | 要求 |
|---|---|
| 代理状态 | 源代理子树、目标父级以及目标父级到 admin 的链路都必须是正常状态 |
| 结算 | 源代理子树内的代售结算必须已经生成结算单、审核，并标记支付 |
| 代理类型 | 余额充值类型的普通父级下面不能接入代售结算子树 |
| 软件授权 | 目标父级链路必须能提供源代理已有的软件授权 |
| 卡类型授权 | 目标父级链路必须能提供源代理已有的卡类型授权和价格 |
| 卡类型价格 | 成本价必须满足上级不高于下级 |
| 权限 | 目标父级链路必须有人拥有该权限，并且允许下发 |
如果这些条件都满足，迁移通常可以完成。若有差异，弹窗会要求确认自动补链、填写价格，或提示硬阻断。
如何迁移
在代理列表、代理树、蓝图或在线代理页中，打开代理操作菜单，选择“迁移节点”。
迁移弹窗会让你选择新的父代理。系统会自动阻止把代理迁到自己或自己的下级下面，因为这会让代理树形成环。
预检结果通常有三类：
| 结果 | 含义 | 操作 |
|---|---|---|
| 可以直接迁移 | 新父级已经完全覆盖源代理能力 | 填写原因后执行迁移 |
| 需要补链或补价 | 系统可以补齐授权，但需要你确认或填写价格 | 按弹窗要求确认、填价 |
| 存在硬阻断 | 系统不能安全补齐能力，或结算/状态不满足 | 先处理阻断，再重新预检 |
如果同时出现“子树链路待填价”和“源代理待填供货价”，先填“子树链路待填价”，再填“源代理待填供货价”。源代理价格不能低于迁移后直接父级的价格。
自动补授权是什么意思
迁移后，目标父级必须覆盖源代理的能力。如果目标父级暂时缺少某项能力，但它的上级链路中有人能提供，系统可以把这项能力补到目标父级链路上。
例如：
admin -> A -> P
S 要迁移到 P 下面
S 拥有软件 X
P 没有软件 X，但 A 拥有软件 X这种情况下，系统可以提示自动把软件 X 补给 P。你确认后，迁移可以继续。
如果从 P 往上一直到 admin 都没有任何一层能提供软件 X，系统不会凭空创建授权，会阻止迁移。
卡类型授权和权限也是同样规则。权限还多一个条件：上级不只是“拥有权限”，还必须把该权限设置为“可下发”。
卡类型价格规则
卡类型价格表示代理的供货成本。系统要求价格链不能倒挂：
上级成本价 <= 下级成本价 <= 更下级成本价如果新父级某张卡的价格比源代理原价更高，源代理迁移后必须重新设置价格。
例如：
| 代理 | Core Monthly 成本价 |
|---|---|
| 新父级 P | 2.00 元 |
| 源代理 S 原价 | 1.20 元 |
迁移后 S 不能继续用 1.20 元。你必须把 S 的 Core Monthly 价格设置为至少 2.00 元。
待重定价
迁移或上级普通涨价后，直接下级可能出现价格倒挂。系统不会静默改完整棵子树的价格，而是生成“待重定价项”。
例如：
S 新价格 = 2.00 元
S 的下级 C 当前价格 = 1.20 元迁移可以成功，但 C 子树会进入待重定价状态：
- C 和 C 的下级暂时不能制作这张卡类型。
- S 本人不因此被禁止制卡。
- S 需要给 C 重新设置不低于 2.00 元的价格。
- 如果 C 重新定价后又影响 C 的下级，待重定价会继续向下传递。
这能避免系统偷偷改价，同时保证卡密成本链始终正确。
常见迁移阻断
不能迁移 admin
admin 是代理树根节点，不能作为源代理迁移。请选择 admin 下面的普通代理。
不能迁移到自己的子树
目标父级不能是源代理自己，也不能是源代理的下级。请换到源代理子树外的目标父级。
源子树或目标父链有非正常代理
迁移要求源代理子树、目标父级和目标父级到 admin 的链路都是正常状态。若其中有人被禁用，需要先启用或处理为正常状态。
余额充值父级下不能接入代售结算子树
余额充值和代售结算的业务口径不同。普通余额充值代理下面不能出现代售结算代理。请改迁到代售结算父级或 admin 下。
存在未支付结算
源代理或它的下级还有代售结算没有支付结清。结算单只生成或只审核通过还不够，必须标记支付。请先创建结算单、审核并标记支付，再迁移。
目标父链无法提供软件授权
源代理拥有某个软件，但目标父级链路没有任何一层能提供该软件。请换目标父级，或先在目标链路上补齐软件授权。
目标父链无法提供卡类型授权
源代理拥有某个卡类型，但目标父级链路无法提供该卡类型和价格。请换目标父级，或先整理目标链路的卡类型授权和价格。
源代理价格低于新父级
迁移后源代理的价格不能低于新父级价格。按弹窗最低价填写即可。
目标父链无法提供权限
源代理拥有某个权限，但目标父级链路没有任何一层同时满足“已授予”和“可下发”。请让目标父级的上级先授予并允许下发，或换一个能提供该权限的目标父级。
未知权限
源代理持有系统不认识的权限 key。通常是开发或历史数据导致。请通过权限配置界面重新整理，不要直接写数据库补权限。
迁移成功后检查
迁移完成后建议检查：
- 源代理是否出现在新父级下面。
- 授权软件、卡类型、权限是否符合预期。
- 是否出现待重定价弹窗。
- 受影响下级是否已经完成重新定价。
- 代售结算代理是否仍处在正确的结算链路里。
如果出现待重定价，应优先处理。未处理前，相关下级子树不能制作对应卡类型。
删除代理
代理删除是另一类永久操作，会涉及按软件迁移用户和卡密、处理余额、检查结算阻断，以及“删除当前代理并上提子代理”和“删除整棵子树”两种模式。
请阅读 代理删除使用指南。
建议操作顺序
大规模调整代理树时，建议按这个顺序处理：
- 先处理结算：涉及子树的代售结算全部创建、审核并标记支付。
- 再处理状态：确认源子树和目标链路都处于正常状态。
- 再处理授权：确认目标父级或迁移目标能覆盖软件、卡类型和权限。
- 再处理价格：确认价格链不会倒挂。
- 最后执行迁移或删除。
如果迁移后出现待重定价，先处理待重定价，再让下级继续制卡。