# 背景
文件名: 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()` 等辅助方法供其他插件调试或扩展使用。

# 当前执行步骤："10. 购买排序优化"

实施清单：
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` 并确保错误提示明确
- 原因：满足命令拆分要求，避免未注册商品时误返回帮助信息
- 阻碍因素：无
- 状态：未确认
2025-11-09_19:18:39
- 已修改：`Plugins/WPSStoreSystem.py`
- 更改：玩家出售与系统商品展示统一使用物品名称，扩展 `PlayerListing` 并在加载时补充物品名
- 原因：确保商店界面不再暴露物品ID，提升可读性
- 阻碍因素：无
- 状态：未确认
2025-11-09_19:35:08
- 已修改：`Plugins/WPSStoreSystem.py` `PWF/CoreModules/plugin_interface.py`
- 更改：出售指令支持 `<数量> <单价>` 参数，调整逻辑使用玩家自定 single price，并在表注册时自动补齐缺失列
- 原因：允许运营自定售价并避免旧表缺列导致的运行错误
- 阻碍因素：无
- 状态：成功
2025-11-09_19:45:00
- 已修改：`Plugins/WPSStoreSystem.py`
- 更改：购买流程统一收集匹配来源，按价格升序排序；同价时优先玩家，再按系统、常驻顺序处理
- 原因：满足按价格优先购买的需求，确保同价时玩家商品优先售出
- 阻碍因素：无
- 状态：进行中
2025-11-09_19:50:00
- 已修改：`Plugins/WPSAlchemyGame.py`
- 更改：炼金插件依赖商店系统，在注册炉灰物品后同步为整点刷新候选，单价 8 分、限购 999
- 原因：补充基础货源，便于验证按价格排序的购买流程
- 阻碍因素：无
- 状态：成功
2025-11-09_21:22:44
- 已修改：`Plugins/WPSStoreSystem.py`
- 更改：玩家出售展示改为调用配置接口获取昵称，避免暴露纯数字ID
- 原因：提升商店玩家出售区的可读性与一致性
- 阻碍因素：无
- 状态：未确认
2025-11-10_00:06:48
- 已修改：`Plugins/WPSStoreSystem.py`
- 更改：修正 `WPSConfigAPI.get_user_points` 参数传递，仅使用 `user_id`，避免购买流程报错。
- 原因：购买时出现 `get_user_points()` 参数数量不匹配异常。
- 阻碍因素：无
- 状态：未确认

# 最终审查
(待补充)