PRD-023 宝石镶嵌与合成

文档编号：PRD-023
版本：v1.0
状态：已通过
适用端：服务端 / 客户端
关联模块：ScenesServer/Item.cpp、tbl/Gem.xml、RecordServer

1. 背景与目标

宝石是装备的二级养成线，当前存在孔位数据未持久化、拆卸后宝石消失、合成成功率可被客户端伪造等问题。本 PRD 统一宝石的孔位、镶嵌、拆卸、合成与属性计算。

目标

• 每件装备最多 4 个孔位，孔位类型与装备品质相关。
• 宝石可镶嵌、拆卸、合成，操作可逆且有成本。
• 属性实时汇总，客户端展示与计算一致。

2. 核心规则

2.1 孔位

装备品质	孔位数	孔位类型
精良	2	攻击/防御
史诗	3	攻击/防御/生命
传说	4	攻击/防御/生命/特殊

• 孔位在装备生成时随机/固定，可使用打孔器新增（最多 4）。
• 孔位有类型限制，宝石类型必须匹配。
• 孔位数据绑定 item_uid，不可转移到其他装备。

2.2 宝石等级

• 宝石 1–10 级，属性随等级指数增长。
• 3 颗同级宝石合成 1 颗高一级宝石，成功率 100%（或按配置）。
• 合成绑定：绑定宝石合成后仍绑定。

2.3 镶嵌与拆卸

• 镶嵌：装备已穿戴/在背包、孔位为空、宝石类型匹配。
• 拆卸：消耗拆卸符，宝石回到背包；背包满则拒绝。
• 拆卸不损失宝石，但绑定宝石拆卸后仍绑定。
• 装备强化/升星不影响孔位与宝石。

3. 服务端设计

3.1 模块职责

模块	职责
GemManager	镶嵌、拆卸、合成、孔位管理
AttributeManager	宝石属性汇总
ItemManager	宝石/拆卸符扣除与返还
RecordServer	孔位、宝石、绑定持久化

3.2 数据结构

struct GemSlot {
    uint8_t socket_index;
    uint8_t socket_type;
    uint32_t gem_item_id;   // 0 表示空
    uint32_t gem_level;
};

struct EquipGemData {
    uint64_t item_uid;
    GemSlot  sockets[4];
};

3.3 协议

方向	协议	说明
C→S	CS_GemInlay	镶嵌
C→S	CS_GemRemove	拆卸
C→S	CS_GemCombine	合成
C→S	CS_GemOpenSocket	打孔
S→C	SC_GemUpdate	孔位/宝石变化
S→C	SC_GemCombineResult	合成结果

3.4 镶嵌流程

CS_GemInlay(item_uid, socket_index, gem_uid)
  → 校验装备归属、孔位存在且为空
  → 校验宝石类型匹配、宝石存在
  → 扣除宝石、写入孔位
  → 重算属性
  → 广播 SC_GemUpdate + SC_AttributeUpdate
  → 异步持久化

3.5 合成与日志

• 合成必须一次消耗 3 颗同级同类宝石，返回 1 颗高一级。
• 使用事务：扣 3 颗、加 1 颗、写日志同时成功。
• 合成日志记录宝石 ID/等级/数量/结果，便于回档。
• 失败配置（如有）需记录随机种子。

4. 客户端设计

• 装备详情显示 4 个孔位，空孔位显示类型图标。
• 点击孔位弹出可镶嵌宝石列表，按类型过滤。
• 宝石对比：显示替换后属性变化。
• 拆卸二次确认，提示消耗与背包空间。
• 合成界面：选择 3 颗同级宝石，预览结果与成功率。
• 属性面板实时刷新宝石加成。

5. 配置与数值

tbl/Gem.xml 字段：

字段	说明
id	宝石 ID
type	攻击/防御/生命/特殊
level	等级
attr	属性类型与数值
next_id	合成后的宝石 ID
combine_count	合成所需数量
bind_type	绑定规则

6. 边界与异常

场景	处理
孔位已满	拒绝镶嵌
宝石类型不匹配	拒绝并提示
背包满时拆卸	拒绝，宝石保留在孔位
装备被分解/出售	先卸下宝石或禁止操作
合成时材料不足	拒绝，不扣任何宝石
重复镶嵌请求	幂等，按孔位当前状态返回
断线	已扣宝石的镶嵌结果保留，重连同步

7. 埋点与运营

• 宝石等级分布、合成成功率、拆卸频率。
• 各类型宝石产出/消耗与市场价格。
• 后台可调整合成数量、属性、打孔成功率。

8. 验收标准

• 4 个孔位的镶嵌/拆卸/打孔正确，属性实时更新。
• 宝石类型、等级、绑定规则校验完整。
• 合成扣 3 返 1，事务一致，无复制。
• 背包满/装备变化/断线时不丢宝石。
• 客户端孔位与属性与服务端一致。