docs: test reports + knowledge iteration design + PRDs

提交 OTP/RBAC/Tier0/Tier1/P0+P2 测试报告、方案A E2E 验证、知识库迭代设计(PRD/mermaid/html 原型)、项目状态看板更新; 根配置 docker-compose.yml/mkdocs.yml。
2026-07-09 11:50:19 +08:00
parent 584c975e7f
commit e4e2de47bb
21 changed files with 3311 additions and 214 deletions
@@ -0,0 +1,321 @@
+classDiagram
+    direction TB
+
+    %% ── 枚举 ──────────────────────────────────────────
+    class AudienceEnum {
+        <<enumeration>>
+        employee_quick_reply
+        engineer_workguide
+    }
+
+    class SuggestionStatusEnum {
+        <<enumeration>>
+        pending
+        queued
+        approved
+        rejected
+        applied
+        graph_synced
+        expired
+    }
+
+    class GraphSyncStatusEnum {
+        <<enumeration>>
+        pending
+        synced
+        failed
+    }
+
+    class SourceTypeEnum {
+        <<enumeration>>
+        annotation
+        conversation
+        ai_uncertain
+        manual
+        document_ragflow
+    }
+
+    class RelationTypeEnum {
+        <<enumeration>>
+        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 {
+        <<request>>
+    }
+
+    class KnowledgeSuggestionReject {
+        <<request>>
+        +str reject_reason
+    }
+
+    class KnowledgeSuggestionRewrite {
+        <<request>>
+        +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 {
+        <<request>>
+        +str conversation_id
+        +bytes image_file
+    }
+
+    class VisionResponse {
+        +str description
+        +float confidence
+        +dict metadata
+    }
+
+    class RagflowIngestionRequest {
+        <<request>>
+        +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 : 产出