docs(models): 模型字段行尾注释迁移为 Field(description)，补全 OpenAPI 字段说明

app/shared/api.py

@@ -16,7 +16,7 @@ from typing import Any, Generic, TypeVar
 from fastapi import Depends, FastAPI, Request
 from fastapi.exceptions import RequestValidationError
 from fastapi.responses import JSONResponse
-from pydantic import BaseModel, ValidationError
+from pydantic import BaseModel, Field, ValidationError
 from starlette.exceptions import HTTPException as StarletteHTTPException
 
 from app.shared.errors import AppError, AuthenticationError
@@ -29,10 +29,13 @@ T = TypeVar("T")
 class ApiResponse(BaseModel, Generic[T]):
     """统一 API 响应格式"""
 
-    success: bool
-    msg: str
-    data: T | None = None
-    code: int
+    success: bool = Field(description="请求是否成功")
+    msg: str = Field(description="提示信息；失败时为错误原因")
+    data: T | None = Field(default=None, description="响应数据；无数据或失败时为 null")
+    code: int = Field(
+        description="错误码：0 表示成功，其余见统一错误码表（如 1001 鉴权失败、"
+        "1002 请求参数校验失败、5xxx 交易服务、6xxx 网关）"
+    )
 
 
 # ---- 依赖注入 ----