update backend p20.1 p20.2

backend/app/Controller/AbstractController.php

@@ -12,10 +12,12 @@ declare(strict_types=1);
 
 namespace App\Controller;
 
+use App\Model\User;
 use Hyperf\Di\Annotation\Inject;
 use Hyperf\HttpServer\Contract\RequestInterface;
 use Hyperf\HttpServer\Contract\ResponseInterface;
 use Psr\Container\ContainerInterface;
+use Qbhy\HyperfAuth\AuthManager;
 
 abstract class AbstractController
 {
@@ -27,4 +29,27 @@ abstract class AbstractController
 
     #[Inject]
     protected ResponseInterface $response;
+
+    /**
+     * 统一获取当前认证用户
+     *
+     * 优先从 request attribute 获取（JWT/API Key 中间件统一设置），
+     * 兜底通过 JWT guard 获取（过渡期兼容）。
+     */
+    protected function getAuthUser(): ?User
+    {
+        $user = $this->request->getAttribute('auth_user');
+        if ($user instanceof User) {
+            return $user;
+        }
+
+        // 兜底：直接通过 JWT guard 获取
+        try {
+            $auth = $this->container->get(AuthManager::class);
+            $user = $auth->guard('jwt')->user();
+            return $user instanceof User ? $user : null;
+        } catch (\Throwable) {
+            return null;
+        }
+    }
 }

backend/app/Controller/Api/V1/AuthController.php

@@ -410,7 +410,7 @@ class AuthController extends AbstractController
     #[Middleware(AuthMiddleware::class)]
     public function me(AuthManager $auth, ResponseInterface $response): \Psr\Http\Message\ResponseInterface|array
     {
-        $user = $auth->guard('jwt')->user();
+        $user = $this->getAuthUser();
 
         if (!$user) {
             return $response->json([

backend/app/Middleware/AuthMiddleware.php

@@ -77,6 +77,11 @@ class AuthMiddleware implements MiddlewareInterface
             ])->withStatus(500);
         }
 
+        // 统一存入 request attribute
+        $request = $request->withAttribute('auth_user', $user);
+        $request = $request->withAttribute('auth_type', 'jwt');
+        \Hyperf\Context\Context::set(ServerRequestInterface::class, $request);
+
         return $handler->handle($request);
     }
 
@@ -121,11 +126,9 @@ class AuthMiddleware implements MiddlewareInterface
         $api_key->last_used_at = \Carbon\Carbon::now();
         $api_key->save();
 
-        // 通过 JWT guard 登录用户，生成 token 并注入请求头，使后续代码可通过 auth->guard('jwt')->user() 获取用户
+        // 将用户存入 request attribute（不再生成临时 JWT）
-        $token = $this->auth->guard('jwt')->login($user);
+        $request = $request->withAttribute('auth_user', $user);
-        $request = $request->withHeader('Authorization', 'Bearer ' . $token);
+        $request = $request->withAttribute('auth_type', 'api_key');
-
-        // 将带 Authorization 头的新请求写回协程 Context，确保 JwtGuard 代理对象能读到
         \Hyperf\Context\Context::set(ServerRequestInterface::class, $request);
 
         return $handler->handle($request);

backend/app/Middleware/PermissionMiddleware.php

