classDiagram direction TB %% ── 枚举 ────────────────────────────────────────── class AudienceEnum { <> employee_quick_reply engineer_workguide } class SuggestionStatusEnum { <> pending queued approved rejected applied graph_synced expired } class GraphSyncStatusEnum { <> pending synced failed } class SourceTypeEnum { <> annotation conversation ai_uncertain manual document_ragflow } class RelationTypeEnum { <> LEADS_TO RELATES_TO CAN_JUMP_TO } %% ── PostgreSQL 模型 ─────────────────────────────── class KnowledgeSuggestion { +str id +str suggestion_type +SuggestionStatusEnum status +str title +str content +str category +List~str~ tags +SourceTypeEnum source_type +List~str~ source_data +str reason +str reject_reason +str reviewer_id +datetime reviewed_at +datetime created_at +datetime updated_at +float confidence +AudienceEnum audience +str issue +str action +RelationTypeEnum relation_type +str parent_issue +dict graph_meta +GraphSyncStatusEnum graph_sync_status +bool source_failed +datetime queued_at +datetime applied_at } class KnowledgeBase { +str id +str category +str title +str content +List~str~ tags +int view_count +int use_count +GraphSyncStatusEnum graph_sync_status +str graph_node_uuid +datetime created_at +datetime updated_at } class Conversation { +str id +str employee_id +str status +str session_type +datetime created_at } %% ── Neo4j 图节点模型 ────────────────────────────── class IssueNode { +str uuid +str name +str category +datetime created_at +datetime updated_at +str source_suggestion_id } class ActionNode { +str uuid +str name +str description +datetime created_at +str source_suggestion_id } class InfoNode { +str uuid +str name +str value +List~str~ modifiers +datetime created_at } class RelationEdge { +str from_uuid +str to_uuid +RelationTypeEnum type +int order +float weight } %% ── Pydantic Schema ─────────────────────────────── class KnowledgeSuggestionCreate { +str suggestion_type +str title +str content +str category +List~str~ tags +SourceTypeEnum source_type +List~str~ source_data +str reason +float confidence +AudienceEnum audience +str issue +str action +RelationTypeEnum relation_type +str parent_issue +dict graph_meta } class KnowledgeSuggestionResponse { +str id +str suggestion_type +SuggestionStatusEnum status +str title +str content +str category +List~str~ tags +SourceTypeEnum source_type +float confidence +AudienceEnum audience +str issue +str action +RelationTypeEnum relation_type +str parent_issue +dict graph_meta +GraphSyncStatusEnum graph_sync_status +bool source_failed +datetime queued_at +datetime applied_at +datetime created_at } class KnowledgeSuggestionApprove { <> } class KnowledgeSuggestionReject { <> +str reject_reason } class KnowledgeSuggestionRewrite { <> +str title +str content +str category +List~str~ tags +float confidence +AudienceEnum audience +str issue +str action +RelationTypeEnum relation_type +str parent_issue } class VisionRequest { <> +str conversation_id +bytes image_file } class VisionResponse { +str description +float confidence +dict metadata } class RagflowIngestionRequest { <> +str file_name +bytes file_data +str category_hint } class RagflowIngestionResponse { +str task_id +str status +List~KnowledgeSuggestionResponse~ suggestions } %% ── 服务类 ──────────────────────────────────────── class KnowledgeIterationService { -str ai_api_url -str ai_api_key +analyze_and_generate_suggestions(db, days) dict -_analyze_annotation_data(db, days) dict -_analyze_conversation_data(db, days) dict -_generate_update_suggestion(db, source_type, source_data, reason) KnowledgeSuggestion -_generate_new_faq_suggestion(db, source_type, source_data, reason) KnowledgeSuggestion -_check_existing_suggestion(db, source_id) bool -_auto_tag_audience(db, source_type, source_data) AudienceEnum +approve_suggestion(db, suggestion_id, reviewer_id) KnowledgeSuggestion +reject_suggestion(db, suggestion_id, reviewer_id, reason) KnowledgeSuggestion +rewrite_suggestion(db, suggestion_id, reviewer_id, data) KnowledgeSuggestion +queue_suggestion(db, suggestion_id) KnowledgeSuggestion +dequeue_approve(db, suggestion_id, reviewer_id) KnowledgeSuggestion +sync_to_neo4j(neo4j_client, suggestion) bool +get_suggestion_stats(db) dict +get_queue_stats(db) dict } class WingmanService { -str api_url -str api_key -int timeout -httpx.AsyncClient _client +generate_draft(conversation_id, messages, db) dict +generate_summary(conversation_id, messages) dict +suggest_tags(conversation_id, messages, existing_tags) dict +generate_knowledge_suggestion(context_messages) dict -_build_context_messages(messages, system_prompt) list -_call_wingman_api(context_messages) str -_parse_json_response(content, default) dict -_estimate_confidence(content) float +close() } class Neo4jClient { -str uri -str user -str password -str database -AsyncDriver _driver +initialize() +close() +create_issue_node(issue) IssueNode +create_action_node(action) ActionNode +create_relation(from_uuid, to_uuid, rel) RelationEdge +merge_issue(name, category, props) IssueNode +merge_action(name, props) ActionNode +find_issue_by_name(name) IssueNode +find_related_issues(uuid, rel_type) List~IssueNode~ +execute_write_query(cypher, params) result +execute_read_query(cypher, params) result +health_check() bool } class VisionService { -str dify_vision_api_url -str dify_vision_api_key -str local_vision_model +analyze_screenshot(image_bytes, conversation_id) VisionResponse -_preprocess_image(image_bytes) bytes -_call_vision_workflow(processed_image) dict +inject_to_conversation_context(description, conversation_id) } class RagflowIngestionService { -RagflowClient client +upload_and_process(file_data, file_name, category_hint) RagflowIngestionResponse +poll_processing_status(task_id) str +create_suggestions_from_result(result) List~KnowledgeSuggestion~ } %% ── 关系 ────────────────────────────────────────── KnowledgeSuggestion ..> AudienceEnum : uses KnowledgeSuggestion ..> SuggestionStatusEnum : uses KnowledgeSuggestion ..> SourceTypeEnum : uses KnowledgeSuggestion ..> RelationTypeEnum : uses KnowledgeSuggestion ..> GraphSyncStatusEnum : uses KnowledgeBase ..> GraphSyncStatusEnum : uses KnowledgeIterationService --> WingmanService : 调用 AI 生成 KnowledgeIterationService --> Neo4jClient : 写图同步 KnowledgeIterationService --> KnowledgeSuggestion : 管理 KnowledgeIterationService --> KnowledgeBase : 落库 KnowledgeSuggestionCreate --> KnowledgeSuggestion : 创建 KnowledgeSuggestionResponse --> KnowledgeSuggestion : 返回 KnowledgeSuggestionApprove --> KnowledgeSuggestion : 状态变更 KnowledgeSuggestionReject --> KnowledgeSuggestion : 状态变更 KnowledgeSuggestionRewrite --> KnowledgeSuggestion : 内容更新 IssueNode <--> RelationEdge : 关联 ActionNode <--> RelationEdge : 关联 Neo4jClient --> IssueNode : CRUD Neo4jClient --> ActionNode : CRUD Neo4jClient --> RelationEdge : 管理 VisionService --> WingmanService : 复用 _call_wingman_api 范式 RagflowIngestionService --> KnowledgeSuggestion : 产出