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

server/src/app/api/v1/endpoints/audit_logs.py

@@ -13,13 +13,30 @@ router = APIRouter(prefix="/audit-logs")
 DbSession = Annotated[Session, Depends(get_db)]
 
 
-@router.get("", response_model=list[AuditLogRead])
+@router.get(
+    "",
+    response_model=list[AuditLogRead],
+    summary="查询审计日志",
+    description="按资源类型、资源 ID、动作类型和数量限制筛选审计日志。",
+)
 def list_audit_logs(
     db: DbSession,
-    resource_type: str | None = Query(default=None),
-    resource_id: str | None = Query(default=None),
-    action: str | None = Query(default=None),
-    limit: int = Query(default=50, ge=1, le=200),
+    resource_type: Annotated[
+        str | None,
+        Query(description="资源类型筛选，例如 `rule`、`task`。"),
+    ] = None,
+    resource_id: Annotated[
+        str | None,
+        Query(description="资源主键或业务编码筛选。"),
+    ] = None,
+    action: Annotated[
+        str | None,
+        Query(description="动作名称筛选。"),
+    ] = None,
+    limit: Annotated[
+        int,
+        Query(ge=1, le=200, description="返回日志上限。"),
+    ] = 50,
 ) -> list[AuditLogRead]:
     return AuditLogService(db).list_logs(
         resource_type=resource_type,