|
|
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 |
|
