flowchart TD
    subgraph 外部系统
        BC[区块链网络] 
        UI[用户界面]
        WEB[Web前端服务
web]
        API_GW[API网关]
    end

    subgraph 核心服务
        DEP[充值监听服务\ndeposit-monitor] 
        ADD[地址分配服务\naddress-service] 
        WIT[集中出金服务\nwithdraw-service]
        COL[资金归集服务\ncollection-service]
        MIG[数据迁移服务\nmigrate]
        WEB[Web前端服务\nweb]
    end

    subgraph 基础设施
        DB[(数据库\nPostgreSQL/SQLite)] 
        NATS[NATS JetStream\n事件总线] 
        SIGN[签名服务\n多种签名方案]
    end

    UI -->|访问| WEB
    WEB -->|API请求| API_GW
    API_GW -->|分配地址| ADD
    API_GW -->|发起提现| WIT
    
    DEP -->|监听交易| BC
    WIT -->|发送交易| BC
    COL -->|发送归集交易| BC
    
    DEP -->|写入数据| DB
    ADD -->|写入数据| DB
    WIT -->|写入数据| DB
    COL -->|写入数据| DB
    MIG -->|初始化/迁移数据| DB
    
    DEP -->|发布事件| NATS
    ADD -->|发布/订阅事件| NATS
    WIT -->|订阅/发布事件| NATS
    COL -->|订阅/发布事件| NATS
    
    WIT -->|请求签名| SIGN
    COL -->|请求签名| SIGN
    SIGN -->|返回签名| WIT
    SIGN -->|返回签名| COL
    
    DB -->|读取数据| DEP
    DB -->|读取数据| ADD
    DB -->|读取数据| WIT
    DB -->|读取数据| COL

sequenceDiagram
    participant User as 用户
    participant AddrSvc as 地址服务
    participant DB as 数据库
    participant DepMonitor as 充值监听
    participant Blockchain as 区块链
    participant NATS as 事件总线
    participant API as API服务

    User->>API: 请求充值地址
    API->>AddrSvc: 调用分配地址接口
    AddrSvc->>DB: 查询可用地址
    DB-->>AddrSvc: 返回地址信息
    AddrSvc->>DB: 更新地址状态为已分配
    AddrSvc-->>API: 返回用户充值地址
    API-->>User: 返回充值地址
    
    Note over User,Blockchain: 用户向该地址转账
    
    User->>Blockchain: 发起转账交易
    Blockchain-->>Blockchain: 交易确认
    
    DepMonitor->>Blockchain: 持续监听交易
    Blockchain-->>DepMonitor: 返回新区块/交易
    
    DepMonitor->>DB: 查询地址关联用户
    DB-->>DepMonitor: 返回用户信息
    
    DepMonitor->>DB: 创建/更新交易记录
    DepMonitor->>DB: 更新用户余额
    DepMonitor->>NATS: 发布充值成功事件
    
    NATS-->>API: 推送充值通知
    API-->>User: 通知用户充值完成

sequenceDiagram
    participant User as 用户
    participant API as API服务
    participant DB as 数据库
    participant WithdrawSvc as 提现服务
    participant Signer as 签名器
    participant Blockchain as 区块链
    participant NATS as 事件总线

    User->>API: 提交提现请求
    API->>WithdrawSvc: 调用提现创建接口
    
    WithdrawSvc->>DB: 获取用户账户信息
    DB-->>WithdrawSvc: 返回账户详情
    
    WithdrawSvc->>WithdrawSvc: 验证金额和手续费
    
    alt 余额不足
        WithdrawSvc-->>API: 返回余额不足错误
        API-->>User: 显示余额不足提示
    else 余额充足
        WithdrawSvc->>DB: 开始事务
        
        WithdrawSvc->>DB: 计算并冻结用户资金
        WithdrawSvc->>DB: 创建提现订单(待处理)
        
        alt 事务处理失败
            WithdrawSvc->>DB: 回滚事务
            WithdrawSvc-->>API: 返回处理失败错误
        else 事务处理成功
            WithdrawSvc->>DB: 提交事务
            
            WithdrawSvc->>NATS: 发布提现创建事件
            
            alt 需要人工审核
                WithdrawSvc->>DB: 更新订单状态(待审核)
                Note over WithdrawSvc: 等待审核...
                WithdrawSvc->>DB: 更新订单状态(已审核)
            end
            
            WithdrawSvc->>Signer: 请求交易签名
            Signer-->>WithdrawSvc: 返回签名数据
            
            WithdrawSvc->>Blockchain: 广播交易
            Blockchain-->>WithdrawSvc: 返回交易哈希
            
            WithdrawSvc->>DB: 更新提现订单状态和交易哈希
            WithdrawSvc->>DB: 确认扣除用户余额
            WithdrawSvc->>NATS: 发布提现完成事件
            
            WithdrawSvc-->>API: 返回提现成功
            API-->>User: 显示提现成功信息
        end
    end

