graph LR
    subgraph Clients["客户端"]
        Browser["浏览器 (Vue3 SPA)"]
        Mini["微信小程序 (miniprogram/)"]
        CLI["CLI / Go SDK (cli/, client/)"]
        MCPC["MCP 客户端 (mcp-server/)"]
        IM["IM 平台 (微信/飞书/钉钉/Slack...)"]
    end

    subgraph Compose["Docker Compose: WeKnora-network"]
        FE["frontend: NGINX + 静态资源 (:80)"]
        APP["app: Go 主服务 (:8080)
Gin REST + SSE / Agent 引擎 / Asynq worker"]
        DR["docreader: Python gRPC (:50051)
PDF / DOCX / Excel / Web 解析"]
        PG[("postgres: ParadeDB pg17
业务数据 + BM25 + pgvector")]
        RD[("redis 7
Asynq 队列 / 流管理 / PubSub / 限流")]
        SBX["sandbox 容器 (按需 docker run)"]
        subgraph Optional["可选 profile"]
            SX["searxng (联网搜索)"]
            NEO[("neo4j (知识图谱)")]
            VDB[("qdrant / milvus / weaviate / doris")]
            MINIO[("minio (对象存储)")]
            LF["langfuse 可观测栈"]
        end
    end

    EXT["外部服务: LLM API / Elasticsearch / OpenSearch / COS / S3 / OSS ..."]

    Browser -->|"HTTP / SSE"| FE
    Mini -->|"HTTP"| APP
    CLI -->|"HTTP"| APP
    MCPC -->|"HTTP (X-API-Key)"| APP
    IM -->|"webhook / SDK 长连接"| APP
    FE -->|"反向代理 /api"| APP
    APP -->|"gRPC ReadStream"| DR
    APP -->|"GORM (SQL)"| PG
    APP -->|"RESP"| RD
    APP -->|"docker run"| SBX
    APP -->|"HTTP"| SX
    APP -->|"Bolt"| NEO
    APP -->|"SDK"| VDB
    APP -->|"S3 API"| MINIO
    APP -->|"HTTPS"| EXT
    APP -.->|"trace 上报"| LF
    DR -.->|"共享卷 docreader-tmp"| APP

sequenceDiagram
    autonumber
    participant U as 浏览器
    participant N as "frontend (NGINX)"
    participant A as "app (Gin Handler 层)"
    participant S as "KnowledgeService (Service 层)"
    participant R as "Redis (Asynq)"
    participant W as "Asynq Worker (app 进程内)"
    participant D as "docreader (gRPC)"
    participant E as "Embedding 模型 (LLM Provider)"
    participant V as "向量库 (pgvector / qdrant ...)"
    participant P as "PostgreSQL"

    U->>N: POST /api/v1/knowledge-bases/:id/knowledge/file
    N->>A: 反向代理
    A->>A: "中间件链: RequestID → Auth(JWT/APIKey) → APIKeyGate → RBAC(OwnedKBOrAdmin)"
    A->>S: KnowledgeHandler → CreateKnowledgeFromFile
    S->>P: "写入 knowledge 行 (parse_status=pending), 文件落盘/对象存储"
    S->>R: "Enqueue TypeDocumentProcess (queue=default)"
    A-->>U: "202 返回 knowledge_id (前端轮询/订阅进度)"
    R->>W: 派发任务 (Core worker pool)
    W->>D: "gRPC ReadStream(文件字节/URL)"
    D-->>W: "Markdown 文本 + 图片 (含 OCR / 页面渲染)"
    W->>W: "分块 Chunking (parent-child / heading 策略)"
    W->>E: "批量 Embedding (BatchEmbedder, 受 per-model 并发闸门约束)"
    E-->>W: 向量
    W->>V: 写入向量索引 + BM25 关键词索引
    W->>P: "写入 chunks, parse_status=finalizing"
    W->>R: "Enqueue 富化子任务: summary / question / graph (enrichment 队列)"
    R->>W: Enrichment worker 消费
    W->>P: "回写摘要/问题/实体, PendingSubtasksCount 归零 → parse_status=completed"