feat: 完善后端 API OpenAPI 文档与统一错误响应 schema

server/src/app/api/deps.py

@@ -24,12 +24,24 @@ class CurrentUserContext:
     is_admin: bool
 
 
-def get_current_user(
-    x_auth_username: Annotated[str | None, Header()] = None,
-    x_auth_name: Annotated[str | None, Header()] = None,
-    x_auth_role_codes: Annotated[str | None, Header()] = None,
-    x_auth_is_admin: Annotated[str | None, Header()] = None,
-) -> CurrentUserContext:
+def get_current_user(
+    x_auth_username: Annotated[
+        str | None,
+        Header(description="当前登录用户名。知识库接口至少需要提供用户名或姓名。"),
+    ] = None,
+    x_auth_name: Annotated[
+        str | None,
+        Header(description="当前登录人展示姓名。未传时默认回退到用户名。"),
+    ] = None,
+    x_auth_role_codes: Annotated[
+        str | None,
+        Header(description="角色编码列表，多个角色使用英文逗号分隔，例如 `manager,finance`。"),
+    ] = None,
+    x_auth_is_admin: Annotated[
+        str | None,
+        Header(description="是否管理员，支持 `true/false/1/0`。"),
+    ] = None,
+) -> CurrentUserContext:
     role_codes = [item.strip() for item in (x_auth_role_codes or "").split(",") if item.strip()]
     is_admin = str(x_auth_is_admin or "").strip().lower() in {"1", "true", "yes", "on"}