diff --git a/README.md b/README.md
index f97815a..d51289f 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,7 @@
 - **生命周期管理**：物联网卡/号卡的开卡、激活、停机、复机、销户
 - **代理商体系**：层级管理和分佣结算
 - **批量同步**：卡状态、实名状态、流量使用情况
+- **分佣验证指引**：对代理分佣的冻结、解冻、提现校验流程进行了结构化说明与流程图，详见 [分佣逻辑正确与否验证](docs/优化说明/分佣逻辑正确与否验证.md)
 
 ## 快速开始
 
diff --git a/docs/优化说明/分佣.md b/docs/优化说明/分佣.md
deleted file mode 100644
index ba05981..0000000
--- a/docs/优化说明/分佣.md
+++ /dev/null
@@ -1,31 +0,0 @@
-### 分佣规则
-
-#### 1.秒返
-
-条件：按指定金额充值且卡激活
-
-返佣：按照具体的情况制定金额
-
-#### 2.次月返
-
-条件：次月卡状态正常，不三无（满足其一即可），且满足首充条件
-
-首充：按卡品的具体套餐定，存在累计充值或一次性充值
-
-三无：无短信/语音/流量
-
-#### 3.长期分佣
-
-条件：运营商给我们结算后，其余条件同次月返
-
-结算月:T0为激活月，可能T23为结算月（Tn为结算周期）
-
-#### 4.按比例分佣
-
-条件：要满足首冲、然后开通状态、无三无情况
-
-### 规则改变可能方向
-
-1.按已充值金额
-
-2.根据套餐
\ No newline at end of file
diff --git a/docs/优化说明/分佣正确逻辑.md b/docs/优化说明/分佣正确逻辑.md
new file mode 100644
index 0000000..49ec257
--- /dev/null
+++ b/docs/优化说明/分佣正确逻辑.md
@@ -0,0 +1,183 @@
+# 分佣逻辑正确与否验证
+
+> **说明**：内容依旧基于「分佣需要确认逻辑」中的假定方案，目标是向需求方展示目前的理解，并请对“是否满足预期”给出反馈；所有表达均属于待确认状态。
+
+## 1. 文档定位与假设
+
+1. 面向运营、产品与研发，讨论“梯度配置 → 佣金生成 → 冻结/解冻 → 提现”全链路。
+2. 最小颗粒度仍假定为 ICCID，系统每日巡检是否满足冻结条件。
+3. 返佣梯度模板只提供初始值，真正起效的是写入“代理商-套餐-返佣规则”的快照。
+4. 梯度条目新增字段：返佣条件（累计充值/一次充值）、返佣条件目标值、是否三无校验、长期终止方式等，均由需求方补充。
+
+## 2. 佣金记录状态（当前理解）
+
+| 状态         | 拟定定义                                                         | 关键属性（供确认）                                             |
+| ------------ | ---------------------------------------------------------------- | -------------------------------------------------------------- |
+| 已冻结       | 佣金记录已写入但暂不可提现，等待巡检与运营凭证                   | 送彩金需人工解冻；凭证来自运营商/上游；需解冻密码              |
+| 正常         | 认为条件已满足，可进入提现申请                                   | 允许发起提现；等待审批                                         |
+| 无效佣金     | 核验发现不满足返佣规则                                           | 永久不可提现；记录无效原因                                     |
+| 提取申请中   | 用户提交提现，尚在审批                                           | 资金冻结；需跟踪审批结果                                       |
+| 提取驳回     | 审批未通过                                                       | 记录驳回原因，处理完后可再次申请                               |
+| 已提取       | 提现审批完成并发放                                               | 记录支付流水与时间                                             |
+
+> 如还需“部分解冻”“自动解冻”等扩展状态，可继续在此表补充。
+
+## 3. 状态切换说明
+
+1. **已冻结 → 正常**：运营导入 ICCID + 凭证（含三无校验结果），输入解冻密码；若上游也确认，则解冻。
+2. **已冻结 → 无效佣金**：巡检或上游发现条件不成立（充值不足/未产生流量语音短信等）。
+3. **正常 → 提取申请中 → 已提取/提取驳回**：提现走审批链条，记录审批结论。
+4. **提取驳回 → 正常**：问题解决后回到可申请状态。
+
+## 4. 冻结与解冻（示例流程）
+
+### 4.1 冻结触发
+
+- ICCID 在某月首次充值，卡状态正常。
+- 每日巡检检查：
+  1. 当前卡状态是否正常；
+  2. 返佣条件类型（累计充值或一次充值）对应的金额是否达标；
+  3. 若“是否三无=是”，需确认流量/语音/短信任一指标产生；
+  4. 判断类型（销售数量或销售金额）是否命中梯度目标值。
+- 满足上述组合后写入“已冻结”佣金。
+
+### 4.2 解冻动作
+
+- 运营通过 Web/Excel 导入需解冻的 ICCID 列表。
+- 操作人输入解冻密码（可拓展为双人校验）。
+- 系统对比运营商/上游凭证，符合即批量解冻；不符则继续冻结或转为无效。
+
+### 4.3 数据来源
+
+- 运营商官方结算单。
+- 上游渠道对账单。
+- 其他可信来源（需要在系统内记录来源，以便审计追溯）。
+
+### 4.4 结果
+
+- 凭证齐全 → 状态切到“正常”。
+- 不满足条件 → “无效佣金”。
+- 信息不足 → 维持“已冻结”。
+
+## 5. 返佣梯度字段（含新增项）
+
+1. **判断类型**：套餐销售数量 / 套餐销售金额。
+2. **判断目标值**：对应的数量或金额门槛。
+3. **返佣属性**：比例金额 / 固定金额。
+4. **返佣假定值**：如 10% / 10 元等。
+5. **返佣时效**：即可返佣 / 延迟返佣。
+6. **是否长期**：是（每月重复）/ 否（仅一次）。
+   - 若选择“是”，需额外配置终止方式：
+     - 指定持续月数（例：36 个月内有效）。
+     - 或指定终止日期（例：截至 2026-11-20）。
+7. **返佣条件类型**：累计充值 / 一次充值。
+8. **返佣条件目标值**：具体金额门槛（例：累计 100 元或一次 100 元）。
+9. **是否三无**：是 → 必须满足流量/语音/短信任一用量；否 → 默认无需此校验。
+
+### 5.1 示例条目（即时返佣 + 长期到期日）
+
+- 判断类型：套餐销售金额
+- 返佣时效：即可返佣
+- 返佣条件：累计充值 ≥ 100 元
+- 是否三无：否
+- 是否长期：是，终止日期 2026-11-20
+
+| 套餐类型     | 判断目标值 | 返佣属性 | 返佣假定值 |
+| :----------: | :--------: | :------: | :--------: |
+| 套餐销售金额 | 2000 元    | 固定金额 | 10 元      |
+| 套餐销售金额 | 4000 元    | 固定金额 | 15 元      |
+| 套餐销售金额 | 10000 元   | 比例金额 | 10%        |
+| 套餐销售金额 | 50000 元   | 比例金额 | 20%        |
+
+### 5.2 示例条目（延迟返佣 + 长期月数 + 三无）
+
+- 判断类型：销售套餐数量
+- 返佣时效：延迟返佣（冻结）
+- 返佣条件：一次性充值 ≥ 100 元
+- 是否三无：是（需满足流量/语音/短信任一用量）
+- 是否长期：是，持续 36 个月
+
+| 套餐类型     | 判断目标值 | 返佣属性 | 返佣假定值 |
+| :----------: | :--------: | :------: | :--------: |
+| 销售套餐数量 | 20 个      | 固定金额 | 10 元      |
+| 销售套餐数量 | 40 个      | 固定金额 | 15 元      |
+| 销售套餐数量 | 60 个      | 固定金额 | 20 元      |
+| 销售套餐数量 | 120 个     | 比例金额 | 10%        |
+| 销售套餐数量 | 130 个     | 比例金额 | 20%        |
+
+### 5.3 模板与快照玩法
+
+1. 预设多套梯度模板（包含全部字段）。
+2. 给代理分销套餐时选择模板，写入“代理商-套餐-返佣规则”，这一刻生成快照。
+3. 若模板不合适，可即时调参，结果仅作用于该代理的快照，不影响原模板。
+
+## 6. 分佣类型与时效/长期标记
+
+1. **立即返佣**：命中梯度且“返佣时效=即可”，直接生成“正常”佣金，可发起提现。
+2. **延迟返佣**：命中梯度但“返佣时效=延迟”，生成“已冻结”佣金，等巡检+凭证后解冻。
+3. **长期 vs 一次性**：若标记“长期=是”，每月满足条件都重复以上流程，直至达到配置的终止月份或日期；若“否”，仅首次写入。
+
+## 7. 返佣金额计算
+
+### 7.1 比例返佣
+
+- 按成本价乘以返佣比例。
+- 示例：成本 100 元，返佣 10%，代理得 10 元，上级留存 90 元。
+
+### 7.2 固定金额返佣
+
+- 从成本价中拆出固定金额。
+- 示例：成本 100 元，固定返佣 10 元，代理每卖一份获得 10 元。
+
+> 若需要多级代理差额分摊，可在后续补充案例。
+
+## 8. 参考流程图（覆盖新字段）
+
+```mermaid
+flowchart TD
+    A["预设返佣梯度模板<br/>(含判断类型/目标值/时效/条件/三无等)"] --> B[分销套餐选择模板]
+    B --> C{需要调整模板值?}
+    C -->|否| D[直接写入代理-套餐-返佣规则快照]
+    C -->|是| E[按协商修改目标/比例/条件/时效]
+    E --> D
+    D --> F[代理销售套餐]
+    F --> G{达到梯度判断目标?}
+    G -->|否| G1[不生成佣金记录]
+    G -->|是| H["写入佣金记录<br/>(含时效/长期/条件/三无标记)"]
+    H --> I{返佣时效}
+    I -->|即可返佣| J["生成正常佣金 → 可发起提现"]
+    I -->|延迟返佣| K[生成冻结佣金]
+    K --> L["每日巡检<br/>1. 卡状态<br/>2. 返佣条件金额<br/>3. 三无校验"]
+    L --> M{巡检结果}
+    M -->|不满足| N[标记无效佣金]
+    M -->|满足| O[运营提交解冻名单 + 解冻密码]
+    O --> P{上游/运营商凭证匹配?}
+    P -->|是| Q[状态改为正常]
+    P -->|否| R[保持冻结或升级为无效]
+    J --> S[提交提现申请]
+    Q --> S
+    S --> T{审批结果}
+    T -->|通过| U[状态=已提取]
+    T -->|驳回| V["状态=提取驳回 → 原因记录 → 回到正常"]
+```
+
+## 9. 核验清单（滚动更新）
+
+1. **模板即快照**：确认需求方已认可“模板只是初始值，写入后独立”的做法。
+2. **字段完整性**：判断类型、目标值、返佣属性/假定值、时效、长期、返佣条件类型与目标值、是否三无，是否还需追加封顶金额、最低到账天数等字段？
+3. **巡检周期**：默认每日，是否需要在配置中开放？
+4. **三无策略**：仅当“是否三无=是”时才校验流量/语音/短信是否产生，逻辑是否符合需求？
+5. **审批链路**：提现审批角色、SLA、驳回原因记录是否需要更细化？
+6. **审计/导出**：无效佣金与驳回清单是否需要导出或定期复盘？
+
+## 10. 后续讨论点
+
+1. 延迟返佣 + 长期标记时，是否意味着每月都会触发冻结/解冻循环？
+2. 运营商提供的结算文档是否为“全量数据”（即包含可返佣与不可返佣的 ICCID），以便我们比对三无和解冻名单？
+---
+
+> 如 `docs/优化说明/分佣需要确认逻辑.md` 有新的补充，请继续同步，本文件将保持“假设 → 核验 → 反馈”的循环输出。
+
+---
+
+> 本文档持续依赖 `docs/优化说明/分佣需要确认逻辑.md` 的最新内容，若原始假设变化，请同步更新此文件以便再次生成。
diff --git a/docs/优化说明/分佣正确逻辑补充.md b/docs/优化说明/分佣正确逻辑补充.md
new file mode 100644
index 0000000..3ca56f5
--- /dev/null
+++ b/docs/优化说明/分佣正确逻辑补充.md
@@ -0,0 +1,31 @@
+### 1.佣金回溯（待确认）
+
+若客户退款导致佣金回溯，但代理账户无佣金是否支持负数，下次抵扣
+
+待确认是否存在回款周期等条件
+
+### 2.修改冻结状态
+
+已冻结-——正常：除ICCID外，支持号码导入（例如：号卡的号码）
+
+### 3.是否三无
+
+区分号卡，物联网卡不用三无校验
+
+### 4.实时显示代理分佣金额
+
+若代理的产品状态满足分佣条件，则同步分佣金额
+
+### 5.审批链路
+
+增加：操作人（放款人），进行操作留痕
+
+### 6.导出
+
+⽆效佣⾦与驳回清单需要导出
+
+代理的佣金梯度也可以导出
+
+### 7.延迟返佣 + ⻓期标记时，是每⽉都会触发冻结/解冻循环
+
+### 8.运营商提供的结算⽂档不是“全量数据”
diff --git a/docs/优化说明/分佣需要确认逻辑.md b/docs/优化说明/分佣需要确认逻辑.md
new file mode 100644
index 0000000..a35c812
--- /dev/null
+++ b/docs/优化说明/分佣需要确认逻辑.md
@@ -0,0 +1,216 @@
+# 关于分佣
+
+## 佣金记录
+
+所有产生的佣金都将存在一条佣金记录,每条佣金记录都存在 已冻结/正常/无效佣金/已提取/提取驳回/提取申请中 等状态
+
+### 已冻结状态
+
+已冻结佣金拥有以下属性
+
+* 无法被提现
+
+* 需要运营人员提供凭证
+
+***例子: 一个ICCID(一张卡)在2月再我们平台首次充值,卡正常使用,状态正常,一直使用到次月,每天系统会检查该ICCID是否满足***
+```
+1. 检查时刻-卡状态正常
+2. 检查时刻之前是否达成的金额条件(一次性充值/累计充值)
+3. 是否产生 流量/语音/短信
+```
+***如以上条件皆满足,则会产生一条佣金记录,该佣金记录为冻结状态***
+
+***解冻条件:***
+
+* 提供需要解冻的ICCID数据(web界面操作/excel导入)
+* 拥有解冻密码
+
+***解冻数据可能来源***
+
+* 运营商
+* 某个上游
+
+
+***已冻结状态变更可能性***
+
+- 正常 ( 我们的上游/运营商给了我们该ICCID的佣金即可再系统解冻)
+- 无效佣金 (我们的上游/运营商在做结算的时候发现该iccid不满足上方例子中的情况)
+
+### 正常状态
+
+正常状态的佣金记录为可以被提交提佣申请的,没有特殊说明的意义
+
+### 无效佣金
+
+无效佣金有以下属性
+
+* 无法被提取佣金
+
+* 无效原因-如(我们的上游/运营商在做结算的时候发现该iccid不满足上方已冻结例子中的情况)
+
+### 已提取
+
+已提取拥有以下属性
+
+- 佣金提现申请已通过
+
+### 提取申请中
+
+提取申请中拥有以下属性
+
+- 已操作提现申请
+
+- 提现申请还未通过
+
+
+### 提取驳回
+
+提取驳回拥有以下属性
+
+- 提交的提现申请被拒绝
+
+- 会有拒绝原因
+
+
+## 返佣梯度
+
+返佣梯度属性:
+
+```
+1. 判断类型
+- 套餐销售数量 (按照套餐销售数量来判断)
+- 套餐销售金额 (按照套餐销售金额来判断)
+
+2. 判断目标值
+- 套餐销售数量需要达到[多少] 
+- 套餐销售金额需要达到 [多少] 
+
+3. 返佣属性
+- 比例金额 (从我们给出去的成本价格中分出去百分之多少作为佣金)
+- 固定金额 (从我们给出去的成本价格中分出去具体金额作为佣金)
+
+4. 返佣假定值
+- 具体比例 如 10%
+- 具体金额 如 10元
+
+5. 返佣时效
+- 即可返佣
+- 延迟返佣
+
+6. 是否长期
+- 是 (每个月都会产生佣金)
+- 否 (只会产生一次)
+
+if 如果为长期分佣 
+
+6.1 终止时间
+- 分佣多少月 (一共分佣多少个月)
+- 指定目标日期 (到哪个时间点后就不分佣了)
+
+7. 返佣条件
+- 累计充值
+- 一次充值
+
+8. 返佣条件目标值
+- 累计充值金额 (要充多少钱才给分佣)
+- 一次充值金额 (要一次性充多少钱才给分佣)
+
+9. 是否三无
+- 是 (必须满足 流量/语音/短信 其一产生用量)
+- 否 (默认否)
+```
+
+我们可以设置多个梯度
+
+例:
+
+返佣时效: 即可返佣
+返佣条件: 累计充值
+返佣条件目标值: 100元
+是否三无: 否
+是否长期: 是
+终止时间: 2026-11-20
+
+|套餐类型|判断目标值|返佣属性|返佣假定值|
+|:-----:|:----:|:-----:|:-----:|
+|套餐销售金额|2000元|固定金额|10元|
+|套餐销售金额|4000元|固定金额|15元|
+|套餐销售金额|10000元|比例金额|10%|
+|套餐销售金额|50000元|比例金额|20%|
+
+例:
+
+返佣时效:延迟返佣
+返佣条件: 一次性充值
+返佣条件目标值: 100元
+是否三无: 是
+是否长期 是
+终止时间 36个月
+
+|套餐类型|判断目标值|返佣属性|返佣假定值|
+|:-----:|:----:|:-----:|:-----:|
+|销售套餐数量|20个|固定金额|10元|
+|销售套餐数量|40个|固定金额|15元|
+|销售套餐数量|60个|固定金额|20元|
+|销售套餐数量|120个|比例金额|10%|
+|销售套餐数量|130个|比例金额|20%|
+
+
+返佣梯度分两种操作场景
+
+1. 预设模板,我们可以预先设置很多分佣梯度,在给代理分销套餐/产品的时候可以直接使用这个预设模板
+
+2. 当我们在给某个代理商分销套餐/产品的时候[我们觉得这个代理需要调整一下比例/目标 | 代理商与我们已经商定过规则],我们还可以更改某个代理商的梯度
+
+返佣梯度主要是这样玩
+
+1. 预设返佣梯度模板
+
+2. 分销套餐给代理 分销的时候需要选择梯度模板
+
+3. 发现模板值不适合修改值
+
+(值我们会写入到代理商-套餐-返佣规则里面 也就是说预设的返佣梯度只是一个模板,不会影响实际返佣判断)
+
+## 分佣类型
+
+我们的分佣大类只分为两种
+
+### 立即返佣
+
+在规定的规则内即可产生正常的佣金
+
+### 延迟返佣(冻结返佣)
+
+在规定的规则内产生已冻结的佣金,只能被手动解冻
+
+## 返佣金额
+
+```
+以下返佣金额设置都受返佣梯度影响
+```
+
+### 比例返佣
+```
+按照给予的成本价比例返佣
+例:
+
+1. 上级设置套餐成本价格为100 返佣比例为10%,则对于上级而言卖出去一个套餐获得90元,对于直属下级而言他如果按照100的成本价格销售出去则获得10元的佣金
+```
+
+### 固定金额返佣
+
+```
+按照给予的成本价从分出去固定金额为返佣
+
+例:
+
+1. 上级设置套餐价格为100 返佣金额为 10元 则对于上级而言卖出去一个套餐获得90元, 对于直属下级而言他如果按照100的价格销售出去则获得10元的佣金
+```
+
+
+
+## 问题
+
+1. 延迟返佣 + 长期标记时，是否意味着每月都会触发冻结/解冻循环？
+2. 运营商提供的结算文档是全量的吗,全量指 能返佣 + 不能返佣的iccid集合