WebhockTransfer/docs/webhook-relay/FLOWCHART.md

Webhook 中继系统流程图

1. 系统宏观架构图

graph TB
    subgraph External["外部世界"]
        Sender["发送方 (支付宝/微信/业务系统)"]
        User["管理员"]
        TargetSys["目标系统 (ERP/BI)"]
        NotifyApp["IM工具 (飞书/企微)"]
    end

    subgraph WebhookRelay["Webhook中继服务 (Docker)"]
        direction TB
        
        subgraph Interface["接入层"]
            API["FastAPI (端口:8080)"]
            AdminUI["Web管理后台"]
        end

        subgraph Core["核心逻辑层"]
            Parser["数据解析 (Pydantic)"]
            Router["路由引擎 (Routing)"]
            Notifier["通知引擎 (Notification)"]
            Logger["日志审计 (Logging)"]
        end

        subgraph Data["数据存储层"]
            DB[(SQLite 数据库)]
            Config["Config Loader (DB优先 + YAML回退)"]
        end
    end

    Sender -->|POST JSON| API
    User -->|浏览器访问| AdminUI
    AdminUI -->|CRUD配置| DB
    
    API --> Parser
    Parser --> Router
    Parser --> Notifier
    
    Router <-->|查询规则| Config
    Notifier <-->|查询模板| Config
    Config <-->|读取| DB

    Router -->|转发请求| TargetSys
    Notifier -->|推送消息| NotifyApp
    
    API -->|异步写入| Logger
    Logger -->|持久化| DB

2. 详细数据处理流程

此图展示了一个 Webhook 请求从进入系统到完成分发与记录的完整生命周期。

sequenceDiagram
    participant Ext as 外部系统
    participant API as FastAPI入口
    participant DB as SQLite数据库
    participant Router as 路由服务
    participant Target as 目标系统
    participant Notifier as 通知服务
    participant Channel as IM渠道(飞书/企微)
    participant Log as 日志服务

    Note over Ext, API: 1. 请求接入
    Ext->>API: POST /webhook/{namespace} (Payload)
    
    activate API
    API->>DB: 校验 Namespace 是否有效/启用
    alt Namespace 无效/禁用
        API-->>Ext: 403 Forbidden
    else Namespace 有效
        API->>API: 解析 Payload (remark, event_no, trans_amt...)
        
        par 2. 并行处理 - 转发 (Relay)
            API->>Router: 使用规则引擎匹配路由规则
            Router->>DB: 查询 ProcessingRule/RuleAction/Target
            Router-->>API: 返回目标列表 [Target A, Target B]
            
            loop 对每个目标
                API->>Target: POST /target_url (异步 + 重试机制)
                Target-->>API: 响应 (200 OK / 500 Error)
            end
            
        and 3. 并行处理 - 通知 (Notify)
            API->>Notifier: notify(event_no, payload)
            Notifier->>DB: 查询 ProcessingRule/RuleAction/MessageTemplate/NotificationChannel
            Notifier->>Notifier: 渲染模板 ("【{biz_name}】{pay_method_name} 收款 {trans_amt} 元，状态：{cash_resp_desc}，日期：{trans_date}")
            Notifier-->>API: 返回消息文本 & 渠道列表
            
            loop 对每个渠道
                API->>Channel: POST Webhook (发送消息)
                Channel-->>API: 响应结果
            end
        end

        Note over API, Log: 4. 收尾工作
        API->>Log: BackgroundTask: 保存 RequestLog & DeliveryLog
        Log->>DB: INSERT request_logs, delivery_logs
        
        API-->>Ext: 200 OK (包含 routed/notified 摘要)
    end
    deactivate API

3. 数据库实体关系图 (ERD)

展示了用于支撑上述流程的数据库模型结构。

erDiagram
    WebhookEndpoint {
        int id PK
        string namespace "URL路径标识"
        string description
        bool is_active
        datetime created_at
    }

    ProcessingRule {
        int id PK
        int endpoint_id FK
        int parent_rule_id FK "父规则ID，可为空"
        int priority "优先级，高优先级先匹配"
        string match_field "如 remark / event_define_no"
        string operator "eq/neq/contains/regex"
        string match_value "匹配值"
    }

    RuleAction {
        int id PK
        int rule_id FK
        string action_type "forward/notify"
        int target_id FK "转发目标，可空"
        int channel_id FK "通知渠道，可空"
        int template_id FK "消息模板，可空"
        json template_vars "模板变量，键值对"
    }

    Target {
        int id PK
        string name
        string url
        int timeout_ms
    }

    NotificationChannel {
        int id PK
        string name
        string channel_type "feishu/wecom"
        string webhook_url
    }

    MessageTemplate {
        int id PK
        string name "模板名称"
        text template_content "模板内容"
    }

    RequestLog {
        int id PK
        string namespace
        string remark "来源标识"
        string event_no "事件类型"
        json raw_body "原始数据"
        datetime received_at
        string status "success/error"
    }

    DeliveryLog {
        int id PK
        int request_id FK
        string target_name
        string type "relay/notify"
        string status "success/failed"
        text response_summary
        datetime created_at
    }

    WebhookEndpoint ||--|{ ProcessingRule : "拥有多条规则"
    ProcessingRule ||--|{ ProcessingRule : "树形子规则"
    ProcessingRule ||--|{ RuleAction : "每条规则包含多个动作"
    RuleAction }o--|| Target : "转发到目标"
    RuleAction }o--|| NotificationChannel : "推送到渠道"
    RuleAction }o--|| MessageTemplate : "使用消息模板"
    RequestLog ||--|{ DeliveryLog : "包含多条分发记录"