# 战意无损回退功能 

## 一、功能说明

战意无损回退功能允许玩家将战意等级回退，回退后战意格子变为空（等级0），并返还消耗的材料。回退需要消耗特定数量的1050道具。

**重要说明：** 回退后战意格子会清空（变为空状态），而不是回退到上一级。所有等级（1-4）都可以回退，回退后都变为空（0级）。

## 二、战意等级定义

| 等级 | 名称 | 说明 |
|------|------|------|
| 0 | 空 | 未装备战意，回退后的状态 |
| 1 | 初级 | 最低等级，可回退（回退后变为空） |
| 2 | 中级 | 可回退（回退后变为空） |
| 3 | 高级 | 可回退（回退后变为空） |
| 4 | 超级 | 可回退（回退后变为空） |

**重要说明：** 所有等级（1-4）回退后，战意格子都会变为空（等级0），而不是回退到上一级。

## 三、回退消耗和返还

### 3.1 回退消耗

| 当前等级 | 消耗道具 | 消耗数量 |
|---------|---------|---------|
| 初级(1) | 1050道具 | 1个 |
| 中级(2) | 1050道具 | 5个 |
| 高级(3) | 1050道具 | 12个 |
| 超级(4) | 1050道具 | 50个 |

### 3.2 回退返还

| 当前等级 | 返还战意 | 返还战意碎片 | 返还远古之灵 |
|---------|---------|-------------|-------------|
| 初级(1) | 1个 | 0 | 0 |
| 中级(2) | 4个 | 10,000 | 0 |
| 高级(3) | 9个 | 40,000 | 0 |
| 超级(4) | 19个 | 90,000 | 100 |

## 四、协议定义

### 4.1 查询回退信息

**协议名：** `CG_BATTLE_WILL_ROLLBACK_QUERY`

**请求参数：**
```json
{
    "heroID": 123,        // int - 英雄ID
    "heroIndex": 1,       // short - 英雄索引
    "index": 1            // byte - 战意索引（战意格子的位置，如1、2、3等）
}
```

**说明：** 需要传入英雄ID、英雄索引和战意索引，服务器会根据这些信息查询该战意格子的当前等级，然后返回回退信息。

**前端调用示例：**
```typescript
// 前端已有 this.dataHero（包含英雄的 id 和 index）
public CG_BATTLE_WILL_ROLLBACK_QUERY(index: number) {
    if (!this.dataHero) return;
    Msg.CG_BATTLE_WILL_ROLLBACK_QUERY(this.dataHero.id, this.dataHero.index, index);
}
```

**返回协议：** `GC_BATTLE_WILL_ROLLBACK_QUERY`

**返回数据：**
```json
{
    "heroID": 123,                // int - 英雄ID
    "heroIndex": 1,               // short - 英雄索引
    "index": 1,                    // byte - 战意索引
    "currentLevel": 2,           // byte - 当前等级（1-4，服务器查询的实际等级）
    "targetLevel": 0,            // byte - 回退后等级（固定为0，表示空）
    "needItem": {                // ItemData - 消耗道具
        "id": 1050,              // 道具ID
        "cnt": 5                 // 消耗数量
    },
    "returnItems": [             // ItemData[] - 返还物品列表（最多5个）
        {
            "id": 战意ID,        // 战意道具ID
            "cnt": 4             // 返还数量
        },
        {
            "id": 战意碎片ID,    // 战意碎片道具ID
            "cnt": 10000         // 返还数量
        }
        // ... 其他返还物品
    ]
}
```

### 4.2 执行回退

**协议名：** `CG_BATTLE_WILL_ROLLBACK_DO`

**请求参数：**
```json
{
    "heroID": 123,        // int - 英雄ID
    "heroIndex": 1,       // short - 英雄索引
    "index": 1            // byte - 战意索引（战意格子的位置）
}
```

