GameItem模块物品冻结功能设计文档

任务时间： 2025年06月12日 11:11
任务类型： 功能设计
模块： GameItems

任务背景

在实现匹配交易的过程中，当用户发起卖出物品订单时，需要冻结该物品，防止用户在订单处理期间使用、交易或消耗这些物品。目前GameItem模块缺少物品冻结机制，需要设计并实现完整的物品冻结功能。

现状分析

当前物品状态管理

ItemUser表：记录用户物品关联，包含数量、过期时间等基本信息
ItemInstance表：单独属性物品实例，包含绑定状态(is_bound)、交易状态(tradable)
交易日志：通过ItemTransactionLog记录所有物品流转
状态枚举：已有TRANSACTION_TYPE、ITEM_BIND_TYPE等状态管理

缺失的功能

缺少物品冻结状态字段
缺少冻结/解冻操作逻辑
缺少冻结状态验证机制
缺少冻结记录追踪

设计方案

数据库设计

ItemUser表扩展（拆堆模式）

在item_users表中新增冻结相关字段：

is_frozen - 是否冻结状态（布尔值）
freeze_log_id - 冻结日志ID，关联冻结记录表

拆堆机制：冻结时将原堆叠拆分为冻结部分和可用部分两个独立记录，例如1000个物品冻结200个时，拆分为200个（冻结）+ 800个（可用）。

重要修正：ItemInstance表不需要扩展冻结字段，因为ItemInstance是物品实例表，记录的是物品的基本信息和属性，而不涉及物品归属关系。冻结功能是针对用户拥有的物品进行的操作，应该在ItemUser表中实现。

冻结记录表

创建专门的冻结记录表item_freeze_logs用于追踪所有冻结操作，使用source_id和source_type记录操作方信息。

枚举定义

冻结操作类型

class FREEZE_ACTION_TYPE
{
    const FREEZE = 1;    // 冻结
    const UNFREEZE = 2;  // 解冻
}

冻结原因类型

class FREEZE_REASON_TYPE
{
    const TRADE_ORDER = 'trade_order';      // 交易订单
    const ADMIN_FREEZE = 'admin_freeze';    // 管理员冻结
    const SYSTEM_FREEZE = 'system_freeze';  // 系统冻结
    const AUCTION = 'auction';              // 拍卖
    const MAIL_ATTACHMENT = 'mail_attachment'; // 邮件附件
}

模型扩展

ItemUser模型扩展

新增冻结相关字段：is_frozen和freeze_log_id
添加isFrozen()检查是否为冻结状态
添加isAvailable()检查是否可用
添加getAvailableQuantity()静态方法获取用户可用物品总数
添加freezeLog()关联冻结日志记录

修正：ItemInstance模型不需要扩展冻结相关字段和方法，冻结状态在ItemUser表中管理。

逻辑层实现

ItemFreeze逻辑类（拆堆模式）

核心方法包括：

freezeNormalItem() - 冻结统一属性物品，拆堆实现，创建冻结记录
freezeUniqueItem() - 冻结单独属性物品，直接标记is_frozen=true
unfreezeByLogId() - 根据冻结日志ID解冻物品，可选择合并或保持独立
getAvailableQuantity() - 获取用户可用物品数量（排除冻结堆叠）
checkAvailableQuantity() - 验证用户是否有足够的可用物品

服务层扩展

ItemService扩展

freezeItem() - 冻结物品
unfreezeItem() - 解冻物品
getAvailableQuantity() - 获取可用数量
getFrozenItems() - 获取冻结物品列表

集成方案

与交易系统集成

创建卖出订单时：自动冻结对应数量的物品
订单完成时：解冻物品并执行消耗操作
订单取消时：解冻物品恢复可用状态
订单失败时：解冻物品并记录失败原因

与现有验证集成

消耗物品前：检查可用数量（总数量-冻结数量）
交易物品前：验证物品未被冻结
使用物品前：确认物品处于可用状态

解冻机制

主动解冻：由冻结发起方（如交易系统、管理员等）主动调用解冻方法
日志追踪：通过freeze_log_id关联冻结记录，确保解冻操作的准确性

实现优先级

第一阶段（核心功能）

数据库表结构修改
模型字段和基础方法扩展
冻结/解冻核心逻辑实现
基础验证机制

第二阶段（集成功能）

与交易系统集成
服务层方法完善
管理后台界面
冻结记录查询

第三阶段（优化功能）

批量操作优化
性能监控和优化
异常情况处理
冻结记录清理机制

注意事项

数据一致性

冻结操作必须在事务中执行
确保冻结数量不超过实际拥有数量
解冻时验证冻结记录的有效性

性能考虑

冻结状态查询需要适当的索引支持
大量物品冻结时考虑批量操作
定时任务的执行频率和性能影响

业务规则

冻结的堆叠（is_frozen=true）不能被消耗、交易或使用
解冻操作由冻结发起方负责处理，通过freeze_log_id定位
拆堆时需要保证数量守恒：原堆叠数量 = 冻结堆叠数量 + 剩余可用堆叠数量
交易日志不记录冻结相关信息，冻结信息由冻结记录表单独管理
不同冻结原因（source_type）可能有不同的处理逻辑

任务成果

完整的设计文档：创建了详细的物品冻结功能设计文档
数据库设计：设计了完整的数据库表结构扩展方案
架构设计：提供了完整的枚举、模型、逻辑层、服务层设计
集成方案：明确了与交易系统的集成方式
实现计划：制定了三阶段的实现优先级

文件清单

app/Module/GameItems/Docs/冻结实现.md - 物品冻结功能实现思路文档

总结

本次任务成功为GameItem模块设计了完整的物品冻结功能架构，解决了匹配交易中卖出物品需要冻结的核心问题。设计方案涵盖了数据库设计、代码架构、集成方案和实现计划，为后续的代码开发提供了详细的技术指导。

设计方案具有以下特点：

完整性：覆盖了冻结功能的所有方面
可扩展性：支持多种冻结原因和场景
一致性：与现有代码架构保持一致
实用性：提供了具体的实现指导

该设计文档将作为GameItem模块物品冻结功能开发的重要参考资料。

重要修正

版本修正内容：

v1.1：移除了ItemInstance表的冻结扩展设计，因为ItemInstance是物品实例表，记录的是物品的基本信息和属性，而不涉及物品归属关系。
v1.2：简化设计，移除自动解冻逻辑，解冻由发起方处理；冻结记录表使用source_id/source_type替代order_id；简化ItemUser表字段。
v1.3：采用冻结即拆"堆"的模式，使用is_frozen字段标识冻结状态；交易日志不记录冻结信息，冻结信息由冻结记录表单独管理。

12日1111-GameItem模块物品冻结功能设计文档.md 6.9 KB History Raw