新增商店系统

.tasks/2025-11-08_1_store-system.md

@@ -0,0 +1,115 @@
+# 背景
+文件名: 2025-11-08_1_store-system
+创建于: 2025-11-08_20:01:03
+创建者: LIUBAI095
+主分支: main
+任务分支: (未创建)
+Yolo模式: Off
+
+# 任务描述
+开发商店系统，包含整点刷新商品（商品种类与限购数量由其他插件注册）以及用户可销售一种物品并设定数量，交易使用积分。
+
+# 项目概览
+WPS Bot 插件体系，现有 `WPSConfigAPI` 提供积分管理与签到积分类功能。
+
+# 分析
+目前掌握：
+- 插件通过 `PluginInterface.execute()` 注册数据库模型与唤醒回调，调用 `Architecture.Register` 管理依赖。
+- `WPSAPI` 继承 `BasicWPSInterface`，提供消息发送、命令解析与插件注册工具，现有 `WPSConfigAPI` 管理 `user_info` 表与积分操作。
+- `ClockScheduler` 提供异步定时任务，可通过 `register_clock()` 注册延迟任务，内部使用数据库任务队列并按 `scheduler_tick_ms`（默认1分钟）轮询。
+新增结论：
+- 商店列表无需缓存，依赖确定性的（小时级时间哈希 -> 随机种子）算法来生成；商品列表在未新增注册项时稳定。
+- 用户出售物品由用户手动触发，不受随机商店列表影响。
+新增设计要求：
+- 外部系统通过依赖商店插件类并从 `Architecture` 获取实例，使用成员函数注册商品出售模式。
+- 注册接口接受物品ID（由 `WPSBackpackSystem` 管理）与限购数量，生成一个商品模式ID；同一物品可注册多种限购模式。
+- 随机商品列表从这些模式ID中按整点种子抽取，确保灵活组合。
+- 支持限购 -1 表示不限量商品；支持注册常驻商品（不参与随机列表生成）。
+- 商店命令：`商店` 展示列表和帮助；`购买 <名称/ID> <数量>` 执行购买；`出售 <名称/ID> <数量>` 管理用户出售栏。
+- 背包系统 `WPSBackpackSystem` 提供物品定义表与用户物品数据，需与商店库存/交易逻辑对接；玩家只能同时出售一种物品。
+- 无预设消息模板，需要自行设计输出 Markdown。
+待明确：
+- 商店与用户出售物品需要的数据库结构及现有表：建议系统商品与玩家出售分表存储，便于按各自逻辑维护；系统商品表需记录模式ID与创建时间用于懒加载刷新。
+- 商店刷新仅需在查询时按算法生成，无需计时器任务，不会主动推送消息；仍需定义命令交互的输出格式与多语言提示。
+
+# 提议的解决方案
+- `WPSStoreSystem` 只负责商店列表和公共接口，不再直接注册 `购买`/`出售` 指令；保留现有模式注册、懒加载刷新、积分/背包操作接口。
+- 新增 `WPSStoreBuyCommand` 与 `WPSStoreSellCommand` 两个插件类（继承 `WPSAPI`），分别依赖 `WPSStoreSystem` 与必要的配置/背包模块：
+  - `WPSStoreBuyCommand` 注册 `购买`／`buy`，在 `callback` 中直接接收 `<名称/ID> <数量>` 参数，调用 `WPSStoreSystem` 提供的购买 API，未匹配商品时返回明确错误信息而非帮助。
+  - `WPSStoreSellCommand` 注册 `出售`／`sell`，处理用户出售逻辑（上架、修改、撤单），同样通过 `WPSStoreSystem` 的公共方法执行，并在错误情况下给出具体提示。
+- 在 `WPSStoreSystem` 中抽象公共入口：
+  - `purchase_item(user_id, chat_id, identifier, quantity)`，区分系统商品/玩家商品，自行调用现有内部方法并返回 Markdown 消息或错误文本。
+  - `sell_item(user_id, chat_id, identifier, quantity)`，复用既有出售逻辑。
+  - 保留 `_handle_store` 与辅助方法供 `商店` 命令使用，未来如需扩展可新增 `WPSStoreViewCommand`（当前可继续由 `WPSStoreSystem` 注册 `商店` 命令）。
+- 更新 `callback` 流程：`WPSStoreSystem` 的 `callback` 只响应 `商店`，并在无参数时直接展示列表；其他指令由独立插件处理，因此不会出现未注册商品时落入帮助信息的问题。
+- 重新整理依赖关系与命令注册，确保未注册商品或物品未找到时返回明确错误提示（如“未找到商店商品”“背包未注册物品”）。
+- 暴露额外接口：`list_registered_modes()`、`get_store_snapshot()` 等辅助方法供其他插件调试或扩展使用。
+
+# 当前执行步骤："5. 重新规划命令拆分"
+
+实施清单：
+1. 重构 `WPSStoreSystem`：新增 `purchase_item`/`sell_item` 公共方法，并将 `callback` 限制为 `商店` 指令。
+2. 创建 `WPSStoreBuyCommand` 插件，注册 `购买`/`buy`，调用商店公共方法返回明确结果。
+3. 创建 `WPSStoreSellCommand` 插件，注册 `出售`/`sell`，调用商店公共方法返回明确结果。
+4. 更新依赖与注册流程，确保新插件在 `ImportPlugins` 中可被发现；补充帮助与错误信息。
+5. 运行 lint 并补记任务进度，为进入执行阶段做准备。
+
+# 任务进度
+2025-11-08_21:12:33
+- 已修改：`Plugins/WPSStoreSystem.py`
+- 更改：创建商店系统插件基础结构、数据库模型定义以及初始化清理逻辑
+- 原因：落实实施清单第1步，搭建插件骨架以支撑后续功能实现
+- 阻碍因素：无
+- 状态：未确认
+2025-11-08_21:13:08
+- 已修改：`Plugins/WPSStoreSystem.py`
+- 更改：实现商品模式注册/注销接口，维护常驻与候选模式及版本号
+- 原因：完成实施清单第2步，支持外部插件登记商店商品信息
+- 阻碍因素：无
+- 状态：未确认
+2025-11-08_21:14:01
+- 已修改：`Plugins/WPSStoreSystem.py`
+- 更改：实现整点懒加载刷新逻辑，含随机抽样、常驻商品同步与种子算法
+- 原因：落实实施清单第3步，确保商店列表稳定生成与自动过期重建
+- 阻碍因素：无
+- 状态：未确认
+2025-11-08_21:15:14
+- 已修改：`Plugins/WPSStoreSystem.py`
+- 更改：实现商店指令流程，生成系统/常驻/玩家商品列表及帮助信息
+- 原因：完成实施清单第4步，提供用户可见的商店展示
+- 阻碍因素：无
+- 状态：未确认
+2025-11-08_21:16:24
+- 已修改：`Plugins/WPSStoreSystem.py`
+- 更改：实现购买流程，校验积分与库存，并处理系统/玩家商品交易
+- 原因：落实实施清单第5步，支持积分扣除与背包发放
+- 阻碍因素：无
+- 状态：未确认
+2025-11-08_21:18:43
+- 已修改：`Plugins/WPSStoreSystem.py`
+- 更改：实现出售流程，包含背包校验、数量更新、撤单与售价生成逻辑
+- 原因：完成实施清单第6步，支持玩家自助上架或撤下物品
+- 阻碍因素：无
+- 状态：未确认
+2025-11-08_21:20:06
+- 已修改：`Plugins/WPSStoreSystem.py`
+- 更改：补充商店快照接口与通用数据转换，完善帮助信息与并发校验流程
+- 原因：完成实施清单第7步，为其他插件提供可复用查询能力
+- 阻碍因素：无
+- 状态：未确认
+2025-11-08_22:35:12
+- 已修改：`Plugins/WPSStoreSystem.py`
+- 更改：将 StoreMode / StoreEntry / PlayerListing 替换为 Pydantic BaseModel，并调整相关引用与导入
+- 原因：根据最新要求统一使用 BaseModel，保持不可变语义并通过 lint 检查
+- 阻碍因素：无
+- 状态：未确认
+2025-11-08_23:03:28
+- 已修改：`Plugins/WPSStoreSystem.py` `Plugins/WPSStoreBuyCommand.py` `Plugins/WPSStoreSellCommand.py`
+- 更改：抽离购买/出售命令至独立插件，提供公共接口 `purchase_item` / `sell_item` 并确保错误提示明确
+- 原因：满足命令拆分要求，避免未注册商品时误返回帮助信息
+- 阻碍因素：无
+- 状态：未确认
+
+# 最终审查
+(待补充)
+