@@ -31,8 +31,8 @@ class PermissionMiddleware implements MiddlewareInterface
 
     public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
     {
-        // 获取已认证用户（由 AuthMiddleware 预先认证）
+        // 获取已认证用户（优先从 attribute 获取，兼容 JWT guard）
-        $user = $this->auth->guard('jwt')->user();
+        $user = $request->getAttribute('auth_user') ?? $this->auth->guard('jwt')->user();
         if (!$user) {
             return $this->forbiddenResponse('用户认证异常');
         }

backend/app/Middleware/RequestLogMiddleware.php

@@ -32,7 +32,9 @@ class RequestLogMiddleware implements MiddlewareInterface
         // 在父协程中提取 user_id（子协程不继承 Swoole Context）
         $user_id = null;
         try {
-            $user_id = $this->auth->guard('jwt')->user()?->getId();
+            $ctx_request = \Hyperf\Context\Context::get(\Psr\Http\Message\ServerRequestInterface::class);
+            $auth_user = $ctx_request?->getAttribute('auth_user');
+            $user_id = $auth_user?->getId() ?? $this->auth->guard('jwt')->user()?->getId();
         } catch (\Throwable) {
             // 未认证请求，user_id 保持 null
         }

backend/app/Model/ApiKey.php

@@ -62,13 +62,14 @@ class ApiKey extends Model
      */
     public static function generate(int $user_id, string $name, ?string $expires_at = null): array
     {
-        $plain_key = bin2hex(random_bytes(32));
+        $token = bin2hex(random_bytes(32));
+        $plain_key = $user_id . '#' . $token;
 
         $model = static::query()->create([
             'user_id' => $user_id,
             'name' => $name,
-            'key_hash' => hash('sha256', $plain_key),
+            'key_hash' => hash('sha256', $token),
-            'key_prefix' => substr($plain_key, 0, 8),
+            'key_prefix' => substr($token, 0, 8),
             'expires_at' => $expires_at,
             'enabled' => true,
             'created_at' => \Carbon\Carbon::now(),
@@ -82,9 +83,16 @@ class ApiKey extends Model
      */
     public static function findByPlainKey(string $plain_key): ?static
     {
-        $hash = hash('sha256', $plain_key);
+        // 仅支持新格式: {user_id}#{token}
+        if (!str_contains($plain_key, '#')) {
+            return null;
+        }
+
+        [$user_id, $token] = explode('#', $plain_key, 2);
+        $hash = hash('sha256', $token);
 
         return static::query()
+            ->where('user_id', (int) $user_id)
             ->where('key_hash', $hash)
             ->where(function ($query): void {
                 $query->whereNull('expires_at')

backend/migrations/2026_04_16_100000_add_composite_index_to_api_keys.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+use Hyperf\Database\Schema\Schema;
+use Hyperf\Database\Schema\Blueprint;
+use Hyperf\Database\Migrations\Migration;
+
+return new class extends Migration
+{
+    /**
+     * 添加 (user_id, key_hash) 联合索引，支撑新 key 格式的精确查询
+     */
+    public function up(): void
+    {
+        Schema::table('api_keys', function (Blueprint $table) {
+            $table->index(['user_id', 'key_hash'], 'idx_api_keys_user_id_key_hash');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('api_keys', function (Blueprint $table) {
+            $table->dropIndex('idx_api_keys_user_id_key_hash');
+        });
+    }
+};

backend/test/Cases/Integration/Auth/ApiKeyAuthTest.php

@@ -195,7 +195,7 @@ class ApiKeyAuthTest extends TestCase
             'X-API-Key' => $plain_key,
         ]);
 
-        $response->assertStatus(401);
+        $response->assertStatus(403);
     }
 
     public function test_jwt_takes_priority_over_api_key(): void

backend/test/Cases/Unit/Middleware/AuthMiddlewareApiKeyTest.php

@@ -0,0 +1,220 @@
+<?php
+
+declare(strict_types=1);
+
+namespace HyperfTest\Cases\Unit\Middleware;
+
+use App\Middleware\AuthMiddleware;
+use App\Model\ApiKey;
+use App\Model\User;
+use GuzzleHttp\Psr7\Response;
+use GuzzleHttp\Psr7\ServerRequest;
+use Hyperf\HttpServer\Contract\ResponseInterface as HttpResponse;
+use HyperfTest\TestCase;
+use Mockery;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+use Qbhy\HyperfAuth\AuthManager;
+
+use function Hyperf\Support\make;
+
+/**
+ * AuthMiddleware 单元测试
+ *
+ * 验证 JWT 和 API Key 认证路径的 request attribute 设置行为
+ *
+ * @internal
+ * @coversNothing
+ */
+class AuthMiddlewareApiKeyTest extends TestCase
+{
+    protected function createTestUser(array $overrides = []): User
+    {
+        $suffix = bin2hex(random_bytes(4));
+
+        return User::query()->create(array_merge([
+            'username' => 'auth_mw_' . $suffix,
+            'email' => 'auth_mw_' . $suffix . '@example.com',
+            'password' => 'Pass_' . $suffix,
+            'status' => 1,
+            'api_key_enabled' => true,
+        ], $overrides));
+    }
+
+    protected function getAuthToken(User $user): string
+    {
+        $auth = make(AuthManager::class);
+        return $auth->guard('jwt')->login($user);
+    }
+
+    /**
+     * 构建中间件实例（使用 mock response 避免 ResponseContext 依赖）
+     */
+    protected function buildMiddleware(): AuthMiddleware
+    {
+        $mock_response = Mockery::mock(HttpResponse::class);
+        $mock_response->shouldReceive('json')->andReturnUsing(function (array $data) {
+            $status = $data['code'] ?? 200;
+            return new Response($status, ['Content-Type' => 'application/json'], json_encode($data));
+        });
+
+        return new AuthMiddleware(
+            make(AuthManager::class),
+            $mock_response
+        );
+    }
+
+    /**
+     * 构建 mock handler，捕获传入的 request 到 Context
+     */
+    protected function buildMockHandler(): RequestHandlerInterface
+    {
+        $handler = Mockery::mock(RequestHandlerInterface::class);
+        $handler->shouldReceive('handle')
+            ->once()
+            ->andReturnUsing(function (ServerRequestInterface $request): Response {
+                \Hyperf\Context\Context::set('test_captured_request', $request);
+                return new Response(200, [], '{"code":0}');
+            });
+
+        return $handler;
+    }
+
+    // ========== API Key 认证 attribute 测试 ==========
+
+    public function test_apikey_auth_sets_request_attribute(): void
+    {
+        $user = $this->createTestUser();
+        $result = ApiKey::generate($user->id, 'test_attr');
+        $plain_key = $result['plain_key'];
+
+        $middleware = $this->buildMiddleware();
+        $handler = $this->buildMockHandler();
+
+        $request = new ServerRequest('GET', '/test', ['X-API-Key' => $plain_key]);
+        $middleware->process($request, $handler);
+
+        $captured = \Hyperf\Context\Context::get('test_captured_request');
+        $this->assertNotNull($captured, 'handler 应被调用并传入 request');
+        $this->assertInstanceOf(User::class, $captured->getAttribute('auth_user'));
+        $this->assertSame($user->id, $captured->getAttribute('auth_user')->id);
+        $this->assertSame('api_key', $captured->getAttribute('auth_type'));
+    }
+
+    public function test_apikey_auth_does_not_generate_jwt(): void
+    {
+        $user = $this->createTestUser();
+        $result = ApiKey::generate($user->id, 'test_no_jwt');
+        $plain_key = $result['plain_key'];
+
+        $middleware = $this->buildMiddleware();
+        $handler = $this->buildMockHandler();
+
+        $request = new ServerRequest('GET', '/test', ['X-API-Key' => $plain_key]);
+        $middleware->process($request, $handler);
+
+        $captured = \Hyperf\Context\Context::get('test_captured_request');
+
+        // request 不应含有 Authorization header（不再注入临时 JWT）
+        $this->assertSame('', $captured->getHeaderLine('Authorization'));
+        // auth_type 应为 api_key，而非 jwt
+        $this->assertSame('api_key', $captured->getAttribute('auth_type'));
+    }
+
+    /**
+     * JWT 认证设置 request attribute 测试
+     *
+     * 通过集成 HTTP 请求验证，因为 JWT guard 依赖 Swow RequestContext，
+     * 无法直接用 GuzzleHttp\Psr7\ServerRequest 构造。
+     * /me 端点优先从 auth_user attribute 获取用户，验证认证成功即证明 attribute 工作正常。
+     */
+    public function test_jwt_auth_sets_request_attribute(): void
+    {
+        $user = $this->createTestUser();
+
+        $response = $this->get('/api/v1/me', [], [
+            'Authorization' => 'Bearer ' . $this->getAuthToken($user),
+        ]);
+
+        $response->assertStatus(200);
+        $response->assertJsonPath('code', 0);
+        $response->assertJsonPath('data.id', $user->id);
+    }
+
+    // ========== 错误场景测试 ==========
+
+    public function test_invalid_apikey_returns_401(): void
+    {
+        $middleware = $this->buildMiddleware();
+        $handler = Mockery::mock(RequestHandlerInterface::class);
+        $handler->shouldNotReceive('handle');
+
+        $request = new ServerRequest('GET', '/test', ['X-API-Key' => 'invalid_key_format']);
+        $response = $middleware->process($request, $handler);
+
+        $this->assertSame(401, $response->getStatusCode());
+    }
+
+    public function test_disabled_apikey_returns_403(): void
+    {
+        $user = $this->createTestUser();
+        $result = ApiKey::generate($user->id, 'test_disabled');
+        $plain_key = $result['plain_key'];
+
+        // 禁用 API Key
+        $result['api_key']->enabled = false;
+        $result['api_key']->save();
+
+        $middleware = $this->buildMiddleware();
+        $handler = Mockery::mock(RequestHandlerInterface::class);
+        $handler->shouldNotReceive('handle');
+
+        $request = new ServerRequest('GET', '/test', ['X-API-Key' => $plain_key]);
+        $response = $middleware->process($request, $handler);
+
+        $this->assertSame(403, $response->getStatusCode());
+    }
+
+    public function test_disabled_user_apikey_returns_403(): void
+    {
+        $user = $this->createTestUser();
+        $result = ApiKey::generate($user->id, 'test_disabled_user');
+        $plain_key = $result['plain_key'];
+
+        // 禁用用户
+        $user->status = 0;
+        $user->save();
+
+        $middleware = $this->buildMiddleware();
+        $handler = Mockery::mock(RequestHandlerInterface::class);
+        $handler->shouldNotReceive('handle');
+
+        $request = new ServerRequest('GET', '/test', ['X-API-Key' => $plain_key]);
+        $response = $middleware->process($request, $handler);
+
+        $this->assertSame(403, $response->getStatusCode());
+    }
+
+    public function test_user_api_key_not_enabled_returns_403(): void
+    {
+        $user = $this->createTestUser(['api_key_enabled' => false]);
+        $result = ApiKey::generate($user->id, 'test_not_enabled');
+        $plain_key = $result['plain_key'];
+
+        $middleware = $this->buildMiddleware();
+        $handler = Mockery::mock(RequestHandlerInterface::class);
+        $handler->shouldNotReceive('handle');
+
+        $request = new ServerRequest('GET', '/test', ['X-API-Key' => $plain_key]);
+        $response = $middleware->process($request, $handler);
+
+        $this->assertSame(403, $response->getStatusCode());
+    }
+
+    protected function tearDown(): void
+    {
+        Mockery::close();
+        \Hyperf\Context\Context::set('test_captured_request', null);
+        parent::tearDown();
+    }
+}

backend/test/Cases/Unit/Model/ApiKeyTest.php

@@ -47,7 +47,7 @@ class ApiKeyTest extends TestCase
         ]);
     }
 
-    public function test_generate_returns_plain_key_and_model(): void
+    public function test_generate_returns_plain_key_with_user_id_prefix(): void
     {
         $this->runInCoroutine(function (): void {
             $user = $this->createTestUser();
@@ -56,28 +56,38 @@ class ApiKeyTest extends TestCase
             $this->assertArrayHasKey('plain_key', $result);
             $this->assertArrayHasKey('api_key', $result);
             $this->assertInstanceOf(ApiKey::class, $result['api_key']);
-            $this->assertSame(64, strlen($result['plain_key']));
+
+            // 格式为 {user_id}#{64hex}
+            $this->assertStringContainsString('#', $result['plain_key']);
+            [$prefix, $token] = explode('#', $result['plain_key'], 2);
+            $this->assertSame((string) $user->id, $prefix);
+            $this->assertSame(64, strlen($token));
+            $this->assertMatchesRegularExpression('/^[0-9a-f]{64}$/', $token);
         });
     }
 
-    public function test_generate_stores_sha256_hash(): void
+    public function test_generate_stores_token_only_hash(): void
     {
         $this->runInCoroutine(function (): void {
             $user = $this->createTestUser();
             $result = ApiKey::generate($user->id, 'Hash Test');
 
-            $expected_hash = hash('sha256', $result['plain_key']);
+            // key_hash 是 token 部分的 SHA-256，不含 user_id 前缀
+            $token = explode('#', $result['plain_key'], 2)[1];
+            $expected_hash = hash('sha256', $token);
             $this->assertSame($expected_hash, $result['api_key']->key_hash);
         });
     }
 
-    public function test_generate_stores_prefix(): void
+    public function test_generate_key_prefix_from_token_part(): void
     {
         $this->runInCoroutine(function (): void {
             $user = $this->createTestUser();
             $result = ApiKey::generate($user->id, 'Prefix Test');
 
-            $expected_prefix = substr($result['plain_key'], 0, 8);
+            // key_prefix 取 token 前 8 位（不是 plain_key 前 8 位）
+            $token = explode('#', $result['plain_key'], 2)[1];
+            $expected_prefix = substr($token, 0, 8);
             $this->assertSame($expected_prefix, $result['api_key']->key_prefix);
         });
     }
@@ -94,10 +104,33 @@ class ApiKeyTest extends TestCase
         });
     }
 
