feat(force-onboarding): 运营一键开启新手引导 — User.force_onboarding + admin 接口 + /me 带出 + 走完自动清

- User 新增 force_onboarding 列(仿 debug_trace_enabled)+ 迁移 user_force_onboarding。
- POST /admin/api/users/{id}/force-onboarding(operator 角色 + 审计 user.force_onboarding.set)。
- UserOut(/me 与登录响应)带出该字段;/api/v1/user/onboarding/complete 走完即自动清回 false,只触发一次。
- 测试:admin 设置+审计+角色守卫、走完引导自动清标记。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

app/admin/routers/users.py

@@ -14,6 +14,7 @@ from app.admin.schemas.user import (
     AdminUserOverview,
     GrantCoinsRequest,
     SetDebugTraceRequest,
+    SetForceOnboardingRequest,
     SetUserStatusRequest,
 )
 from app.models.admin import AdminUser
@@ -100,6 +101,33 @@ def set_user_debug_trace(
     return OkResponse()
 
 
+@router.post("/{user_id}/force-onboarding", response_model=OkResponse, summary="一键开启/取消新手引导")
+def set_user_force_onboarding(
+    user_id: int,
+    body: SetForceOnboardingRequest,
+    request: Request,
+    admin: Annotated[AdminUser, Depends(require_role("operator"))],
+    db: AdminDb,
+) -> OkResponse:
+    """运营「一键开启新手引导」:置 user.force_onboarding。开启后该用户下次启动 App(/me 带出此字段)
+    会被强制重走引导教程——即便此前已看完;走完引导后端自动清回 false,不无限循环。
+    仅对支持 force_onboarding 的 App 版本生效(老版本忽略该字段)。"""
+    user = user_repo.get_user_by_id(db, user_id)
+    if user is None:
+        raise HTTPException(status_code=404, detail="用户不存在")
+    if user.status == "deleted":
+        raise HTTPException(status_code=400, detail="已注销账号不可操作")
+    before = user.force_onboarding
+    # 业务写 + 审计写同一事务(commit=False),最后一起 commit(同 set_user_status / debug-trace)
+    mutations.set_user_force_onboarding(db, user, enabled=body.enabled, commit=False)
+    write_audit(
+        db, admin, action="user.force_onboarding.set", target_type="user", target_id=user_id,
+        detail={"before": before, "after": body.enabled}, ip=get_client_ip(request), commit=False,
+    )
+    db.commit()
+    return OkResponse()
+
+
 @router.post("/{user_id}/coins", response_model=OkResponse, summary="手动增减金币(带审计)")
 def grant_user_coins(
     user_id: int,