fix(knowledge): classify assets and fail soft list readback

apps/api/src/models/knowledge.py

@@ -127,3 +127,8 @@ class KnowledgeListResponse(BaseModel):
     items: list[KnowledgeEntry]
     total: int
     categories: list[CategoryCount] = Field(default_factory=list)
+    readback_status: str = "ready"
+    operator_stage: str | None = None
+    next_step: str | None = None
+    writes_on_read: bool = False
+    manual_review_required: bool = False

apps/api/src/services/knowledge_service.py

@@ -40,6 +40,22 @@ logger = structlog.get_logger(__name__)
 _knowledge_service: "KnowledgeService | None" = None
 
 
+def build_knowledge_list_readback_degraded_response(reason: str) -> KnowledgeListResponse:
+    """主 KM readback 失敗時回保守 payload，避免前端誤判成知識庫歸零。"""
+    return KnowledgeListResponse(
+        items=[],
+        total=0,
+        categories=[],
+        readback_status="degraded",
+        operator_stage="knowledge_readback_degraded_ai_controlled_repair",
+        next_step=(
+            "queue_ai_controlled_km_readback_retry_tagging_and_connector_verifier"
+        ),
+        writes_on_read=False,
+        manual_review_required=False,
+    )
+
+
 def get_knowledge_service() -> "KnowledgeService":
     """取得 Knowledge Service 實例"""
     global _knowledge_service
@@ -140,24 +156,37 @@ class KnowledgeService:
         offset: int = 0,
     ) -> KnowledgeListResponse:
         """列出知識條目 + 分類統計"""
-        async with get_db_context() as db:
-            repo: IKnowledgeRepository = KnowledgeDBRepository(db)
-            items, total = await repo.list_entries(
+        try:
+            async with get_db_context() as db:
+                repo: IKnowledgeRepository = KnowledgeDBRepository(db)
+                items, total = await repo.list_entries(
+                    category=category,
+                    entry_type=entry_type,
+                    status=status,
+                    tags=tags,
+                    q=q,
+                    limit=limit,
+                    offset=offset,
+                )
+                categories_raw = await repo.get_categories()
+                categories = [
+                    CategoryCount(category=cat, count=cnt) for cat, cnt in categories_raw
+                ]
+                return KnowledgeListResponse(
+                    items=items, total=total, categories=categories
+                )
+        except Exception as exc:  # noqa: BLE001 - production readback must fail soft
+            logger.warning(
+                "knowledge_list_readback_degraded",
+                error=str(exc),
                 category=category,
-                entry_type=entry_type,
-                status=status,
-                tags=tags,
+                entry_type=entry_type.value if entry_type else None,
+                status=status.value if status else None,
                 q=q,
                 limit=limit,
                 offset=offset,
             )
-            categories_raw = await repo.get_categories()
-            categories = [
-                CategoryCount(category=cat, count=cnt) for cat, cnt in categories_raw
-            ]
-            return KnowledgeListResponse(
-                items=items, total=total, categories=categories
-            )
+            return build_knowledge_list_readback_degraded_response(str(exc))
 
     async def get_categories(self) -> list[CategoryCount]:
         """取得分類統計（直接呼叫 repo，不走 list_entries）"""