feat(api): 添加 graphrag 权限规则和优化知识图谱缓存失效

- 在权限规则匹配器中添加 /api/graphrag/** 的读写权限控制
- 修改图关系服务中的删除操作以精确失效相关实体缓存
- 更新图同步服务确保 BELONGS_TO 关系在增量同步时正确重建
- 重构图同步步骤服务中的组织归属关系构建逻辑
- 修复前端图_canvas 组件中的元素点击事件处理逻辑
- 实现 Python GraphRAG 缓存的启用/禁用功能
- 为 GraphRAG 缓存统计和清除接口添加调用方日志记录

runtime/datamate-python/app/module/kg_graphrag/cache.py

@@ -49,6 +49,24 @@ class CacheStats:
         }
 
 
+class _DisabledCache:
+    """缓存禁用时的 no-op 缓存实现。"""
+
+    maxsize = 0
+
+    def get(self, key: str) -> None:
+        return None
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        return None
+
+    def __len__(self) -> int:
+        return 0
+
+    def clear(self) -> None:
+        return None
+
+
 class GraphRAGCache:
     """GraphRAG 检索结果缓存。
 
@@ -63,19 +81,27 @@ class GraphRAGCache:
         embedding_maxsize: int = 512,
         embedding_ttl: int = 600,
     ) -> None:
-        self._kg_cache: TTLCache = TTLCache(maxsize=kg_maxsize, ttl=kg_ttl)
-        self._embedding_cache: TTLCache = TTLCache(maxsize=embedding_maxsize, ttl=embedding_ttl)
+        self._kg_cache: TTLCache | _DisabledCache = self._create_cache(kg_maxsize, kg_ttl)
+        self._embedding_cache: TTLCache | _DisabledCache = self._create_cache(
+            embedding_maxsize, embedding_ttl
+        )
         self._kg_lock = threading.Lock()
         self._embedding_lock = threading.Lock()
         self._kg_stats = CacheStats()
         self._embedding_stats = CacheStats()
 
+    @staticmethod
+    def _create_cache(maxsize: int, ttl: int) -> TTLCache | _DisabledCache:
+        if maxsize <= 0:
+            return _DisabledCache()
+        return TTLCache(maxsize=maxsize, ttl=max(1, ttl))
+
     @classmethod
     def from_settings(cls) -> GraphRAGCache:
         from app.core.config import settings
 
         if not settings.graphrag_cache_enabled:
-            # 返回一个 maxsize=0 的缓存，所有 get 都会 miss，set 都是 no-op
+            # 返回禁用缓存实例：不缓存数据，避免 maxsize=0 初始化异常
             return cls(kg_maxsize=0, kg_ttl=1, embedding_maxsize=0, embedding_ttl=1)
 
         return cls(

runtime/datamate-python/app/module/kg_graphrag/interface.py

@@ -260,9 +260,10 @@ async def query_stream(
     summary="缓存统计",
     description="返回 GraphRAG 检索缓存的命中率和容量统计。",
 )
-async def cache_stats():
+async def cache_stats(caller: Annotated[str, Depends(_require_caller_id)]):
     from app.module.kg_graphrag.cache import get_cache
 
+    logger.info("GraphRAG cache stats requested by caller=%s", caller)
     return StandardResponse(code=200, message="success", data=get_cache().stats())
 
 
@@ -272,8 +273,9 @@ async def cache_stats():
     summary="清空缓存",
     description="清空所有 GraphRAG 检索缓存。",
 )
-async def cache_clear():
+async def cache_clear(caller: Annotated[str, Depends(_require_caller_id)]):
     from app.module.kg_graphrag.cache import get_cache
 
+    logger.info("GraphRAG cache clear requested by caller=%s", caller)
     get_cache().clear()
     return StandardResponse(code=200, message="success", data={"cleared": True})