feat(#1718): PATCH /auth/me 资料更新接口 + profile_completed 字段 (#1728)

Co-authored-by: xiaoxia <dev@xiaoxiajianji.com>
Co-committed-by: xiaoxia <dev@xiaoxiajianji.com>

apps/api/app/api/routes/auth.py

@@ -1,4 +1,5 @@
 """
+from __future__ import annotations
 Canonical authentication API routes.
 
 The route layer is intentionally thin: repository construction lives in
@@ -15,7 +16,7 @@ from app.config import settings
 from app.dependencies import get_auth_email_service, get_auth_session_store, get_user_repository
 from fastapi import APIRouter, Depends, Header, HTTPException, Request, status
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
-from pydantic import BaseModel, EmailStr
+from pydantic import BaseModel, EmailStr, field_validator
 
 from packages.adapters.redis import NoopSessionStore
 from packages.adapters.smtp import NoopEmailService
@@ -85,6 +86,22 @@ class CurrentUserResponse(BaseModel):
     phone_verified: bool = False
     binding_complete: bool = False
     wechat_bound: bool = False
+    profile_completed: bool = True
+
+
+class UserProfileResponse(BaseModel):
+    """用户资料负载（PATCH /me、绑定/解绑接口复用；字段与 GET /auth/me 一致，前端 normalizeUser 直接消费）"""
+
+    user_id: str
+    email: str
+    username: str
+    display_name: str
+    email_verified: bool
+    phone: str = ""
+    phone_verified: bool = False
+    binding_complete: bool = False
+    wechat_bound: bool = False
+    profile_completed: bool = True
 
 
 class PasswordResetRequestModel(BaseModel):
@@ -274,9 +291,51 @@ async def get_current_user_info(
         phone_verified=user.phone_verified,
         binding_complete=binding_complete,
         wechat_bound=bool(user.wechat_openid),
+        profile_completed=user.profile_completed,
     )
 
 
+class UpdateProfileRequest(BaseModel):
+    """更新个人资料请求（当前仅支持昵称）"""
+
+    display_name: str
+
+    @field_validator("display_name")
+    @classmethod
+    def _validate_display_name(cls, v: str) -> str:
+        name = (v or "").strip()
+        if not name:
+            raise ValueError("昵称不能为空白")
+        if len(name) > 20:
+            raise ValueError("昵称长度需在 1-20 个字符之间")
+        return name
+
+
+class UpdateProfileResponse(BaseModel):
+    """更新资料响应：前端 normalizeUser(response.user) 直接消费"""
+
+    user: UserProfileResponse
+
+
+@router.patch("/me", response_model=UpdateProfileResponse)
+async def update_current_user_profile(
+    request: UpdateProfileRequest,
+    current_user: AuthenticatedUser = Depends(get_current_user),
+    user_repository: UserRepository = Depends(get_user_repository),
+) -> UpdateProfileResponse:
+    """更新当前登录用户昵称（微信新用户首次设置昵称后置 profile_completed=True）。"""
+    user = current_user.user
+    user.display_name = request.display_name  # 已 strip（validator）
+    if not user.profile_completed:
+        user.profile_completed = True
+    user_repository.save(user)
+
+    logger.info("[资料更新] 用户 %s 更新昵称，profile_completed=%s", user.id, user.profile_completed)
+    # 重新读取，确保返回的是持久化后的最新状态
+    fresh = user_repository.find_by_id(user.id) or user
+    return UpdateProfileResponse(user=_user_profile(fresh))
+
+
 class _NoopSessionStore(NoopSessionStore):
     pass
 
@@ -507,34 +566,20 @@ class WechatBindCompleteRequest(BaseModel):
     state: str = ""
 
 
-class WechatBindUserProfile(BaseModel):
-    """绑定/解绑后返回的用户信息（字段对齐 /auth/me，前端 normalizeUser 直接消费）"""
-
-    user_id: str
-    email: str
-    username: str
-    display_name: str
-    email_verified: bool
-    phone: str = ""
-    phone_verified: bool = False
-    binding_complete: bool = False
-    wechat_bound: bool = False
-
-
 class WechatBindCompleteResponse(BaseModel):
     success: bool
-    user: WechatBindUserProfile
+    user: UserProfileResponse
 
 
 class WechatUnbindResponse(BaseModel):
     success: bool
 
 
-def _wechat_user_profile(user) -> WechatBindUserProfile:
+def _user_profile(user) -> UserProfileResponse:
     binding_complete = bool(
         user.phone_verified and user.email_verified and user.email and "@wechat.local" not in user.email
     )
-    return WechatBindUserProfile(
+    return UserProfileResponse(
         user_id=user.id,
         email=user.email,
         username=user.username,
@@ -544,6 +589,7 @@ def _wechat_user_profile(user) -> WechatBindUserProfile:
         phone_verified=user.phone_verified,
         binding_complete=binding_complete,
         wechat_bound=bool(user.wechat_openid),
+        profile_completed=user.profile_completed,
     )
 
 
@@ -589,7 +635,7 @@ async def wechat_bind(
         raise HTTPException(status_code=http_status, detail=error)
 
     logger.info("[微信绑定] 用户 %s 绑定成功 openid=%s", current_user.user.id, wechat_user.openid[:8])
-    return WechatBindCompleteResponse(success=True, user=_wechat_user_profile(result.user))
+    return WechatBindCompleteResponse(success=True, user=_user_profile(result.user))
 
 
 @router.delete("/wechat/bind", response_model=WechatUnbindResponse)