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

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

@@ -16,10 +16,19 @@ from app.schemas.agent_asset import (
     AgentAssetVersionCreate,
     AgentAssetVersionRead,
 )
+from app.schemas.common import ErrorResponse
 from app.services.agent_assets import AgentAssetService
 
 router = APIRouter(prefix="/agent-assets")
 DbSession = Annotated[Session, Depends(get_db)]
+ActorHeader = Annotated[
+    str | None,
+    Header(description="审计操作者。未传时回退到请求体中的 owner / reviewer 或 `system`。"),
+]
+RequestIdHeader = Annotated[
+    str | None,
+    Header(description="外部请求 ID，用于串联审计日志和上游调用链。"),
+]
 
 
 def _handle_asset_error(exc: Exception) -> None:
@@ -32,13 +41,30 @@ def _handle_asset_error(exc: Exception) -> None:
     raise exc
 
 
-@router.get("", response_model=list[AgentAssetListItem])
+@router.get(
+    "",
+    response_model=list[AgentAssetListItem],
+    summary="查询 Agent 资产列表",
+    description="按资产类型、状态、领域和关键字筛选规则、技能、MCP 与任务资产。",
+)
 def list_agent_assets(
     db: DbSession,
-    asset_type: str | None = Query(default=None),
-    status_value: str | None = Query(default=None, alias="status"),
-    domain: str | None = Query(default=None),
-    keyword: str | None = Query(default=None),
+    asset_type: Annotated[
+        str | None,
+        Query(description="资产类型：`rule`、`skill`、`mcp`、`task`。"),
+    ] = None,
+    status_value: Annotated[
+        str | None,
+        Query(alias="status", description="资产状态筛选。"),
+    ] = None,
+    domain: Annotated[
+        str | None,
+        Query(description="业务领域筛选，例如 `expense`、`ar`、`ap`。"),
+    ] = None,
+    keyword: Annotated[
+        str | None,
+        Query(description="资产编码、名称关键字模糊查询。"),
+    ] = None,
 ) -> list[AgentAssetListItem]:
     return AgentAssetService(db).list_assets(
         asset_type=asset_type,
@@ -48,7 +74,18 @@ def list_agent_assets(
     )
 
 
-@router.get("/{asset_id}", response_model=AgentAssetRead)
+@router.get(
+    "/{asset_id}",
+    response_model=AgentAssetRead,
+    summary="读取 Agent 资产详情",
+    description="返回资产当前版本正文、最近版本列表和最近一次审核信息。",
+    responses={
+        status.HTTP_404_NOT_FOUND: {
+            "model": ErrorResponse,
+            "description": "资产不存在。",
+        }
+    },
+)
 def get_agent_asset(asset_id: str, db: DbSession) -> AgentAssetRead:
     asset = AgentAssetService(db).get_asset(asset_id)
     if asset is None:
@@ -56,12 +93,24 @@ def get_agent_asset(asset_id: str, db: DbSession) -> AgentAssetRead:
     return asset
 
 
-@router.post("", response_model=AgentAssetRead, status_code=status.HTTP_201_CREATED)
+@router.post(
+    "",
+    response_model=AgentAssetRead,
+    status_code=status.HTTP_201_CREATED,
+    summary="创建 Agent 资产",
+    description="创建新的规则、技能、MCP 或任务资产，并自动记录审计日志。",
+    responses={
+        status.HTTP_400_BAD_REQUEST: {
+            "model": ErrorResponse,
+            "description": "资产编码冲突或请求字段不合法。",
+        }
+    },
+)
 def create_agent_asset(
     payload: AgentAssetCreate,
     db: DbSession,
-    x_actor: Annotated[str | None, Header()] = None,
-    x_request_id: Annotated[str | None, Header()] = None,
+    x_actor: ActorHeader = None,
+    x_request_id: RequestIdHeader = None,
 ) -> AgentAssetRead:
     try:
         return AgentAssetService(db).create_asset(
@@ -73,13 +122,28 @@ def create_agent_asset(
         _handle_asset_error(exc)
 
 
-@router.patch("/{asset_id}", response_model=AgentAssetRead)
+@router.patch(
+    "/{asset_id}",
+    response_model=AgentAssetRead,
+    summary="更新 Agent 资产",
+    description="更新资产基础信息、当前版本、状态和配置，并写入审计日志。",
+    responses={
+        status.HTTP_400_BAD_REQUEST: {
+            "model": ErrorResponse,
+            "description": "状态更新非法或请求字段不合法。",
+        },
+        status.HTTP_404_NOT_FOUND: {
+            "model": ErrorResponse,
+            "description": "资产或指定版本不存在。",
+        },
+    },
+)
 def update_agent_asset(
     asset_id: str,
     payload: AgentAssetUpdate,
     db: DbSession,
-    x_actor: Annotated[str | None, Header()] = None,
-    x_request_id: Annotated[str | None, Header()] = None,
+    x_actor: ActorHeader = None,
+    x_request_id: RequestIdHeader = None,
 ) -> AgentAssetRead:
     try:
         return AgentAssetService(db).update_asset(
@@ -92,9 +156,25 @@ def update_agent_asset(
         _handle_asset_error(exc)
 
 
-@router.get("/{asset_id}/versions", response_model=list[AgentAssetVersionRead])
+@router.get(
+    "/{asset_id}/versions",
+    response_model=list[AgentAssetVersionRead],
+    summary="查询资产版本列表",
+    description="返回指定资产的版本历史，默认按最近版本优先排序。",
+    responses={
+        status.HTTP_404_NOT_FOUND: {
+            "model": ErrorResponse,
+            "description": "资产不存在。",
+        }
+    },
+)
 def list_agent_asset_versions(
-    asset_id: str, db: DbSession, limit: int = Query(default=20, ge=1, le=100)
+    asset_id: str,
+    db: DbSession,
+    limit: Annotated[
+        int,
+        Query(ge=1, le=100, description="返回版本数量上限。"),
+    ] = 20,
 ) -> list[AgentAssetVersionRead]:
     try:
         return AgentAssetService(db).list_versions(asset_id, limit=limit)
@@ -106,13 +186,25 @@ def list_agent_asset_versions(
     "/{asset_id}/versions",
     response_model=AgentAssetVersionRead,
     status_code=status.HTTP_201_CREATED,
+    summary="创建资产版本",
+    description="为指定资产创建新版本；规则使用 Markdown，其他资产使用 JSON 快照。",
+    responses={
+        status.HTTP_400_BAD_REQUEST: {
+            "model": ErrorResponse,
+            "description": "版本号重复或内容类型不匹配。",
+        },
+        status.HTTP_404_NOT_FOUND: {
+            "model": ErrorResponse,
+            "description": "资产不存在。",
+        },
+    },
 )
 def create_agent_asset_version(
     asset_id: str,
     payload: AgentAssetVersionCreate,
     db: DbSession,
-    x_actor: Annotated[str | None, Header()] = None,
-    x_request_id: Annotated[str | None, Header()] = None,
+    x_actor: ActorHeader = None,
+    x_request_id: RequestIdHeader = None,
 ) -> AgentAssetVersionRead:
     try:
         return AgentAssetService(db).create_version(
@@ -126,14 +218,28 @@ def create_agent_asset_version(
 
 
 @router.post(
-    "/{asset_id}/reviews", response_model=AgentAssetReviewRead, status_code=status.HTTP_201_CREATED
+    "/{asset_id}/reviews",
+    response_model=AgentAssetReviewRead,
+    status_code=status.HTTP_201_CREATED,
+    summary="创建资产审核记录",
+    description="为指定资产版本写入审核结果，并联动更新资产状态。",
+    responses={
+        status.HTTP_400_BAD_REQUEST: {
+            "model": ErrorResponse,
+            "description": "审核参数不合法。",
+        },
+        status.HTTP_404_NOT_FOUND: {
+            "model": ErrorResponse,
+            "description": "资产或版本不存在。",
+        },
+    },
 )
 def create_agent_asset_review(
     asset_id: str,
     payload: AgentAssetReviewCreate,
     db: DbSession,
-    x_actor: Annotated[str | None, Header()] = None,
-    x_request_id: Annotated[str | None, Header()] = None,
+    x_actor: ActorHeader = None,
+    x_request_id: RequestIdHeader = None,
 ) -> AgentAssetReviewRead:
     try:
         return AgentAssetService(db).create_review(
@@ -146,12 +252,27 @@ def create_agent_asset_review(
         _handle_asset_error(exc)
 
 
-@router.post("/{asset_id}/activate", response_model=AgentAssetRead)
+@router.post(
+    "/{asset_id}/activate",
+    response_model=AgentAssetRead,
+    summary="激活资产当前版本",
+    description="将资产当前版本切换为上线状态；规则资产必须已有 `approved` 审核记录。",
+    responses={
+        status.HTTP_400_BAD_REQUEST: {
+            "model": ErrorResponse,
+            "description": "审核未通过或当前版本未设置。",
+        },
+        status.HTTP_404_NOT_FOUND: {
+            "model": ErrorResponse,
+            "description": "资产不存在。",
+        },
+    },
+)
 def activate_agent_asset(
     asset_id: str,
     db: DbSession,
-    x_actor: Annotated[str | None, Header()] = None,
-    x_request_id: Annotated[str | None, Header()] = None,
+    x_actor: ActorHeader = None,
+    x_request_id: RequestIdHeader = None,
 ) -> AgentAssetRead:
     try:
         return AgentAssetService(db).activate_asset(