优化座驾开发插件规范

plugins/chatroom-ride-development/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "chatroom-ride-development",
-  "version": "0.1.0",
-  "description": "聊天室座驾开发插件，沉淀新增座驾的代码位置、命名规则和测试清单。",
+  "version": "0.2.0",
+  "description": "聊天室座驾开发插件，沉淀独立座驾模块、金币流水、特效注册、命名规则和测试清单。",
   "interface": {
     "displayName": "Chatroom Ride Development"
   },

plugins/chatroom-ride-development/skills/chatroom-ride-development/SKILL.md

@@ -11,10 +11,12 @@ description: "开发 /Users/pllx/Web/Herd/chatroom 的聊天室座驾。适用
 - 新增 `resources/js/effects/<key>.js` 全屏座驾特效。
 - 调整座驾购买、续期、替换、入场欢迎语或后台价格/天数配置。
 - 排查座驾进房后特效不播放、欢迎语不显示、购买记录不正确的问题。
+- 排查座驾购买没有金币流水、后台座驾列表为空、前台座驾弹窗为空的问题。
 
 ## 必须遵守
 
-- 座驾必须使用独立 `rides` 和 `user_ride_purchases`，不要写入 `shop_items` 或 `user_purchases`。
+- 座驾是独立模块：必须使用 `rides` 和 `user_ride_purchases`，不要写入 `shop_items` 或 `user_purchases`。
+- 商店模块只管理普通商店商品；不要给 `ShopItem` 增加 `TYPE_RIDE`、`isRide()`、`rideKey()` 或座驾欢迎语字段。
 - 座驾 slug 固定为 `ride_<effect_key>`。
 - `<effect_key>` 必须同时出现在：
   - `rides.slug`
@@ -28,6 +30,18 @@ description: "开发 /Users/pllx/Web/Herd/chatroom 的聊天室座驾。适用
 - `welcome_message` 支持 `{name}` 和 `{ride}`，输出前必须转义，不能直接信任后台输入。
 - 当前版本只允许用户同时拥有一个 active 座驾；同款续购叠加有效期，不同款替换旧座驾并把旧记录置为 `cancelled`。
 - 用户购买记录必须写入 `user_ride_purchases`，不要复用商店购买记录。
+- 座驾购买扣金币必须走 `UserCurrencyService::deductGoldIfEnough()`，来源使用 `CurrencySource::RIDE_BUY`，并写入 `user_currency_logs`。
+- 座驾购买接口必须携带房间 ID，并把 `room_id` 传给金币流水，方便后台按房间追溯。
+- 测试中禁止使用 `Redis::flushall()` 清理聊天室状态；只允许清理 `room:*` 相关 key，避免把本机登录 session 一起删掉。
+
+## 模块边界
+
+- 前台接口：`GET /rides/items`、`POST /rides/buy`。
+- 后台入口：`GET /admin/rides`，页面文件为 `resources/views/admin/rides/index.blade.php`。
+- 前台弹窗脚本：`resources/js/chat-room/ride-controls.js`。
+- 业务服务：`app/Services/RideService.php`。
+- 数据模型：`app/Models/Ride.php`、`app/Models/UserRidePurchase.php`。
+- 请求验证：`BuyRideRequest`、`StoreRideRequest`、`UpdateRideRequest`。
 
 ## 新增座驾步骤
 
@@ -36,8 +50,26 @@ description: "开发 /Users/pllx/Web/Herd/chatroom 的聊天室座驾。适用
 3. 在 `effect-sounds.js` 注册音效启动分支。
 4. 在 `EffectBroadcast::TYPES` 加入 `<effect_key>`。
 5. 在迁移或 Seeder 中新增 `rides` 记录，slug 使用 `ride_<effect_key>`，`effect_key` 使用 `<effect_key>`。
-6. 若后台预览需要，把按钮加入管理菜单预览区。
-7. 更新座驾相关 PHPUnit 测试，至少覆盖列表、购买、续期、替换和进房触发。
+6. 确认后台 `座驾管理` 可以配置价格、使用天数、欢迎语、上下架状态和排序。
+7. 确认 `RideService::buy()` 购买时写入 `user_ride_purchases` 和 `user_currency_logs`。
+8. 更新座驾相关 PHPUnit 测试，至少覆盖列表、余额不足、购买成功、金币流水、续期、替换和进房触发。
+
+## 金币流水要求
+
+- 购买成功必须在 `user_currency_logs` 中写入：
+  - `currency = gold`
+  - `amount = -座驾价格`
+  - `source = ride_buy`
+  - `remark = 购买聊天室座驾：<座驾名称>`
+  - `room_id = 当前房间 ID`
+- 余额不足时不能写 `user_ride_purchases`，也不能写 `user_currency_logs`。
+- 不要用 `$user->decrement('jjb', ...)` 直接扣金币。
+
+## 旧方案清理要求
+
+- 不要恢复 `add_ride_fields_to_shop_items` 这类把座驾挂到商店表的迁移。
+- 允许保留清理迁移，用于删除旧环境中 `shop_items.slug like ride_%`、`shop_items.type = ride` 或 `shop_items.welcome_message` 残留。
+- 修改座驾模块后，检查 `rg 'TYPE_RIDE|ShopItem::rideKey|RideItemController|复用商店购买记录'`，确认没有旧方案引用。
 
 ## 验证清单
 
@@ -46,6 +78,7 @@ description: "开发 /Users/pllx/Web/Herd/chatroom 的聊天室座驾。适用
 - `node --check resources/js/effects/effect-sounds.js`
 - `php artisan test --compact tests/Feature/RideControllerTest.php`
 - 有进房逻辑变更时运行相关 `ChatControllerTest` 过滤用例。
+- 涉及商店边界时运行 `php artisan test --compact tests/Feature/ShopControllerTest.php`。
 - 修改 PHP 后运行 `vendor/bin/pint --dirty --format=agent`。
 
 ## 特别注意
@@ -53,3 +86,4 @@ description: "开发 /Users/pllx/Web/Herd/chatroom 的聊天室座驾。适用
 - 如果从 stash 恢复昨天的座驾特效，必须确认 untracked 父提交中的新特效文件也已恢复，不能只恢复已跟踪文件。
 - `99a` 这种以数字开头的 key 在 JS 对象字面量里必须加引号。
 - 新座驾的展示名可以是中文，但 effect key 必须保持小写短横线/数字/字母风格，避免前后端匹配失败。
+- 本项目 PHP 文件要求类和方法上方有中文 DocBlock；新增座驾相关 PHP 文件时必须补齐。