火山引擎SMS API|celery容灾优化|生成模型引擎积分列表API

video-gen-api/app/api/v1/sms.py

@@ -4,27 +4,45 @@ from app.config import settings
 from app.schemas.sms import SmsSendRequest, SmsVerifyRequest, SmsResponse
 from app.services.sms import generate_and_send_sms, verify_sms_code
 
-router = APIRouter(prefix="/sms", tags=["sms"])
+router = APIRouter(prefix="/sms", tags=["短信验证码"])
 
 
-@router.post("/send", response_model=SmsResponse)
+def _validate_captcha_token(captcha_token: str | None) -> None:
+    if settings.SMS_MOCK:
+        return
+    if not (req_captcha := captcha_token):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="需要验证码",
+        )
+
+    from app.services.auth import decode_access_token
+
+    token_sub = decode_access_token(req_captcha)
+    if not token_sub or not token_sub.startswith("captcha:"):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="验证码无效",
+        )
+
+
+@router.post(
+    "/send",
+    response_model=SmsResponse,
+    summary="发送短信验证码",
+    description="客户端发送短信验证码。scene=register 用于注册，scene=login 用于短信登录，scene=set_password 用于设置密码。正式环境会按配置校验图形验证码。",
+)
 async def send_sms_code(req: SmsSendRequest):
-    """Send SMS verification code. Requires captcha_token in production."""
-    if not settings.SMS_MOCK:
-        if not req.captcha_token:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail="需要验证码",
-            )
-        from app.services.auth import decode_access_token
-        token_sub = decode_access_token(req.captcha_token)
-        if not token_sub or not token_sub.startswith("captcha:"):
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail="验证码无效",
-            )
+    _validate_captcha_token(req.captcha_token)
+
+    try:
+        ok = await generate_and_send_sms(req.phone, req.scene.value)
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(exc),
+        ) from exc
 
-    ok = await generate_and_send_sms(req.phone)
     if not ok:
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
@@ -33,10 +51,14 @@ async def send_sms_code(req: SmsSendRequest):
     return SmsResponse(message="验证码已发送", success=True)
 
 
-@router.post("/verify", response_model=SmsResponse)
+@router.post(
+    "/verify",
+    response_model=SmsResponse,
+    summary="校验短信验证码",
+    description="校验指定手机号、场景下的短信验证码。业务接口一般会内部校验，本接口主要用于前端调试或单独校验。",
+)
 async def verify_sms(req: SmsVerifyRequest):
-    """Verify SMS code."""
-    ok = await verify_sms_code(req.phone, req.code)
+    ok = await verify_sms_code(req.phone, req.code, req.scene.value)
     if not ok:
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,