文档：在 DEVELOPMENT.md 补充积分流水系统完整开发者使用指南

DEVELOPMENT.md

@@ -201,6 +201,7 @@ npm run dev                        # Vite 热更新（开发阶段）
 | _(新增)_    | `create_ai_provider_configs_table` | `AiProviderConfig`  | AI 服务商配置（多厂商支持）        |
 | _(新增)_    | `create_ai_usage_logs_table`       | `AiUsageLog`        | AI 使用日志（Token 用量记录）      |
 | _(新增)_    | `create_username_blacklist_table`  | `UsernameBlacklist` | 用户名黑名单                       |
+| _(新增)_    | `create_user_currency_logs_table`  | `UserCurrencyLog`   | 积分流水（经验/金币/魅力变动记录） |
 
 ---
 
@@ -225,7 +226,8 @@ app/
 │   ├── UserLevelService.php        # 等级权限判断（替代 getLevel()）
 │   ├── AiChatService.php           # AI 聊天服务（多厂商适配：OpenAI/DeepSeek 等）
 │   ├── VipService.php              # VIP 开通/到期检查
-│   └── ShopService.php             # 商店购买 + 道具激活逻辑
+│   ├── ShopService.php             # 商店购买 + 道具激活逻辑
+│   └── UserCurrencyService.php     # ⭐ 积分统一操作服务（所有经验/金币/魅力变更必须经此）
 │
 ├── Http/
 │   ├── Controllers/
@@ -246,7 +248,8 @@ app/
 │   │       ├── RoomManagerController.php  # 房间大盘管理
 │   │       ├── AutoactController.php      # 随机事件管理
 │   │       ├── VipController.php          # VIP 等级 CRUD
-│   │       ├── AiProviderController.php   # AI 厂商配置管理
+│   │       ├── AiProviderController.php   # AI 厂商配置管理（含启用/禁用/设为默认）
+│   │       ├── CurrencyStatsController.php # ⭐ 积分流水活动统计（每日来源产出分析）
 │   │       └── SmtpController.php         # 邮件发信配置
 │   │
 │   ├── Middleware/
@@ -268,9 +271,13 @@ app/
 │   ├── RoomDescription.php ├── UserItem.php   ├── Gift.php
 │   ├── ShopItem.php      ├── UserPurchase.php  ├── VipLevel.php
 │   ├── AiProviderConfig.php ├── AiUsageLog.php ├── UsernameBlacklist.php
+│   ├── UserCurrencyLog.php # ⭐ 积分流水记录
 │   └── System/
 │       └── PlatformSmtpAccount.php
 │
+├── Enums/
+│   └── CurrencySource.php          # ⭐ 积分来源枚举（auto_save/fishing_gain/admin_adjust 等）
+│
 └── Jobs/
     └── SaveMessageJob.php          # 异步将消息持久化到 MySQL
 
@@ -434,6 +441,22 @@ routes/
 
 ---
 
+### ✅ 第十一阶段：积分流水审计系统
+
+- [x] `App\Enums\CurrencySource` — 所有来源枚举（可扩展）
+- [x] `App\Models\UserCurrencyLog` — 流水 Model（含查询 Scope）
+- [x] `App\Services\UserCurrencyService` — 统一积分变更服务（**所有经验/金币/魅力修改必须走此服务**）
+- [x] 接入 `AutoSaveExp`（auto_save 来源）
+- [x] 接入 `FishingController`（fishing_cost / fishing_gain 来源）
+- [x] 接入 `ChatController::init()` 新人礼包（newbie_bonus 来源）
+- [x] 接入 `Admin\UserManagerController`（admin_adjust 来源）
+- [x] `LeaderboardController::todayIndex()` — 今日风云榜独立页（`/leaderboard/today`）
+- [x] `LeaderboardController::myLogs()` — 用户个人流水日志（`/my/currency-logs`）
+- [x] `Admin\CurrencyStatsController` — 后台积分活动统计（`/admin/currency-stats`）
+- [x] 导航栏新增「📅 今日榜」按钮，后台侧边栏新增「📈 积分流水统计」入口
+
+---
+
 ### 🔲 待完善事项
 
 - [ ] **用户名黑名单管理**（后台 CRUD，`UsernameBlacklist` 模型已建，路由/界面待完成）
@@ -501,6 +524,118 @@ routes/
 
 ---
 
