lingyue-zhibao/backend/graph-service/src/main/java/com/lingyue/graph/dto/KnowledgeGraphDTO.java

package com.lingyue.graph.dto;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import lombok.Builder;
import lombok.NoArgsConstructor;
import lombok.AllArgsConstructor;

import java.util.List;
import java.util.Map;

/**
 * 知识图谱 DTO
 * 用于前端图谱可视化渲染
 * 
 * @author lingyue
 * @since 2026-01-21
 */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Schema(description = "知识图谱")
public class KnowledgeGraphDTO {
    
    @Schema(description = "文档ID（单文档图谱时）")
    private String documentId;
    
    @Schema(description = "图谱标题")
    private String title;
    
    @Schema(description = "节点列表")
    private List<NodeDTO> nodes;
    
    @Schema(description = "关系/边列表")
    private List<EdgeDTO> edges;
    
    @Schema(description = "统计信息")
    private GraphStats stats;
    
    /**
     * 节点 DTO
     */
    @Data
    @Builder
    @NoArgsConstructor
    @AllArgsConstructor
    @Schema(description = "图谱节点")
    public static class NodeDTO {
        
        @Schema(description = "节点ID")
        private String id;
        
        @Schema(description = "节点名称（显示文本）")
        private String name;
        
        @Schema(description = "节点类型", example = "entity/concept/data/location/person/org")
        private String type;
        
        @Schema(description = "显示图标（emoji）")
        private String icon;
        
        @Schema(description = "节点颜色")
        private String color;
        
        @Schema(description = "节点大小（基于关联数量）")
        private Integer size;
        
        @Schema(description = "关联实体数量")
        private Integer relationCount;
        
        @Schema(description = "在文档中出现次数")
        private Integer occurrenceCount;
        
        @Schema(description = "节点值（如数据类型的具体值）")
        private String value;
        
        @Schema(description = "来源文档ID列表")
        private List<String> documentIds;
        
        @Schema(description = "位置信息")
        private Map<String, Object> position;
        
        @Schema(description = "元数据")
        private Map<String, Object> metadata;
    }
    
    /**
     * 边/关系 DTO
     */
    @Data
    @Builder
    @NoArgsConstructor
    @AllArgsConstructor
    @Schema(description = "图谱边/关系")
    public static class EdgeDTO {
        
        @Schema(description = "边ID")
        private String id;
        
        @Schema(description = "源节点ID")
        private String source;
        
        @Schema(description = "源节点名称")
        private String sourceName;
        
        @Schema(description = "目标节点ID")
        private String target;
        
        @Schema(description = "目标节点名称")
        private String targetName;
        
        @Schema(description = "关系类型", example = "属于/包含/位于/负责")
        private String relationType;
        
        @Schema(description = "关系标签（显示文本）")
        private String label;
        
        @Schema(description = "边的权重/强度")
        private Double weight;
        
        @Schema(description = "元数据")
        private Map<String, Object> metadata;
    }
    
    /**
     * 图谱统计
     */
    @Data
    @Builder
    @NoArgsConstructor
    @AllArgsConstructor
    @Schema(description = "图谱统计")
    public static class GraphStats {
        
        @Schema(description = "总节点数")
        private Integer totalNodes;
        
        @Schema(description = "总关系数")
        private Integer totalEdges;
        
        @Schema(description = "按类型统计节点数")
        private Map<String, Integer> nodesByType;
        
        @Schema(description = "按类型统计关系数")
        private Map<String, Integer> edgesByType;
    }
    
    /**
     * 实体列表项 DTO（用于列表视图）
     */
    @Data
    @Builder
    @NoArgsConstructor
    @AllArgsConstructor
    @Schema(description = "实体列表项")
    public static class EntityListItemDTO {
        
        @Schema(description = "实体ID")
        private String id;
        
        @Schema(description = "实体名称")
        private String name;
        
        @Schema(description = "实体类型")
        private String type;
        
        @Schema(description = "类型显示名称")
        private String typeName;
        
        @Schema(description = "图标")
        private String icon;
        
        @Schema(description = "颜色")
        private String color;
        
        @Schema(description = "出现次数")
        private Integer occurrenceCount;
        
        @Schema(description = "关联实体数量")
        private Integer relationCount;
        
        @Schema(description = "关联实体预览（前几个）")
        private List<RelatedEntityDTO> relatedEntities;
    }
    
    /**
     * 关联实体预览
     */
    @Data
    @Builder
    @NoArgsConstructor
    @AllArgsConstructor
    @Schema(description = "关联实体")
    public static class RelatedEntityDTO {
        
        @Schema(description = "实体ID")
        private String id;
        
        @Schema(description = "实体名称")
        private String name;
        
        @Schema(description = "关系类型")
        private String relationType;
    }
    
    /**
     * 实体列表分组
     */
    @Data
    @Builder
    @NoArgsConstructor
    @AllArgsConstructor
    @Schema(description = "实体列表分组")
    public static class EntityGroupDTO {
        
        @Schema(description = "分组类型")
        private String type;
        
        @Schema(description = "分组名称")
        private String typeName;
        
        @Schema(description = "分组颜色")
        private String color;
        
        @Schema(description = "实体数量")
        private Integer count;
        
        @Schema(description = "实体列表")
        private List<EntityListItemDTO> entities;
    }
    
    /**
     * 实体详情
     */
    @Data
    @Builder
    @NoArgsConstructor
    @AllArgsConstructor
    @Schema(description = "实体详情")
    public static class EntityDetailDTO {
        
        @Schema(description = "实体ID")
        private String id;
        
        @Schema(description = "实体名称")
        private String name;
        
        @Schema(description = "实体类型")
        private String type;
        
        @Schema(description = "类型显示名称")
        private String typeName;
        
        @Schema(description = "实体值")
        private String value;
        
        @Schema(description = "图标")
        private String icon;
        
        @Schema(description = "颜色")
        private String color;
        
        @Schema(description = "出现次数")
        private Integer occurrenceCount;
        
        @Schema(description = "所有关联实体")
        private List<RelatedEntityDTO> allRelations;
        
        @Schema(description = "出现位置列表")
        private List<OccurrenceDTO> occurrences;
        
        @Schema(description = "来源文档列表")
        private List<DocumentRefDTO> documents;
        
        @Schema(description = "元数据")
        private Map<String, Object> metadata;
    }
    
    /**
     * 出现位置
     */
    @Data
    @Builder
    @NoArgsConstructor
    @AllArgsConstructor
    @Schema(description = "出现位置")
    public static class OccurrenceDTO {
        
        @Schema(description = "文档ID")
        private String documentId;
        
        @Schema(description = "文档名称")
        private String documentName;
        
        @Schema(description = "上下文片段")
        private String context;
        
        @Schema(description = "位置信息")
        private Map<String, Object> position;
    }
    
    /**
     * 文档引用
     */
    @Data
    @Builder
    @NoArgsConstructor
    @AllArgsConstructor
    @Schema(description = "文档引用")
    public static class DocumentRefDTO {
        
        @Schema(description = "文档ID")
        private String documentId;
        
        @Schema(description = "文档名称")
        private String documentName;
        
        @Schema(description = "在该文档中的出现次数")
        private Integer count;
    }
}