**说明：** 需要传入英雄ID、英雄索引和战意索引，服务器会根据这些信息查询该战意格子的当前等级并执行回退。

**前端调用示例：**
```typescript
// 前端已有 this.dataHero（包含英雄的 id 和 index）
public CG_BATTLE_WILL_ROLLBACK_DO(index: number) {
    if (!this.dataHero) return;
    Msg.CG_BATTLE_WILL_ROLLBACK_DO(this.dataHero.id, this.dataHero.index, index);
}
```

**返回说明：** 
- 执行回退后，服务器**不返回专门的协议消息**
- 服务器会直接使用**通用道具发放逻辑**（`GC_ITEM_GET_LIST` 协议）发送返还的道具
- 战意状态更新会通过其他方式通知前端（如刷新英雄数据协议）

## 五、UI交互流程

### 5.1 回退按钮显示

1. **按钮位置：** 在战意升级界面，当前等级 >= 1 时显示"回退"按钮（所有等级都可以回退）
2. **按钮显示内容：**
   - 按钮文字："回退" 或 "无损回退"
   - 按钮上显示消耗道具图标和数量
   - 格式：`[1050道具图标] x数量`

### 5.2 查询回退信息

1. 点击"回退"按钮
2. 发送 `CG_BATTLE_WILL_ROLLBACK_QUERY` 协议
3. 接收 `GC_BATTLE_WILL_ROLLBACK_QUERY` 协议
4. 显示确认对话框

### 5.3 确认对话框

**对话框内容：**
- 标题："确认回退"
- 提示文字："确认进行战意无损回退操作？"
- 显示信息：
  - 当前等级：中级法连
  - 回退后状态：空（战意格子将清空）
  - 消耗道具：[1050道具图标] x5
  - 返还物品列表：
    - [战意图标] x4
    - [战意碎片图标] x10,000
- 按钮：
  - "取消" - 关闭对话框
  - "确定" - 执行回退

### 5.4 执行回退

1. 点击"确定"按钮
2. 发送 `CG_BATTLE_WILL_ROLLBACK_DO` 协议
3. 接收 `GC_ITEM_GET_LIST` 协议（通用道具发放协议，显示返还物品弹窗）
4. 更新战意等级显示（等级变为0，格子显示为空）
   - 可以通过刷新英雄数据协议来更新，或前端根据回退操作直接更新UI

## 六、错误处理

### 6.1 常见错误情况

| 错误码 | 错误信息 | 处理方式 |
|--------|---------|---------|
| - | 当前等级为空（0），无法回退 | 不显示回退按钮 |
| - | 消耗道具不足 | 显示提示："道具不足" |
| - | 背包空间不足 | 显示提示："背包空间不足" |
| - | 技能ID无效 | 显示提示："技能不存在" |

### 6.2 错误提示

所有错误通过 `GC_ERROR` 协议返回，前端显示对应的错误提示。

## 七、注意事项

1. **回退后状态：** 回退后战意格子变为空（等级0），不是回退到上一级
2. **等级限制：** 当前等级为0（空）时，不显示回退按钮；等级1-4都可以回退
3. **道具显示：** 按钮上必须显示消耗道具（1050）的图标和数量
4. **确认对话框：** 必须弹出确认对话框，防止误操作，明确提示回退后格子将清空
5. **返还物品：** 返还物品通过 `GC_ITEM_GET_LIST` 协议显示，与普通获得物品一致
6. **数据更新：** 回退成功后，需要更新战意等级显示为0（空），相关UI需要显示为空状态



## 九、配置数据（代码常量）

### 9.1 配置位置

配置数据直接写在代码中，作为常量定义。文件位置：`script/module/battleWill/BattleWillLogic.lua`

### 9.2 配置数据结构

