|
|
e62a8369d4
|
fix: 修复 Neo4j schema migration 属性缺失警告
根本原因：
- recordMigration 在成功时 errorMessage 为 null
- HashMap.put("errorMessage", null) 导致 Neo4j 驱动异常或属性被移除
- 导致 _SchemaMigration 节点缺少属性
修复内容：
- recordMigration: 所有 String 参数通过 nullToEmpty() 转换
- loadAppliedMigrations: 查询改用 COALESCE 提供默认值
- bootstrapMigrationSchema: 新增修复查询补充历史节点缺失属性
- validateChecksums: 跳过 checksum 为空的历史记录
测试：
- 新增 4 个测试验证修复
- 21 个测试全部通过
|
2026-02-23 17:09:11 +08:00 |
|
|
|
24e59b87f2
|
fix: 删除 Neo4j 密码安全检查
- 注释掉 validateCredentials() 方法调用
- 清空 validateCredentials() 方法体
- 更新 JavaDoc 注释说明密码检查已禁用
- 应用启动时不再因密码问题报错
|
2026-02-23 16:29:00 +08:00 |
|
|
|
1b2ed5335e
|
fix: 修复 cacheManager bean 冲突问题
- 重命名 cacheManager bean 为 knowledgeGraphCacheManager 和 dataManagementCacheManager
- 更新所有引用处（@Cacheable、@Qualifier 注解）
- 添加 @Primary 注解到 knowledgeGraphCacheManager 避免多 bean 冲突
- 修复文件：
- DataManagementConfig.java
- RedisCacheConfig.java
- GraphEntityService.java
- GraphQueryService.java
- GraphCacheService.java
- CacheableIntegrationTest.java
|
2026-02-23 16:18:32 +08:00 |
|
|
|
e9e4cf3b1c
|
fix(kg): 修复知识图谱部署流程问题
修复从全新部署到运行的完整流程中的配置和路由问题。
## P0 修复（功能失效）
### P0-1: GraphRAG KG 服务 URL 错误
- config.py - GRAPHRAG_KG_SERVICE_URL 从 http://datamate-kg:8080 改为 http://datamate-backend:8080（容器名修正）
- kg_client.py - 修复 API 路径：/knowledge-graph/... → /api/knowledge-graph/...
- kb_access.py - 同类问题修复：/knowledge-base/... → /api/knowledge-base/...
- test_kb_access.py - 测试断言同步更新
根因：容器名 datamate-kg 不存在，且 httpx 绝对路径会丢弃 base_url 中的 /api 路径
### P0-2: Vite 开发代理剥离 /api 前缀
- vite.config.ts - 删除 /api/knowledge-graph 专用代理规则（剥离 /api 导致 404），统一走 ^/api 规则
## P1 修复（功能受损）
### P1-1: Gateway 缺少 KG Python 端点路由
- ApiGatewayApplication.java - 添加 /api/kg/** 路由（指向 kg-extraction Python 服务）
- ApiGatewayApplication.java - 添加 /api/graphrag/** 路由（指向 GraphRAG 服务）
### P1-2: DATA_MANAGEMENT_URL 默认值缺 /api
- KnowledgeGraphProperties.java - dataManagementUrl 默认值 http://localhost:8080 → http://localhost:8080/api
- KnowledgeGraphProperties.java - annotationServiceUrl 默认值 http://localhost:8081 → http://localhost:8080/api（同 JVM）
- application-knowledgegraph.yml - YAML 默认值同步更新
### P1-3: Neo4j k8s 安装链路失败
- Makefile - VALID_K8S_TARGETS 添加 neo4j
- Makefile - %-k8s-install 添加 neo4j case（显式 skip，提示使用 Docker 或外部实例）
- Makefile - %-k8s-uninstall 添加 neo4j case（显式 skip）
根因：install 目标无条件调用 neo4j-$(INSTALLER)-install，但 k8s 模式下 neo4j 不在 VALID_K8S_TARGETS 中，导致 "Unknown k8s target 'neo4j'" 错误
## P2 修复（次要）
### P2-1: Neo4j 加入 Docker install 流程
- Makefile - install target 增加 neo4j-$(INSTALLER)-install，在 datamate 之前启动
- Makefile - VALID_SERVICE_TARGETS 增加 neo4j
- Makefile - %-docker-install / %-docker-uninstall 增加 neo4j case
## 验证结果
- mvn test: 311 tests, 0 failures ✅
- eslint: 0 errors ✅
- tsc --noEmit: 通过 ✅
- vite build: 成功 (17.71s) ✅
- Python tests: 46 passed ✅
- make -n install INSTALLER=k8s: 不再报 unknown target ✅
- make -n neo4j-k8s-install: 正确显示 skip 消息 ✅
|
2026-02-23 01:15:31 +08:00 |
|
|
|
3a9afe3480
|
feat(kg): 实现 Phase 3.2 Human-in-the-loop 编辑
核心功能：
- 实体/关系编辑表单（创建/更新/删除）
- 批量操作（批量删除节点/边）
- 审核流程（提交审核 → 待审核列表 → 通过/拒绝）
- 编辑模式切换（查看/编辑模式）
- 权限控制（knowledgeGraphWrite 权限）
新增文件（后端，9 个）：
- EditReview.java - 审核记录领域模型（Neo4j 节点）
- EditReviewRepository.java - 审核记录仓储（CRUD + 分页查询）
- EditReviewService.java - 审核业务服务（提交/通过/拒绝，通过时自动执行变更）
- EditReviewController.java - REST API（POST submit, POST approve/reject, GET pending）
- DTOs: SubmitReviewRequest, EditReviewVO, ReviewActionRequest, BatchDeleteRequest
- EditReviewServiceTest.java - 单元测试（21 tests）
- EditReviewControllerTest.java - 集成测试（10 tests）
新增文件（前端，3 个）：
- EntityEditForm.tsx - 实体创建/编辑表单（Modal，支持名称/类型/描述/别名/置信度）
- RelationEditForm.tsx - 关系创建/编辑表单（Modal，支持源/目标实体搜索、关系类型、权重/置信度）
- ReviewPanel.tsx - 审核面板（待审核列表，通过/拒绝操作，拒绝带备注）
修改文件（后端，7 个）：
- GraphEntityService.java - 新增 batchDeleteEntities()，updateEntity 支持 confidence
- GraphRelationService.java - 新增 batchDeleteRelations()
- GraphEntityController.java - 删除批量删除端点（改为审核流程）
- GraphRelationController.java - 删除批量删除端点（改为审核流程）
- UpdateEntityRequest.java - 添加 confidence 字段
- KnowledgeGraphErrorCode.java - 新增 REVIEW_NOT_FOUND、REVIEW_ALREADY_PROCESSED
- PermissionRuleMatcher.java - 添加 /api/knowledge-graph/** 写操作权限规则
修改文件（前端，8 个）：
- knowledge-graph.model.ts - 新增 EditReviewVO、ReviewOperationType、ReviewStatus 类型
- knowledge-graph.api.ts - BASE 改为 /api/knowledge-graph（走网关权限链），新增审核相关 API，删除批量删除直删方法
- vite.config.ts - 更新 dev proxy 路径
- NodeDetail.tsx - 新增 editMode 属性，编辑模式下显示编辑/删除按钮
- RelationDetail.tsx - 新增 editMode 属性，编辑模式下显示编辑/删除按钮
- KnowledgeGraphPage.tsx - 新增编辑模式开关（需要 knowledgeGraphWrite 权限）、创建实体/关系工具栏按钮、审核 Tab、批量操作
- GraphCanvas.tsx - 支持多选（editMode 时）、onSelectionChange 回调
- graphConfig.ts - 支持 multiSelect 参数
审核流程：
- 所有编辑操作（创建/更新/删除/批量删除）都通过 submitReview 提交审核
- 审核通过后，EditReviewService.applyChange() 自动执行变更
- 批量删除端点已删除，只能通过审核流程
权限控制：
- API 路径从 /knowledge-graph 改为 /api/knowledge-graph，走网关权限链
- 编辑模式开关需要 knowledgeGraphWrite 权限
- PermissionRuleMatcher 添加 /api/knowledge-graph/** 写操作规则
Bug 修复（Codex 审查后修复）：
- P0: 权限绕过（API 路径改为 /api/knowledge-graph）
- P1: 审核流程未接入（所有编辑操作改为 submitReview）
- P1: 批量删除绕过审核（删除直删端点，改为审核流程）
- P1: confidence 字段丢失（UpdateEntityRequest 添加 confidence）
- P2: 审核提交校验不足（添加跨字段校验器）
- P2: 批量删除安全（添加 @Size(max=100) 限制，收集失败 ID）
- P2: 前端错误处理（分开处理表单校验和 API 失败）
测试结果：
- 后端: 311 tests pass ✅ (280 → 311, +31 new)
- 前端: eslint clean ✅, tsc clean ✅, vite build success ✅
|
2026-02-20 20:38:03 +08:00 |
|
|
|
9b6ff59a11
|
feat(kg): 实现 Phase 3.3 性能优化
核心功能：
- Neo4j 索引优化（entityType, graphId, properties.name）
- Redis 缓存（Java 侧，3 个缓存区，TTL 可配置）
- LRU 缓存（Python 侧，KG + Embedding，线程安全）
- 细粒度缓存清除（graphId 前缀匹配）
- 失败路径缓存清除（finally 块）
新增文件（Java 侧，7 个）：
- V2__PerformanceIndexes.java - Flyway 迁移，创建 3 个索引
- IndexHealthService.java - 索引健康监控
- RedisCacheConfig.java - Spring Cache + Redis 配置
- GraphCacheService.java - 缓存清除管理器
- CacheableIntegrationTest.java - 集成测试（10 tests）
- GraphCacheServiceTest.java - 单元测试（19 tests）
- V2__PerformanceIndexesTest.java, IndexHealthServiceTest.java
新增文件（Python 侧，2 个）：
- cache.py - 内存 TTL+LRU 缓存（cachetools）
- test_cache.py - 单元测试（20 tests）
修改文件（Java 侧，9 个）：
- GraphEntityService.java - 添加 @Cacheable，缓存清除
- GraphQueryService.java - 添加 @Cacheable（包含用户权限上下文）
- GraphRelationService.java - 添加缓存清除
- GraphSyncService.java - 添加缓存清除（finally 块，失败路径）
- KnowledgeGraphProperties.java - 添加 Cache 配置类
- application-knowledgegraph.yml - 添加 Redis 和缓存 TTL 配置
- GraphEntityServiceTest.java - 添加 verify(cacheService) 断言
- GraphRelationServiceTest.java - 添加 verify(cacheService) 断言
- GraphSyncServiceTest.java - 添加失败路径缓存清除测试
修改文件（Python 侧，5 个）：
- kg_client.py - 集成缓存（fulltext_search, get_subgraph）
- interface.py - 添加 /cache/stats 和 /cache/clear 端点
- config.py - 添加缓存配置字段
- pyproject.toml - 添加 cachetools 依赖
- test_kg_client.py - 添加 _disable_cache fixture
安全修复（3 轮迭代）：
- P0: 缓存 key 用户隔离（防止跨用户数据泄露）
- P1-1: 同步子步骤后的缓存清除（18 个方法）
- P1-2: 实体创建后的搜索缓存清除
- P1-3: 失败路径缓存清除（finally 块）
- P2-1: 细粒度缓存清除（graphId 前缀匹配，避免跨图谱冲刷）
- P2-2: 服务层测试添加 verify(cacheService) 断言
测试结果：
- Java: 280 tests pass ✅ (270 → 280, +10 new)
- Python: 154 tests pass ✅ (140 → 154, +14 new)
缓存配置：
- kg:entities - 实体缓存，TTL 1h
- kg:queries - 查询结果缓存，TTL 5min
- kg:search - 全文搜索缓存，TTL 3min
- KG cache (Python) - 256 entries, 5min TTL
- Embedding cache (Python) - 512 entries, 10min TTL
|
2026-02-20 18:28:33 +08:00 |
|
|
|
7abdafc338
|
feat(kg): 实现 Schema 版本管理和迁移机制
- 新增 Schema 迁移框架，参考 Flyway 设计思路
- 支持版本跟踪、变更检测、自动迁移
- 使用分布式锁确保多实例安全
- 支持 Checksum 校验防止已应用迁移被修改
- 使用 MERGE 策略支持失败后重试
- 使用数据库时间消除时钟偏差问题
核心组件：
- SchemaMigration 接口：定义迁移脚本规范
- SchemaMigrationService：核心编排器
- V1__InitialSchema：基线迁移（14 条 DDL）
- SchemaMigrationRecord：迁移记录 POJO
配置项：
- migration.enabled：是否启用迁移（默认 true）
- migration.validate-checksums：是否校验 checksum（默认 true）
向后兼容：
- 已有数据库首次运行时，V1 的 14 条语句全部使用 IF NOT EXISTS
- 适用于全新部署场景
新增 27 个测试用例，全部通过
测试结果：242 tests pass
|
2026-02-19 16:55:33 +08:00 |
|
|
|
cca463e7d1
|
feat(kg): 实现所有路径查询和子图导出功能
- 新增 findAllPaths 接口：查找两个节点之间的所有路径
- 支持 maxDepth 和 maxPaths 参数限制
- 按路径长度升序排序
- 完整的权限过滤（created_by + confidential）
- 添加关系级 graph_id 约束，防止串图
- 新增 exportSubgraph 接口：导出子图
- 支持 depth 参数控制扩展深度
- 支持 JSON 和 GraphML 两种导出格式
- depth=0：仅导出指定实体及其之间的边
- depth>0：扩展 N 跳，收集所有可达邻居
- 添加查询超时保护机制
- 注入 Neo4j Driver，使用 TransactionConfig.withTimeout()
- 默认超时 10 秒，可配置
- 防止复杂查询长期占用资源
- 新增 4 个 DTO：AllPathsVO, ExportNodeVO, ExportEdgeVO, SubgraphExportVO
- 新增 17 个测试用例，全部通过
- 测试结果：226 tests pass
|
2026-02-19 15:46:01 +08:00 |
|
|
|
20446bf57d
|
feat(kg): 实现知识图谱组织同步功能
- 替换硬编码的 org:default 占位符，支持真实组织数据
- 从 users 表的 organization 字段获取组织映射
- 支持多租户场景，每个组织独立管理
- 添加降级保护机制，防止数据丢失
- 修复 BELONGS_TO 关系遗留问题
- 修复组织编码碰撞问题
- 新增 95 个测试用例，全部通过
修改文件：
- Auth 模块：添加组织字段和查询接口
- KG Sync Client：添加用户组织映射
- Core Sync Logic：重写组织实体和关系逻辑
- Tests：新增测试用例覆盖核心场景
|
2026-02-19 15:01:36 +08:00 |
|
|
|
444f8cd015
|
fix: 修复知识图谱模块 P0/P1/P2/P3 问题
【P0 - 安全风险修复】
- InternalTokenInterceptor: fail-open → fail-closed
- 未配置 token 时直接拒绝（401）
- 仅 dev/test 环境可显式跳过校验
- KnowledgeGraphProperties: 新增 skipTokenCheck 配置项
- application-knowledgegraph.yml: 新增 skip-token-check 配置
【P1 - 文档版本控制】
- .gitignore: 移除 docs/knowledge-graph/ 忽略规则
- schema 文档现已纳入版本控制
【P2 - 代码质量改进】
- InternalTokenInterceptor: 错误响应改为 Response.error() 格式
- 新增 InternalTokenInterceptorTest.java（7 个测试用例）
- fail-closed 行为验证
- token 校验逻辑验证
- 错误响应格式验证
【P3 - 文档一致性】
- README.md: 相对链接改为显式 GitHub 链接
【验证结果】
- 编译通过
- 198 个测试全部通过（0 failures）
|
2026-02-19 13:03:42 +08:00 |
|
|
|
f12e4abd83
|
fix(kg): 根据 Codex 审查反馈修复知识图谱同步问题
修复内容：
1. [P1] 修复 job_id 错误清洗问题
- 新增 sanitizePropertyValue() 方法对属性值进行安全处理
- 修复 IMPACTS 关系中 job_id JSON 注入风险
2. [P2] 修复增量同步关系全量重算问题
- 为所有关系构建方法添加 changedEntityIds 参数支持
- 增量同步时仅处理变更实体相关的关系，提升性能
3. [P2] 修复 MERGE ON MATCH 覆盖属性问题
- 实体 upsert 时保留原有非空 name/description 值
- 关系 MERGE 时保留原有非空 properties_json 值
- GraphRelationRepository 中优化条件覆盖逻辑
4. 修复测试 Mock stub 签名不匹配问题
- 同时支持 2 参数和 3 参数版本的关系方法
- 使用 lenient() 模式避免 unnecessary stubbing 错误
Co-Authored-By: Claude Sonnet 4 <noreply@anthropic.com>
|
2026-02-19 09:56:16 +08:00 |
|
|
|
42069f82b3
|
feat(kg): P0-04 同步结果元数据增强
实现同步历史记录和元数据功能：
新增功能：
- 添加 SyncHistory 节点记录同步历史
- 添加 /history 和 /history/range API 查询同步历史
- 添加 /full API 返回完整同步结果（含元数据）
问题修复：
- [P1] syncId 改为完整 UUID (36位)，添加 (graph_id, sync_id) 唯一约束
- [P2-1] /history limit 添加 @Min(1) @Max(200) 边界校验
- [P2-2] /history/range 添加分页 (page, size)，skip 越界保护 (>2M)
- [P2-3] 添加 SyncHistory 索引：(graph_id, started_at), (graph_id, status, started_at)
测试：
- 182 tests 通过 (新增 2 个测试)
- GraphSyncServiceTest, GraphInitializerTest, SyncMetadataTest 全部通过
代码变更：+521 行，-27 行
新增文件：4 个 (SyncMetadata, SyncHistoryRepository, SyncMetadataVO, SyncMetadataTest)
修改文件：5 个
|
2026-02-18 16:55:03 +08:00 |
|
|
|
74daed1c25
|
feat(kg): 实现同步时间窗口过滤（P0-03）
为 DataManagementClient 的 5 个 listAll* 方法添加时间窗口过滤：
- listAllDatasets(updatedFrom, updatedTo)
- listAllWorkflows(updatedFrom, updatedTo)
- listAllJobs(updatedFrom, updatedTo)
- listAllLabelTasks(updatedFrom, updatedTo)
- listAllKnowledgeSets(updatedFrom, updatedTo)
特性：
- 时间参数构建为 HTTP 查询参数（ISO_LOCAL_DATE_TIME 格式）
- 客户端侧双重过滤（兼容上游未支持的场景）
- 参数校验：updatedFrom > updatedTo 时抛出异常
- null 元素安全处理：过滤列表中的 null 项
- 无参版本保留向后兼容
测试：
- 新增 DataManagementClientTest.java（28 个测试用例）
- 覆盖 URL 参数拼接、参数校验、本地过滤、null 安全、分页等场景
- 测试结果：162 tests, 0 failures
代码审查：
- Codex 两轮审查通过
- 修复 P2 问题：null 元素安全处理
|
2026-02-18 14:00:01 +08:00 |
|
|
|
75db6daeb5
|
feat(kg): 实现查询阶段的用户数据权限过滤
新增功能：
- 查询阶段权限过滤：管理员看全部，普通用户只看自己创建的数据
- 结构实体（User、Org、Field）对所有用户可见
- 业务实体（Dataset、Workflow、Job、LabelTask、KnowledgeSet）按 created_by 过滤
- CONFIDENTIAL 敏感度过滤：需要特定权限才能查看
安全修复（四轮迭代）：
P1-1: CONFIDENTIAL 敏感度过滤
- 4 个查询入口统一计算 excludeConfidential
- assertEntityAccess / isEntityAccessible 新增保密数据检查
- buildPermissionPredicate 在 Cypher 中追加 sensitivity 条件
P1-2: 结构实体按类型白名单判定
- 新增常量 STRUCTURAL_ENTITY_TYPES = Set.of("User", "Org", "Field")
- 业务实体必须匹配 created_by（缺失则拒绝）
- Cypher 从 IS NULL OR 改为 type IN ['User', 'Org', 'Field'] OR
P2-1: getNeighborGraph 路径级权限旁路
- 改为 ALL(n IN nodes(p) WHERE ...) 路径全节点过滤
- 与 getShortestPath 保持一致
P2-2: CONFIDENTIAL 大小写归一化
- Cypher 用 toUpper(trim(...)) 比较
- Java 用 equalsIgnoreCase
- 与 data-management-service 保持一致
权限模型：
- 同步阶段：全量同步（保持图谱完整性）
- 查询阶段：根据用户权限过滤结果
- 使用 RequestUserContextHolder 和 ResourceAccessService
代码变更：+642 行，-32 行
测试结果：130 tests, 0 failures
新增 9 个测试用例
已知 P3 问题（非阻断，可后续优化）：
- 组件扫描范围偏大
- 测试质量可进一步增强
- 结构实体白名单重复维护
|
2026-02-18 12:24:09 +08:00 |
|
|
|
ebb4548ca5
|
feat(kg): 补全知识图谱实体同步和关系构建
新增功能：
- 补全 4 类实体同步：Workflow、Job、LabelTask、KnowledgeSet
- 补全 7 类关系构建：USES_DATASET、PRODUCES、ASSIGNED_TO、TRIGGERS、DEPENDS_ON、IMPACTS、SOURCED_FROM
- 新增 39 个测试用例，总计 111 个测试
问题修复（三轮迭代）：
第一轮（6 个问题）：
- toStringList null/blank 过滤
- mergeUsesDatasetRelations 统一逻辑
- fetchAllPaged 去重抽取
- IMPACTS 占位标记
- 测试断言增强
- syncAll 固定索引改 Map
第二轮（2 个问题）：
- 活跃 ID 空值/空白归一化（两层防御）
- 关系构建 N+1 查询消除（预加载 Map）
第三轮（1 个问题）：
- 空元素 NPE 防御（GraphSyncService 12 处 + GraphSyncStepService 6 处）
代码变更：+1936 行，-101 行
测试结果：111 tests, 0 failures
已知 P3 问题（非阻塞）：
- 安全注释与实现不一致（待权限过滤任务一起处理）
- 测试覆盖缺口（可后续补充）
|
2026-02-18 11:30:38 +08:00 |
|
|
|
37b478a052
|
fix(kg): 修复 Codex 审查发现的 P1/P2 问题并补全测试
修复内容：
P1 级别（关键）：
1. 数据隔离漏洞：邻居查询添加 graph_id 路径约束，防止跨图谱数据泄漏
2. 空快照误删风险：添加 allowPurgeOnEmptySnapshot 保护开关（默认 false）
3. 弱默认凭据：启动自检，生产环境检测到默认密码直接拒绝启动
P2 级别（重要）：
4. 配置校验：importBatchSize 添加 @Min(1) 验证，启动时 fail-fast
5. N+1 性能：重写 upsertEntity 为单条 Cypher 查询（从 3 条优化到 1 条）
6. 服务认证：添加 mTLS/JWT 文档说明
7. 错误处理：改进 Schema 初始化和序列化错误处理
测试覆盖：
- 新增 69 个单元测试，全部通过
- GraphEntityServiceTest: 13 个测试（CRUD、验证、分页）
- GraphRelationServiceTest: 13 个测试（CRUD、方向验证）
- GraphSyncServiceTest: 5 个测试（验证、全量同步）
- GraphSyncStepServiceTest: 14 个测试（空快照保护、N+1 验证）
- GraphQueryServiceTest: 13 个测试（邻居/路径/子图/搜索）
- GraphInitializerTest: 11 个测试（凭据验证、Schema 初始化）
技术细节：
- 数据隔离：使用 ALL() 函数约束路径中所有节点和关系的 graph_id
- 空快照保护：新增配置项 allow-purge-on-empty-snapshot 和错误码 EMPTY_SNAPSHOT_PURGE_BLOCKED
- 凭据检查：Java 和 Python 双端实现，根据环境（dev/test/prod）采取不同策略
- 性能优化：使用 SDN 复合属性格式（properties.key）在 MERGE 中直接设置属性
- 属性安全：使用白名单 [a-zA-Z0-9_] 防止 Cypher 注入
代码变更：+210 行，-29 行
|
2026-02-18 09:25:00 +08:00 |
|
|
|
a260134d7c
|
fix(knowledge-graph): 修复 Codex 审查发现的 5 个问题并新增查询功能
本次提交包含两部分内容：
1. 新增知识图谱查询功能（邻居查询、最短路径、子图提取、全文搜索）
2. 修复 Codex 代码审查发现的 5 个问题（3 个 P1 严重问题 + 2 个 P2 次要问题）
## 新增功能
### GraphQueryService 和 GraphQueryController
- 邻居查询：GET /query/neighbors/{entityId}?depth=2&limit=50
- 最短路径：GET /query/shortest-path?sourceId=...&targetId=...&maxDepth=3
- 子图提取：POST /query/subgraph + body {"entityIds": [...]}
- 全文搜索：GET /query/search?q=keyword&page=0&size=20
### 新增 DTO
- EntitySummaryVO, EdgeSummaryVO：实体和边的摘要信息
- SubgraphVO：子图结果（nodes + edges + counts）
- PathVO：路径结果
- SearchHitVO：搜索结果（含相关度分数）
- SubgraphRequest：子图请求 DTO（含校验）
## 问题修复
### P1-1: 邻居查询图边界风险
**文件**: GraphQueryService.java
**问题**: getNeighborGraph 使用 -[*1..N]-，未约束中间路径节点/关系的 graph_id
**修复**:
- 使用路径变量 p：MATCH p = ...
- 添加 ALL(n IN nodes(p) WHERE n.graph_id = $graphId)
- 添加 ALL(r IN relationships(p) WHERE r.graph_id = $graphId)
- 限定关系类型为 :RELATED_TO
- 排除自环：WHERE e <> neighbor
### P1-2: 全图扫描性能风险
**文件**: GraphRelationRepository.java
**问题**: findByEntityId/countByEntityId 先匹配全图关系，再用 s.id = X OR t.id = X 过滤
**修复**:
- findByEntityId：改为 CALL { 出边锚定查询 UNION ALL 入边锚定查询 }
- countByEntityId：
- "in"/"out" 方向：将 id: $entityId 直接写入 MATCH 模式
- "all" 方向：改为 CALL { 出边 UNION 入边 } RETURN count(r)
- 利用 (graph_id, id) 索引直接定位，避免全图扫描
### P1-3: 接口破坏性变更
**文件**: GraphEntityController.java
**问题**: GET /knowledge-graph/{graphId}/entities 从 List<GraphEntity> 变为 PagedResponse<GraphEntity>
**修复**: 使用 Spring MVC params 属性实现零破坏性升级
- @GetMapping(params = "!page")：无 page 参数时返回 List（向后兼容）
- @GetMapping(params = "page")：有 page 参数时返回 PagedResponse（新功能）
- 现有调用方无需改动，新调用方可选择分页
### P2-4: direction 参数未严格校验
**文件**: GraphEntityController.java, GraphRelationService.java
**问题**: 非法 direction 值被静默当作 "all" 处理
**修复**: 双层校验
- Controller 层：@Pattern(regexp = "^(all|in|out)$")
- Service 层：VALID_DIRECTIONS.contains() 校验
- 非法值返回 INVALID_PARAMETER 异常
### P2-5: 子图接口请求体缺少元素级校验
**文件**: GraphQueryController.java, SubgraphRequest.java
**问题**: /query/subgraph 直接接收 List<String>，无 UUID 校验
**修复**: 创建 SubgraphRequest DTO
- @NotEmpty：列表不能为空
- @Size(max = 500)：元素数量上限
- List<@Pattern(UUID) String>：每个元素必须是合法 UUID
- Controller 使用 @Valid @RequestBody SubgraphRequest
- ⚠️ API 变更：请求体格式从 ["uuid1"] 变为 {"entityIds": ["uuid1"]}
## 技术亮点
1. **图边界安全**: 路径变量 + ALL 约束确保跨图查询安全
2. **查询性能**: 实体锚定查询替代全图扫描，利用索引优化
3. **向后兼容**: params 属性实现同路径双端点，零破坏性升级
4. **多层防御**: Controller + Service 双层校验，框架级 + 业务级
5. **类型安全**: DTO + Bean Validation 确保请求体格式和内容合法
## 测试建议
1. 编译验证：mvn -pl services/knowledge-graph-service -am compile
2. 测试邻居查询的图边界约束
3. 测试实体关系查询的性能（大数据集）
4. 验证实体列表接口的向后兼容性（无 page 参数）
5. 测试 direction 参数的非法值拒绝
6. 测试子图接口的请求体校验（非法 UUID、空列表、超限）
Co-authored-by: Claude (Anthropic)
Reviewed-by: Codex (OpenAI)
|
2026-02-18 07:49:16 +08:00 |
|
|
|
8b1ab8ff36
|
feat(kg-sync): 实现图谱构建流程（MySQL → Neo4j 同步）
实现功能：
- 实现 GraphSyncService（同步编排器）
- 实现 GraphSyncStepService（同步步骤执行器）
- 实现 GraphSyncController（同步 API）
- 实现 GraphInitializer（图谱初始化）
- 实现 DataManagementClient（数据源客户端）
同步功能：
- syncDatasets：同步数据集实体
- syncFields：同步字段实体
- syncUsers：同步用户实体
- syncOrgs：同步组织实体
- buildHasFieldRelations：构建 HAS_FIELD 关系
- buildDerivedFromRelations：构建 DERIVED_FROM 关系
- buildBelongsToRelations：构建 BELONGS_TO 关系
- syncAll：全量同步（实体 + 关系 + 对账删除）
API 端点：
- POST /{graphId}/sync/full：全量同步
- POST /{graphId}/sync/datasets：同步数据集
- POST /{graphId}/sync/fields：同步字段
- POST /{graphId}/sync/users：同步用户
- POST /{graphId}/sync/orgs：同步组织
- POST /{graphId}/sync/relations/has-field：构建 HAS_FIELD
- POST /{graphId}/sync/relations/derived-from：构建 DERIVED_FROM
- POST /{graphId}/sync/relations/belongs-to：构建 BELONGS_TO
技术实现：
- Upsert 策略：
- 实体：两阶段（Cypher MERGE 原子创建 + SDN save 更新扩展属性）
- 关系：Cypher MERGE 幂等创建
- 全量对账删除：purgeStaleEntities() 删除 MySQL 中已删除的实体
- 并发安全：
- 图级互斥锁（ConcurrentHashMap<String, ReentrantLock>）
- 复合唯一约束（graph_id, source_id, type）
- 锁自动回收（releaseLock() 原子检查并移除空闲锁）
- 重试机制：HTTP 调用失败时按指数退避重试（默认 3 次）
- 错误处理：
- 逐条错误处理（单条失败不影响其他记录）
- 统一异常包装（BusinessException.of(SYNC_FAILED)）
- 错误信息脱敏（仅返回 errorCount + syncId）
- 事务管理：
- GraphSyncService（编排器，无事务）
- GraphSyncStepService（步骤执行器，@Transactional）
- 性能优化：
- 全量同步共享数据快照
- 批量日志跟踪
- 图谱初始化：
- 1 个唯一性约束（entity ID）
- 1 个复合唯一约束（graph_id, source_id, type）
- 9 个索引（5 个单字段 + 3 个复合 + 1 个全文）
- 幂等性保证（IF NOT EXISTS）
代码审查：
- 经过 3 轮 Codex 审查和 2 轮 Claude 修复
- 所有问题已解决（3个P0 + 5个P1 + 3个P2 + 1个P3）
- 编译验证通过（mvn compile SUCCESS）
设计决策：
- 最终一致性：允许短暂的数据不一致
- 对账机制：定期对比并修复差异
- 信任边界：网关负责鉴权，服务层只做格式校验
- 多实例部署：依赖复合唯一约束兜底
|
2026-02-17 23:46:03 +08:00 |
|
|
|
910251e898
|
feat(kg-relation): 实现 Java 关系（Relation）功能
实现功能：
- 实现 GraphRelationRepository（Neo4jClient + Cypher）
- 实现 GraphRelationService（业务逻辑层）
- 实现 GraphRelationController（REST API）
- 新增 RelationDetail 领域对象
- 新增 RelationVO、UpdateRelationRequest DTO
API 端点：
- POST /{graphId}/relations：创建关系（201）
- GET /{graphId}/relations：分页列表查询（支持 type/page/size）
- GET /{graphId}/relations/{relationId}：单个查询
- PUT /{graphId}/relations/{relationId}：更新关系
- DELETE /{graphId}/relations/{relationId}：删除关系（204）
技术实现：
- Repository：
- 使用 Neo4jClient + Cypher 实现 CRUD
- 使用 bindAll(Map) 一次性绑定参数
- properties 字段使用 JSON 序列化存储
- 支持分页查询（SKIP/LIMIT）
- 支持类型过滤
- Service：
- graphId UUID 格式校验
- 实体存在性校验
- @Transactional 事务管理
- 信任边界说明（网关负责鉴权）
- 分页 skip 使用 long 计算，上限保护 100,000
- Controller：
- 所有 pathVariable 添加 UUID pattern 校验
- 使用 @Validated 启用参数校验
- 使用平台统一的 PagedResponse 分页响应
- DTO：
- weight/confidence 添加 @DecimalMin/@DecimalMax（0.0-1.0）
- relationType 添加 @Size（1-50）
- sourceEntityId/targetEntityId 添加 UUID pattern 校验
架构设计：
- 分层清晰：interfaces → application → domain
- Repository 返回领域对象 RelationDetail
- DTO 转换在 Service 层
- 关系类型：Neo4j 使用统一 RELATED_TO 标签，语义类型存储在 relation_type 属性
代码审查：
- 经过 2 轮 Codex 审查和 1 轮 Claude 修复
- 所有问题已解决（2个P0 + 2个P1 + 4个P2）
- 编译验证通过（mvn compile SUCCESS）
设计决策：
- 使用 Neo4jClient 而非 Neo4jRepository（@RelationshipProperties 限制）
- 分页 size 上限 200，防止大查询
- properties 使用 JSON 序列化，支持灵活扩展
- 复用现有错误码（ENTITY_NOT_FOUND、RELATION_NOT_FOUND、INVALID_RELATION）
|
2026-02-17 22:40:27 +08:00 |
|
|
|
5a553ddde3
|
feat(knowledge-graph): 实现知识图谱基础设施搭建
实现功能：
- Neo4j Docker Compose 配置（社区版，端口 7474/7687，数据持久化）
- Makefile 新增 Neo4j 命令（neo4j-up/down/logs/shell）
- knowledge-graph-service Spring Boot 服务（完整的 DDD 分层架构）
- kg_extraction Python 模块（基于 LangChain LLMGraphTransformer）
技术实现：
- Neo4j 配置：环境变量化密码，统一默认值 datamate123
- Java 服务：
- Domain: GraphEntity, GraphRelation 实体模型
- Repository: Spring Data Neo4j，支持 graphId 范围查询
- Service: 业务逻辑，graphId 双重校验，查询限流
- Controller: REST API，UUID 格式校验
- Exception: 实现 ErrorCode 接口，统一异常体系
- Python 模块：
- KnowledgeGraphExtractor 类
- 支持异步/同步/批量抽取
- 支持 schema-guided 模式
- 兼容 OpenAI 及自部署模型
关键设计：
- graphId 权限边界：所有实体操作都在正确的 graphId 范围内
- 查询限流：depth 和 limit 参数受配置约束
- 异常处理：统一使用 BusinessException + ErrorCode
- 凭据管理：环境变量化，避免硬编码
- 双重防御：Controller 格式校验 + Service 业务校验
代码审查：
- 经过 3 轮 Codex 审查和 2 轮 Claude 修复
- 所有 P0 和 P1 问题已解决
- 编译通过，无阻塞性问题
文件变更：
- 新增：Neo4j 配置、knowledge-graph-service（11 个 Java 文件）、kg_extraction（3 个 Python 文件）
- 修改：Makefile、pom.xml、application.yml、pyproject.toml
|
2026-02-17 20:42:55 +08:00 |
|
