From 69ed7610d9b85d062005b70a5fa2eddff7d90666 Mon Sep 17 00:00:00 2001
From: laogao <wadxf@live.com>
Date: Wed, 4 Nov 2026 12:16:34 +0800
Subject: [PATCH] =?UTF-8?q?fix(auth):=20=E9=AA=8C=E8=AF=81=E7=A0=81?=
 =?UTF-8?q?=E5=85=B3=E9=97=AD=E6=97=B6=20/captcha/get=20=E8=BF=94=E5=9B=9E?=
 =?UTF-8?q?=20enable=3Dfalse=20=E8=80=8C=E9=9D=9E=E6=8A=A5=E9=94=99?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 backend/app/modules/system/auth/schema.py  |  2 +-
 backend/app/modules/system/auth/service.py |  2 +-
 backend/tests/test_captcha_disabled.py     | 14 ++++++++++++++
 3 files changed, 16 insertions(+), 2 deletions(-)
 create mode 100644 backend/tests/test_captcha_disabled.py

diff --git a/backend/app/modules/system/auth/schema.py b/backend/app/modules/system/auth/schema.py
index 0866ad3f8..03ed5ca44 100644
--- a/backend/app/modules/system/auth/schema.py
+++ b/backend/app/modules/system/auth/schema.py
@@ -11,7 +11,7 @@ class CaptchaOutSchema(BaseModel):
     model_config = ConfigDict(from_attributes=True)
 
     enable: bool = Field(default=True, description="是否启用验证码")
-    key: str = Field(..., min_length=1, description="验证码唯一标识")
+    key: str = Field(default="", description="验证码唯一标识（未启用验证码时为空字符串）")
     img_base: str = Field(default="", description="拼图背景图（data URI）")
     piece_base: str = Field(default="", description="拼图图块（data URI，透明底）")
     piece_y: int = Field(default=0, description="图块在背景中的 Y 偏移")
diff --git a/backend/app/modules/system/auth/service.py b/backend/app/modules/system/auth/service.py
index d351acf93..4046d2abf 100644
--- a/backend/app/modules/system/auth/service.py
+++ b/backend/app/modules/system/auth/service.py
@@ -611,7 +611,7 @@ def _matches(state: dict, request: Request) -> bool:
     async def get_captcha(redis: Redis, request: Request) -> CaptchaOutSchema:
         """获取拼图验证码：服务端出题，缺口横坐标只保存在 Redis。"""
         if not settings.CAPTCHA_ENABLE:
-            raise CustomException(msg="未开启验证码服务")
+            return CaptchaOutSchema(enable=False)
 
         captcha_key = get_random_character()
         puzzle = build_puzzle(captcha_key)
diff --git a/backend/tests/test_captcha_disabled.py b/backend/tests/test_captcha_disabled.py
new file mode 100644
index 000000000..8ca4c4f03
--- /dev/null
+++ b/backend/tests/test_captcha_disabled.py
@@ -0,0 +1,14 @@
+"""验证码关闭时 /captcha/get 的行为 —— 返回 enable=false 而不是报错。"""
+
+from fastapi.testclient import TestClient
+
+
+def test_get_captcha_when_disabled_returns_enable_false(test_client: TestClient) -> None:
+    response = test_client.get("/system/auth/captcha/get")
+
+    assert response.status_code == 200, response.text
+    body = response.json()
+    assert body["success"] is True
+    data = body["data"]
+    assert data["enable"] is False
+    assert data["key"] == ""