flowchart TD
    subgraph 归集任务启动
        A[定时任务触发] -->|配置的归集周期| B[加载归集配置]
        B --> C[获取所有用户地址列表]
    end

    subgraph 余额检查与筛选
        C --> D[并行检查各地址余额]
        D --> E{余额是否大于阈值?}
        E -->|否| F[跳过此地址]
        E -->|是| G[加入待归集地址列表]
    end

    subgraph 归集交易准备
        G --> H[准备归集交易数据]
        H --> I[检查归集主地址状态]
        I --> J[计算最优归集金额]
        J --> K[预估交易手续费]
    end

    subgraph 签名请求与交易广播
        K --> L[向签名服务请求签名]
        L -->|等待签名| M[获取签名数据]
        M --> N[广播交易到区块链]
        N -->|返回交易哈希| O[记录交易哈希]
    end

    subgraph 交易确认与状态更新
        O --> P[等待区块确认]
        P -->|定时检查| Q{交易状态?}
        Q -->|成功| R[更新归集记录为已完成]
        Q -->|失败| S[标记为失败并记录错误]
        Q -->|待定| P
    end

    subgraph 数据更新与通知
        R --> T[更新用户地址余额]
        R --> U[更新主钱包余额]
        S --> V[触发失败告警]
        V --> W[记录重试次数]
        W -->|未达最大重试| X[加入重试队列]
        W -->|已达最大重试| Y[人工介入处理]
        R --> Z[发布归集成功事件]
    end

    X -->|延迟重试| L

sequenceDiagram
    participant Client as 客户端/前端
    participant API as API网关
    participant AddressSvc as 地址服务
    participant DB as 数据库
    participant NATS as 事件总线
    participant Monitor as 充值监控服务

    Client->>API: 请求分配新地址(userId, coinType)
    API->>API: 参数验证
    API->>AddressSvc: 调用地址分配接口
    
    AddressSvc->>DB: 查询用户是否已有该币种地址
    
    alt 用户已有该币种地址
        DB-->>AddressSvc: 返回已存在的地址
        AddressSvc-->>API: 返回已有地址
        API-->>Client: 返回已存在的地址信息
    else 用户尚无该币种地址
        AddressSvc->>DB: 查询地址池中可用地址
        
        alt 地址池中有可用地址
            DB-->>AddressSvc: 返回可用地址
        else 地址池地址不足
            AddressSvc->>AddressSvc: 批量生成新地址
            AddressSvc->>DB: 保存新生成的地址到地址池
            DB-->>AddressSvc: 保存成功
            AddressSvc->>DB: 再次查询可用地址
            DB-->>AddressSvc: 返回可用地址
        end
        
        AddressSvc->>DB: 开始事务
        AddressSvc->>DB: 将地址状态更新为已分配
        AddressSvc->>DB: 创建用户-地址关联记录
        AddressSvc->>DB: 更新地址使用时间
        AddressSvc->>DB: 提交事务
        
        AddressSvc->>NATS: 发布地址分配事件(含用户ID、币种、地址信息)
        NATS-->>Monitor: 通知地址已分配
        Monitor->>Monitor: 更新监听配置，开始监控新地址
        
        AddressSvc-->>API: 返回新分配的地址
        API-->>Client: 返回分配成功及地址详情
    end

    Note over AddressSvc,DB: 定期任务：监控地址池水位，自动补充地址

sequenceDiagram
    participant Blockchain as 区块链网络
    participant Monitor as 充值监控服务
    participant DB as 数据库
    participant NATS as 事件总线
    participant AddressSvc as 地址服务
    participant WalletSvc as 钱包服务

    loop 持续监控新区块
        Blockchain->>Monitor: 新区块产生
        Monitor->>Blockchain: 获取区块头信息
        Monitor->>DB: 检查区块是否已处理
        
        alt 区块未处理
            Monitor->>Blockchain: 获取区块内所有交易
            
            loop 遍历交易
                Monitor->>Monitor: 解析交易详情
                Monitor->>Monitor: 提取转出/转入地址
                
                loop 检查每个转入地址
                    Monitor->>DB: 查询地址是否为系统地址
                    
                    alt 是系统地址
                        DB-->>Monitor: 返回地址关联信息
                        Monitor->>DB: 查询交易是否已存在(防重复)
                        
                        alt 交易不存在
                            Monitor->>DB: 创建待确认充值记录
                            
                            loop 等待达到确认数
                                Monitor->>Blockchain: 检查交易确认数
                                
                                alt 确认数达到阈值
                                    Monitor->>DB: 更新充值记录状态为已确认
                                    Monitor->>DB: 更新用户账户余额
                                    Monitor->>NATS: 发布充值成功事件
                                    
                                    NATS-->>WalletSvc: 通知余额更新
                                    NATS-->>AddressSvc: 通知地址有交易
                                end
                            end
                        end
                    end
                end
                
                Monitor->>DB: 记录区块处理状态
            end
        end
    end