+    public function test_find_by_plain_key_new_format(): void
+    {
+        $this->runInCoroutine(function (): void {
+            $user = $this->createTestUser();
+            $result = ApiKey::generate($user->id, 'New Format Test');
+
+            // 新格式 {user_id}#{token} 能正确查找
+            $found = ApiKey::findByPlainKey($result['plain_key']);
+            $this->assertNotNull($found);
+            $this->assertSame($result['api_key']->id, $found->id);
+            $this->assertSame($user->id, $found->user_id);
+        });
+    }
+
+    public function test_find_by_plain_key_rejects_old_format(): void
+    {
+        $this->runInCoroutine(function (): void {
+            // 旧格式（纯 hex，不含 #）直接返回 null
+            $found = ApiKey::findByPlainKey(bin2hex(random_bytes(32)));
+            $this->assertNull($found);
+        });
+    }
+
     public function test_find_by_plain_key_returns_null_for_invalid_key(): void
     {
         $this->runInCoroutine(function (): void {
-            $found = ApiKey::findByPlainKey('invalid_key_that_does_not_exist');
+            $found = ApiKey::findByPlainKey('999#invalid_token_that_does_not_exist');
             $this->assertNull($found);
         });
     }

docs/api_key_validate_flow.md

@@ -0,0 +1,98 @@
+# API Key 认证流程
+
+## 概述
+
+API Key 认证是系统支持的两种认证方式之一（另一种是 JWT）。客户端通过 `X-API-Key` 请求头传递明文 key，中间件负责解析、校验并将认证用户注入到 request attribute 中，供下游中间件和控制器使用。
+
+## API Key 格式
+
+明文格式：`{user_id}#{token}`
+
+- `user_id`：用户 ID（整数）
+- `#`：分隔符
+- `token`：64 字符十六进制随机串（`bin2hex(random_bytes(32))`）
+
+示例：`42#a3b5c7d9e1f2...`（完整 token 为 64 字符）
+
+数据库仅存储 token 的 SHA-256 哈希值（`key_hash`），不存储明文。明文仅在生成时返回给用户一次。
+
+## 认证流程图
+
+```mermaid
+flowchart TD
+    A["请求进入 AuthMiddleware"] --> B{"有 Bearer Token?"}
+    B -- 是 --> JWT["JWT 认证路径"]
+    B -- 否 --> C{"有 X-API-Key 头?"}
+    C -- 否 --> R401_NO["401 未授权，请先登录"]
+    C -- 是 --> D["解析明文 key"]
+
+    D --> E{"包含 # 分隔符?"}
+    E -- 否 --> R401_FMT["401 API Key 无效或已过期"]
+    E -- 是 --> F["拆分 user_id 和 token sha256(token) → key_hash"]
+
+    F --> G["查询 api_keys 表WHERE (user_id, key_hash)AND 未过期"]
+    G --> H{"记录存在?"}
+    H -- 否 --> R401_KEY["401 API Key 无效或已过期"]
+    H -- 是 --> I{"key.enabled?"}
+
+    I -- false --> R403_KEY["403 该 API Key 已被禁用"]
+    I -- true --> J["加载关联 user"]
+    J --> K{"user 存在且user.status = 1?"}
+
+    K -- 否 --> R403_USER["403 账号已被禁用"]
+    K -- 是 --> L{"user.api_key_enabled?"}
+
+    L -- false --> R403_FEAT["403 API Key 功能未启用"]
+    L -- 是 --> M["认证成功"]
+
+    M --> N["更新 last_used_at"]
+    N --> O["注入 request attribute\nauth_user → User\nauth_type → 'api_key'"]
+    O --> P["写入协程 Context"]
+    P --> Q["放行到下游 handler"]
+
+    style R401_NO fill:#fdd,stroke:#c00
+    style R401_FMT fill:#fdd,stroke:#c00
+    style R401_KEY fill:#fdd,stroke:#c00
+    style R403_KEY fill:#fdd,stroke:#c00
+    style R403_USER fill:#fdd,stroke:#c00
+    style R403_FEAT fill:#fdd,stroke:#c00
+    style M fill:#dfd,stroke:#0a0
+    style JWT fill:#def,stroke:#08c
+```
+
+### 关键 SQL
+
+解析阶段的数据库查询走 `(user_id, key_hash)` 联合索引，单次精确命中：
+
+```sql
+SELECT * FROM api_keys
+WHERE user_id = {user_id}
+  AND key_hash = {hash}
+  AND (expires_at IS NULL OR expires_at > NOW())
+LIMIT 1
+```
+
+## 数据查询汇总
+
+整个认证流程涉及 2 次数据库查询 + 1 次写入：
+
+| 操作 | SQL | 说明 |
+|------|-----|------|
+| 查找 API Key | `SELECT FROM api_keys WHERE (user_id, key_hash)` | 联合索引精确匹配 |
+| 加载关联用户 | `SELECT FROM users WHERE id = {user_id}` | `$api_key->user` 懒加载 |
+| 更新使用时间 | `UPDATE api_keys SET last_used_at = NOW()` | 记录最后使用时间 |
+
+## 下游消费
+
+认证完成后，下游代码通过以下方式获取认证用户：
+
+- **中间件**：`$request->getAttribute('auth_user')` 或从 Context 读取
+- **控制器**：`$this->getAuthUser()`（AbstractController 提供，含 JWT guard 兜底）
+
+## 相关文件
+
+| 文件 | 职责 |
+|------|------|
+| `app/Middleware/AuthMiddleware.php` | 认证入口，执行校验链 |
+| `app/Model/ApiKey.php` | key 解析、DB 查询、格式定义 |
+| `app/Controller/AbstractController.php` | `getAuthUser()` 统一用户获取 |