[Echo-Note]

问题

CAPTCHA_ENABLE=false（配置默认值）时，前端登录页调用 GET /api/v1/system/auth/captcha/get 拿到的是 400「未开启验证码服务」，前端只能落进 catch 分支。

但响应模型 CaptchaOutSchema 本来就有 enable 字段，就是用来表达「验证码是否启用」的；前端也是按 data.enable 决定要不要渲染滑块。功能关闭属于正常状态，不该是一个错误。

原因

两处叠加，导致「返回 enable=false」这条路根本走不通：

1. CaptchaService.get_captcha 在 CAPTCHA_ENABLE=false 时直接 raise CustomException，不走正常返回。
2. CaptchaOutSchema.key 是必填字段（min_length=1），即使想返回 enable=false 也构造不出合法响应（验证码关闭时按定义没有 key）。

改动

文件	改动
backend/app/modules/system/auth/service.py	关闭时返回 CaptchaOutSchema(enable=False)，不再抛错
backend/app/modules/system/auth/schema.py	key 改为默认空字符串，允许未启用时没有 key
backend/tests/test_captcha_disabled.py	新增回归测试：断言 HTTP 200、success=true、data.enable=false、data.key==""

if not settings.CAPTCHA_ENABLE:
    return CaptchaOutSchema(enable=False)

兼容性

• 启用验证码时行为完全不变：字段名、类型、取值都没动。
• 前端无需改动：现有前端已经按 data.enable 判断是否渲染拼图。
• 契约上是放宽（key 允许为空字符串），且只影响「验证码关闭」这一场景 —— 该场景在此前返回的是错误响应，没有正常消费方会依赖它。

验证

• 回归测试在修复前失败、修复后通过：

  # 修复前
  FAILED tests/test_captcha_disabled.py::test_get_captcha_when_disabled_returns_enable_false
  [自定义异常] GET /system/auth/captcha/get | code=-1 | status=400 | msg=未开启验证码服务
  
  # 修复后
  1 passed
  

• 相关用例未受影响：

  pytest tests/test_captcha_disabled.py tests/test_security_defaults.py \
         tests/test_error_code_single_source.py tests/test_main.py -q
  → 56 passed
  

• ruff check → All checks passed