feat: 更新 .env.example 文件，新增彩票业务配置与 Redis、邮件、队列等环境变量，优化开发环境设置

2026-05-08 17:26:01 +08:00
parent 8cce1778b9
commit 85e57782cc
12 changed files with 663 additions and 54 deletions
--- a/app/Services/LotterySettings.php
+++ b/app/Services/LotterySettings.php
@@ -0,0 +1,94 @@
+<?php
+
+namespace App\Services;
+
+use App\Models\LotterySetting;
+use Illuminate\Support\Facades\Cache;
+
+/**
+ * 【配置中心】统一读入口：按 key 取运行期配置，默认带缓存。
+ *
+ * - 写入：控制台 / Seeder / 后续管理端可调 {@see put()}；
+ * - 【重要】库里不存在的 key **不写入缓存**，避免长期命中默认值导致后台新增配置不生效。
+ */
+final class LotterySettings
+{
+    public static function cacheTtlSeconds(): int
+    {
+        return max(5, (int) config('lottery.settings.cache_ttl_seconds', 60));
+    }
+
+    /** 取单个配置；若无行则返回 $default（不写缓存）。 */
+    public static function get(string $key, mixed $default = null): mixed
+    {
+        $cacheKey = self::cacheKey($key);
+        if (Cache::has($cacheKey)) {
+            return Cache::get($cacheKey);
+        }
+
+        /** @var LotterySetting|null $row */
+        $row = LotterySetting::query()->where('setting_key', $key)->first();
+        if ($row === null) {
+            return $default;
+        }
+
+        $value = self::normalizeValue($row->value_json);
+        Cache::put($cacheKey, $value, self::cacheTtlSeconds());
+
+        return $value;
+    }
+
+    /**
+     * 批量读取（逐项走 get；已存在的键会受益于缓存）。
+     *
+     * @param  array<string, mixed>  $keysToDefault  key => default
+     * @return array<string, mixed>
+     */
+    public static function many(array $keysToDefault): array
+    {
+        $out = [];
+        foreach ($keysToDefault as $key => $def) {
+            $out[$key] = self::get($key, $def);
+        }
+
+        return $out;
+    }
+
+    /** 删单 key 缓存；写入 lottery_settings 后务必调用（或运维 `php artisan cache:clear`） */
+    public static function forgetKey(string $key): void
+    {
+        Cache::forget(self::cacheKey($key));
+    }
+
+    /**
+     * 写入或更新一行配置并刷新该 key 的缓存。（Seeder / 后续管理端共用）
+     */
+    public static function put(
+        string $key,
+        mixed $value,
+        string $groupName = 'general',
+        ?string $descriptionZh = null,
+    ): void {
+        LotterySetting::query()->updateOrCreate(
+            ['setting_key' => $key],
+            [
+                'value_json' => $value,
+                'group_name' => $groupName,
+                'description_zh' => $descriptionZh,
+            ],
+        );
+        self::forgetKey($key);
+        // 写入后立即预热缓存，下一次 get 可走 Cache::has
+        Cache::put(self::cacheKey($key), self::normalizeValue($value), self::cacheTtlSeconds());
+    }
+
+    public static function cacheKey(string $key): string
+    {
+        return 'lottery_settings:'.$key;
+    }
+
+    private static function normalizeValue(mixed $value): mixed
+    {
+        return $value;
+    }
+}