WebhockTransfer/docs/webhook-relay/FLOWCHART.md

# Webhook 中继系统流程图

## 1. 系统宏观架构图

```mermaid
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 请求从进入系统到完成分发与记录的完整生命周期。

```mermaid
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)

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

```mermaid
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 : "包含多条分发记录"
```