+### 7.8 积分流水系统 — 开发者使用指南 ⭐
+
+> [!IMPORTANT]
+> **铁律**：所有涉及修改用户 `exp_num`（经验）、`jjb`（金币）、`meili`（魅力）的操作，
+> **必须通过 `UserCurrencyService::change()` 执行**，禁止直接操作 `$user->increment()` 或 `User::update()`。
+
+#### 8.1 注入服务
+
+```php
+use App\Enums\CurrencySource;
+use App\Services\UserCurrencyService;
+
+public function __construct(
+    private readonly UserCurrencyService $currencyService,
+) {}
+```
+
+#### 8.2 单次变更
+
+```php
+// 给用户增加经验（正数=增加，负数=扣除）
+$this->currencyService->change(
+    user: $user,
+    currency: 'exp',           // 'exp' | 'gold' | 'charm'
+    amount: 10,                // 正数=增加，负数=消耗（不会低于0）
+    source: CurrencySource::AUTO_SAVE,  // 来源（必须用 Enum，不得写裸字符串）
+    remark: '挂机获得经验',    // 可选备注
+    roomId: 1,                 // 可选房间ID
+);
+
+// 扣金币（钓鱼消耗）
+$this->currencyService->change($user, 'gold', -5, CurrencySource::FISHING_COST, '抛竿消耗');
+```
+
+#### 8.3 批量变更（自动存点场景）
+
+```php
+// 对多个用户批量发放，内部逐条原子执行
+$this->currencyService->batchChange(
+    users: $onlineUsers,     // Collection<User>
+    currency: 'exp',
+    amount: 1,
+    source: CurrencySource::AUTO_SAVE,
+    remark: '定时存点',
+);
+```
+
+#### 8.4 添加新的积分来源（扩展 Enum）
+
+在 `App\Enums\CurrencySource` 枚举中新增一个常量即可，**无需修改数据库**：
+
+```php
+// app/Enums/CurrencySource.php
+enum CurrencySource: string
+{
+    case AUTO_SAVE      = 'auto_save';
+    case FISHING_COST   = 'fishing_cost';
+    case FISHING_GAIN   = 'fishing_gain';
+    case NEWBIE_BONUS   = 'newbie_bonus';
+    case ADMIN_ADJUST   = 'admin_adjust';
+    // ↓ 新增活动时在此追加一行即可
+    case DAILY_SIGN_IN  = 'daily_sign_in';   // 示例：每日签到
+
+    /** 返回可读名称（用于后台统计展示） */
+    public function label(): string
+    {
+        return match($this) {
+            self::AUTO_SAVE     => '⏰ 自动存点',
+            self::FISHING_COST  => '🎣 钓鱼消耗',
+            self::FISHING_GAIN  => '🐟 钓鱼收获',
+            self::NEWBIE_BONUS  => '🎁 新人礼包',
+            self::ADMIN_ADJUST  => '🛠️ 管理员调整',
+            self::DAILY_SIGN_IN => '📅 每日签到',  // 对应新增
+        };
+    }
+}
+```
+
+#### 8.5 流水查询 Scope
+
+```php
+use App\Models\UserCurrencyLog;
+
+// 查询某用户最近7天的经验记录
+$logs = UserCurrencyLog::where('user_id', $user->id)
+    ->currency('exp')
+    ->whereDate('created_at', '>=', now()->subDays(7))
+    ->orderByDesc('created_at')
+    ->get();
+
+// 今日金币排行（今日获得量前20名）
+$ranking = UserCurrencyLog::whereDate('created_at', today())
+    ->where('currency', 'gold')
+    ->where('amount', '>', 0)   // 只算增加，不算消耗
+    ->selectRaw('user_id, username, SUM(amount) as total')
+    ->groupBy('user_id', 'username')
+    ->orderByDesc('total')
+    ->limit(20)
+    ->get();
+```
+
+#### 8.6 相关页面路由速查
+
+| 页面         | 路由名                       | URI                                     |
+| ------------ | ---------------------------- | --------------------------------------- |
+| 个人积分日志 | `currency.my-logs`           | `/my/currency-logs?currency=exp&days=7` |
+| 今日风云榜   | `leaderboard.today`          | `/leaderboard/today`                    |
+| 累计风云榜   | `leaderboard.index`          | `/leaderboard`                          |
+| 后台积分统计 | `admin.currency-stats.index` | `/admin/currency-stats?date=2026-02-28` |
+
+---
+
 ## 八、常用命令速查
 
 ```bash