q792602257/DataMate
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
576 Commits 1 Branch 0 Tags
0ed7dcbee72e591733961d68b33c9336096a1683
Commit Graph

14 Commits

Author SHA1 Message Date
Jerry Yan
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
Jerry Yan
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
Jerry Yan
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
Jerry Yan
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
Jerry Yan
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
Jerry Yan
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
Jerry Yan
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
Jerry Yan
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
Jerry Yan
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
Jerry Yan
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
Jerry Yan
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
Jerry Yan
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
Jerry Yan
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
Jerry Yan
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