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

server/src/app/schemas/common.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class ErrorResponse(BaseModel):
+    detail: str
+
+
+class RootStatusRead(BaseModel):
+    message: str
+
+
+class HealthDatabaseStatusRead(BaseModel):
+    configured: bool
+    ok: bool
+    error: str | None = None
+
+
+class HealthRedisStatusRead(BaseModel):
+    configured: bool
+    enabled: bool
+
+
+class HealthCheckRead(BaseModel):
+    status: str
+    database: HealthDatabaseStatusRead
+    redis: HealthRedisStatusRead

server/src/app/schemas/knowledge.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
-from typing import Any
-
-from pydantic import BaseModel, Field
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
 
 
 class KnowledgeFolderRead(BaseModel):
@@ -58,13 +58,21 @@ class KnowledgeOnlyOfficeConfigRead(BaseModel):
     config: dict[str, Any] = Field(default_factory=dict)
 
 
-class KnowledgeOnlyOfficeCallbackRead(BaseModel):
-    error: int = 0
-
-
-class KnowledgeLibraryRead(BaseModel):
-    folders: list[KnowledgeFolderRead] = Field(default_factory=list)
-    documents: list[KnowledgeDocumentRead] = Field(default_factory=list)
+class KnowledgeOnlyOfficeCallbackRead(BaseModel):
+    error: int = 0
+
+
+class KnowledgeOnlyOfficeCallbackWrite(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    status: int = Field(description="ONLYOFFICE 回调状态码。")
+    url: str | None = Field(default=None, description="文档下载地址，状态为 2 或 6 时使用。")
+    users: list[str] = Field(default_factory=list, description="当前编辑用户列表。")
+
+
+class KnowledgeLibraryRead(BaseModel):
+    folders: list[KnowledgeFolderRead] = Field(default_factory=list)
+    documents: list[KnowledgeDocumentRead] = Field(default_factory=list)
 
 
 class KnowledgeActionResponse(BaseModel):