```lua
-- 战意回退配置
local BATTLE_WILL_ROLLBACK_CONFIG = {
    [1] = {  -- 初级
        needItemID = 1050,              -- 消耗道具ID
        needItemCnt = 1,                -- 消耗数量：1个
        returnBattleWillID = 战意ID,     -- 返还战意道具ID（需要确认实际ID）
        returnBattleWillCnt = 1,        -- 返还战意：1个
        returnFragmentID = 战意碎片ID,  -- 返还战意碎片道具ID（需要确认实际ID）
        returnFragmentCnt = 0,          -- 返还战意碎片：0
        returnAncientSpiritID = 远古之灵ID, -- 返还远古之灵道具ID（需要确认实际ID）
        returnAncientSpiritCnt = 0       -- 返还远古之灵：0
    },
    [2] = {  -- 中级
        needItemID = 1050,
        needItemCnt = 5,                -- 消耗数量：5个
        returnBattleWillID = 战意ID,
        returnBattleWillCnt = 4,        -- 返还战意：4个
        returnFragmentID = 战意碎片ID,
        returnFragmentCnt = 10000,      -- 返还战意碎片：10,000
        returnAncientSpiritID = 远古之灵ID,
        returnAncientSpiritCnt = 0
    },
    [3] = {  -- 高级
        needItemID = 1050,
        needItemCnt = 12,               -- 消耗数量：12个
        returnBattleWillID = 战意ID,
        returnBattleWillCnt = 9,        -- 返还战意：9个
        returnFragmentID = 战意碎片ID,
        returnFragmentCnt = 40000,      -- 返还战意碎片：40,000
        returnAncientSpiritID = 远古之灵ID,
        returnAncientSpiritCnt = 0
    },
    [4] = {  -- 超级
        needItemID = 1050,
        needItemCnt = 50,               -- 消耗数量：50个
        returnBattleWillID = 战意ID,
        returnBattleWillCnt = 19,       -- 返还战意：19个
        returnFragmentID = 战意碎片ID,
        returnFragmentCnt = 90000,      -- 返还战意碎片：90,000
        returnAncientSpiritID = 远古之灵ID,
        returnAncientSpiritCnt = 100   -- 返还远古之灵：100
    }
}
```

### 9.3 配置说明

1. **level索引：** 
   - 数组索引对应战意等级：1=初级，2=中级，3=高级，4=超级
   - 所有等级（1-4）都可以回退，回退后都变为空（等级0）
   - 等级0（空）不需要配置，因为空状态无法回退

2. **needItemID：** 
   - 固定为1050（回退消耗道具）

3. **needItemCnt：** 
   - 不同等级消耗数量不同：初级1个，中级5个，高级12个，超级50个

4. **返还物品：** 
   - 需要确认各道具的实际ID（战意ID、战意碎片ID、远古之灵ID）
   - 如果返还数量为0，则不返还该物品

5. **使用方式：** 
   ```lua
   local config = BATTLE_WILL_ROLLBACK_CONFIG[level]
   if config then
       local needCnt = config.needItemCnt  -- 消耗数量
       local returnWill = config.returnBattleWillCnt  -- 返还战意
       -- ...
   end
   ```


## 十、道具ID说明

需要在代码中确认以下道具ID（具体ID以服务器配置为准）：

- **1050道具ID：** 用于回退消耗的道具（已在配置中）
- **战意ID：** 战意本身的道具ID（需要在代码中填写）
- **战意碎片ID：** 战意碎片的道具ID（需要在代码中填写）
- **远古之灵ID：** 远古之灵的道具ID（需要在代码中填写）

## 十一、协议ID

需要服务器提供以下协议ID：

- `CG_BATTLE_WILL_ROLLBACK_QUERY` 的协议ID
- `GC_BATTLE_WILL_ROLLBACK_QUERY` 的协议ID
- `CG_BATTLE_WILL_ROLLBACK_DO` 的协议ID

**注意：** 执行回退后使用通用的 `GC_ITEM_GET_LIST` 协议发送返还道具，不需要单独的返回协议。

---



