From 92e382a3154766a43e7c45fccd50bcff6a8cf2fb Mon Sep 17 00:00:00 2001
From: Nick Zeng <Nick.Zeng@wpic.co>
Date: Mon, 9 Mar 2026 10:12:12 +0800
Subject: [PATCH] add api key table

---
 backend/app/Model/ApiKey.php | 110 +++++++++++++++++++++++++++++++++++
 1 file changed, 110 insertions(+)
 create mode 100644 backend/app/Model/ApiKey.php

diff --git a/backend/app/Model/ApiKey.php b/backend/app/Model/ApiKey.php
new file mode 100644
index 0000000..8a55a7b
--- /dev/null
+++ b/backend/app/Model/ApiKey.php
@@ -0,0 +1,110 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Model;
+
+use Hyperf\Database\Model\Relations\BelongsTo;
+use Hyperf\DbConnection\Model\Model;
+
+/**
+ * @property int $id
+ * @property int $user_id
+ * @property string $name
+ * @property string $key_hash
+ * @property string $key_prefix
+ * @property \Carbon\Carbon $last_used_at
+ * @property \Carbon\Carbon $expires_at
+ * @property bool $enabled
+ * @property \Carbon\Carbon $created_at
+ */
+class ApiKey extends Model
+{
+    protected ?string $table = 'api_keys';
+
+    public bool $timestamps = false;
+
+    protected array $fillable = [
+        'user_id',
+        'name',
+        'key_hash',
+        'key_prefix',
+        'last_used_at',
+        'expires_at',
+        'enabled',
+    ];
+
+    protected array $hidden = [
+        'key_hash',
+    ];
+
+    protected array $casts = [
+        'id' => 'integer',
+        'user_id' => 'integer',
+        'enabled' => 'boolean',
+        'last_used_at' => 'datetime',
+        'expires_at' => 'datetime',
+        'created_at' => 'datetime',
+    ];
+
+    /**
+     * 所属用户
+     */
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'user_id');
+    }
+
+    /**
+     * 生成新 API Key，返回模型和明文
+     *
+     * 明文仅在生成时可见，后续无法再次获取
+     */
+    public static function generate(int $user_id, string $name, ?string $expires_at = null): array
+    {
+        $plain_key = bin2hex(random_bytes(32));
+
+        $model = static::query()->create([
+            'user_id' => $user_id,
+            'name' => $name,
+            'key_hash' => hash('sha256', $plain_key),
+            'key_prefix' => substr($plain_key, 0, 8),
+            'expires_at' => $expires_at,
+        ]);
+
+        return ['api_key' => $model, 'plain_key' => $plain_key];
+    }
+
+    /**
+     * 通过明文 key 查找有效的 ApiKey 记录
+     */
+    public static function findByPlainKey(string $plain_key): ?static
+    {
+        $hash = hash('sha256', $plain_key);
+
+        return static::query()
+            ->where('key_hash', $hash)
+            ->where('enabled', true)
+            ->where(function ($query): void {
+                $query->whereNull('expires_at')
+                    ->orWhere('expires_at', '>', \Carbon\Carbon::now());
+            })
+            ->first();
+    }
+
+    /**
+     * 检查 API Key 是否有效（未过期且启用）
+     */
+    public function isValid(): bool
+    {
+        if (!$this->enabled) {
+            return false;
+        }
+
+        if ($this->expires_at !== null && $this->expires_at->isPast()) {
+            return false;
+        }
+
+        return true;
+    }
+}