feat: 实现密码重置功能与用户搜索API，优化注册登录流程

- 新增忘记密码页面与重置密码确认流程（前端+后端）
- 修复注册验证码页登录跳转路由
- 新增用户搜索API（按邮箱查询）
- 简化infra脚本，统一为app.sh
- 补充密码重置与用户API测试覆盖
- 更新runtime文档与AGENTS配置

backend/src/v1/auth/gateway.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+from collections.abc import Mapping
 from typing import Any, cast
 
 from fastapi import HTTPException
@@ -10,6 +11,8 @@ from core.config.settings import SupabaseSettings, config
 from core.logging import get_logger
 from v1.auth.schemas import (
     AuthUser,
+    PasswordResetConfirmRequest,
+    PasswordResetRequest,
     SessionCreateRequest,
     SessionRefreshRequest,
     SessionResponse,
@@ -150,6 +153,64 @@ class SupabaseAuthGateway(AuthServiceGateway):
             ),
         )
 
+    async def request_password_reset(self, request: PasswordResetRequest) -> None:
+        try:
+            reset_email = cast(Any, self._client.auth.reset_password_email)
+            email = _coerce_reset_email(request.email)
+            if request.redirect_to:
+                options: dict[str, str] = {"redirect_to": request.redirect_to}
+                await asyncio.to_thread(reset_email, email, options=options)
+            else:
+                await asyncio.to_thread(reset_email, email)
+        except AuthError as exc:
+            logger.warning(
+                "Password reset request failed",
+                error_type=type(exc).__name__,
+            )
+
+    async def confirm_password_reset(
+        self, request: PasswordResetConfirmRequest
+    ) -> None:
+        verify_payload: dict[str, Any] = {
+            "type": "recovery",
+            "email": request.email,
+            "token": request.token,
+        }
+        try:
+            verify_otp = cast(Any, self._client.auth.verify_otp)
+            response = await asyncio.to_thread(verify_otp, verify_payload)
+            session = getattr(response, "session", None)
+            user = getattr(response, "user", None)
+            user_id = str(getattr(user, "id", "")) if user is not None else ""
+            if session is None or not user_id:
+                raise HTTPException(
+                    status_code=401, detail="Invalid or expired verification code"
+                )
+            await asyncio.to_thread(
+                self._admin_client.auth.admin.update_user_by_id,
+                user_id,
+                {"password": request.new_password},
+            )
+        except AuthError as exc:
+            logger.warning(
+                "Password reset confirm failed", error_type=type(exc).__name__
+            )
+            raise HTTPException(
+                status_code=401, detail="Invalid or expired verification code"
+            ) from exc
+
+
+def _coerce_reset_email(value: object) -> str:
+    if isinstance(value, str):
+        return value
+
+    if isinstance(value, Mapping):
+        nested = value.get("email") or value.get("value")
+        if isinstance(nested, str):
+            return nested
+
+    raise HTTPException(status_code=422, detail="Invalid email")
+
 
 def _map_auth_response(response: object, failure_message: str) -> SessionResponse:
     session = getattr(response, "session", None)

backend/src/v1/auth/router.py

@@ -10,6 +10,8 @@ from v1.auth.rate_limit import enforce_rate_limit
 from v1.auth.dependencies import get_auth_service
 from v1.users.dependencies import get_current_user
 from v1.auth.schemas import (
+    PasswordResetConfirmRequest,
+    PasswordResetRequest,
     SessionCreateRequest,
     SessionDeleteRequest,
     SessionRefreshRequest,
@@ -123,3 +125,33 @@ async def get_user_by_email(
     if current_user.role != "service_role" and current_user.email != email:
         raise HTTPException(status_code=403, detail="Forbidden")
     return await service.get_user_by_email(email)
+
+
+@router.post("/password-reset", status_code=204)
+async def request_password_reset(
+    payload: PasswordResetRequest,
+    service: AuthService = Depends(get_auth_service),
+) -> Response:
+    await enforce_rate_limit(
+        scope="password_reset_request",
+        identifier=payload.email,
+        limit=5,
+        window_seconds=60,
+    )
+    await service.request_password_reset(payload)
+    return Response(status_code=204)
+
+
+@router.post("/password-reset/confirm", status_code=204)
+async def confirm_password_reset(
+    payload: PasswordResetConfirmRequest,
+    service: AuthService = Depends(get_auth_service),
+) -> Response:
+    await enforce_rate_limit(
+        scope="password_reset_confirm",
+        identifier=payload.email,
+        limit=10,
+        window_seconds=600,
+    )
+    await service.confirm_password_reset(payload)
+    return Response(status_code=204)

backend/src/v1/auth/schemas.py

@@ -61,5 +61,11 @@ class PasswordResetRequest(BaseModel):
     redirect_to: str | None = None
 
 
+class PasswordResetConfirmRequest(BaseModel):
+    email: EmailStr
+    token: str = Field(pattern=r"^\d{6}$")
+    new_password: str = Field(min_length=6)
+
+
 class PasswordResetResponse(BaseModel):
     message: str = "Password reset email sent"

backend/src/v1/auth/service.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 from typing import Protocol
 
 from v1.auth.schemas import (
+    PasswordResetConfirmRequest,
+    PasswordResetRequest,
     SessionCreateRequest,
     SessionRefreshRequest,
     SessionResponse,
@@ -40,6 +42,14 @@ class AuthServiceGateway(Protocol):
     async def get_user_by_email(self, email: str) -> UserByEmailResponse:
         raise NotImplementedError
 
+    async def request_password_reset(self, request: PasswordResetRequest) -> None:
+        raise NotImplementedError
+
+    async def confirm_password_reset(
+        self, request: PasswordResetConfirmRequest
+    ) -> None:
+        raise NotImplementedError
+
 
 class AuthService:
     _gateway: AuthServiceGateway
@@ -71,3 +81,11 @@ class AuthService:
 
     async def get_user_by_email(self, email: str) -> UserByEmailResponse:
         return await self._gateway.get_user_by_email(email)
+
+    async def request_password_reset(self, request: PasswordResetRequest) -> None:
+        await self._gateway.request_password_reset(request)
+
+    async def confirm_password_reset(
+        self, request: PasswordResetConfirmRequest
+    ) -> None:
+        await self._gateway.confirm_password_reset(request)