flowchart LR
    A[Alice] --> E["入口节点 (Entry)"] --> M["中间节点 (Middle)"] --> X["出口节点 (Exit)"] --> B[Bob]

flowchart LR
    A[Alice] -->|C1| E[Entry<br/>解密: 下一站 Middle] -->|C2| M[Middle<br/>解密: 下一站 Exit] -->|C3| X[Exit<br/>解密: 真实数据] -->|明文| B[Bob]

flowchart TB
    subgraph 公网服务层
        DS[Directory Server<br/>目录服务：发布可信节点]
        SS[Signaling Server<br/>信令服务：NAT 信息交换]
        RS[Relay Server<br/>中继服务：UDP 洋葱转发]
    end

    subgraph Android 客户端
        AC[App 业务层]
        CM[Connection Manager<br/>管理 Circuits / Peers]
        OC[Onion Core<br/>分层加密 / 解密]
        NC[Network Core<br/>UDP Socket / NAT / ICE]
    end

    subgraph 对端
        P2P[Peer B<br/>Android / Server / IoT]
    end

    AC --> CM
    CM --> OC
    CM --> NC
    OC --> NC
    NC -->|UDP| RS
    NC -->|UDP| SS
    NC -.->|查询节点列表| DS
    NC -.->|P2P 直连或中继| P2P

sequenceDiagram
    participant C as Android Client
    participant D as Directory Server
    participant N1 as Node Entry
    participant N2 as Node Middle
    participant N3 as Node Exit

    C->>D: HTTPS GET /nodes?count=3&flags=entry|middle|exit
    D-->>C: 返回节点列表 + 签名
    C->>C: 验证签名、选择路径
    C->>N1: UDP 建立 Circuit 请求
    N1-->>C: 返回 Circuit ID
    C->>N1: 经过 N1 转发到 N2 建立
    N2-->>C: 返回确认
    C->>N2: 经过 N1→N2 转发到 N3 建立
    N3-->>C: 返回确认

flowchart TD
    A[收到 UDP 报文] --> B{报文格式合法?}
    B -->|否| C[直接丢弃]
    B -->|是| D[查找 circuit_id]
    D --> E{存在?}
    E -->|否| C
    E -->|是| F[用 shared_key 解密洋葱层]
    F --> G{解密成功?}
    G -->|否| C
    G -->|是| H[读取下一跳地址 + 内层数据]
    H --> I[TTL - 1]
    I --> J{TTL > 0?}
    J -->|否| K[发送销毁通知]
    J -->|是| L[转发给下一跳]

sequenceDiagram
    participant A as Peer A
    participant S as Signaling Server
    participant B as Peer B

    A->>S: 注册/上报 PeerInfo（UDP 心跳包）
    B->>S: 注册/上报 PeerInfo

    A->>S: 请求连接 peer_B
    S->>S: 检查 A、B 是否在线
    S-->>A: 返回 B 的候选地址列表
    S-->>B: 转发 A 的连接请求 + A 的候选地址

    A->>A: 按优先级尝试直连 / 打洞
    B->>B: 同时尝试直连 / 打洞
    A-->>B: UDP 打洞成功，建立 P2P
    B-->>A: 业务数据互通

    alt 打洞失败
        A->>S: 请求中继
        S-->>A: 分配 Relay 地址
        S-->>B: 通知 B 通过 Relay 通信
        A->>R: 经中继与 B 通信
    end

flowchart TB
    subgraph 应用层
        UI[UI / ViewModel]
        API[业务 API]
    end

    subgraph 网络中间层
        CM[ConnectionManager<br/>管理多 Circuit / 多 Peer]
        P2P[P2PController<br/>打洞 / 直连 / 中继决策]
        SM[SignalingClient<br/>与信令服务通信]
    end

    subgraph 核心引擎层
        OC[OnionCore<br/>加密 / 解密 / 报文封装]
        NC[NetworkCore<br/>UDP Socket / ICE / STUN]
        CR[CircuitStore<br/>持久化 Circuit 状态]
    end

    UI --> API
    API --> CM
    CM --> P2P
    CM --> SM
    CM --> OC
    P2P --> OC
    P2P --> NC
    SM --> NC
    OC --> NC
    CM --> CR

flowchart LR
    subgraph 网络线程
        RT[ReceiveThread<br/>阻塞 recvFrom]
        RT -->|Raw Packet| DP[DecoderPipeline<br/>STUN / 洋葱 / 业务]
        DP -->|业务消息| MQ[MessageQueue]
        DP -->|信令响应| SR[SignalingResponseMap]
    end

    subgraph 发送线程
        SQ[SendQueue<br/>优先级队列]
        ST[SendThread<br/>定时 flush]
        SQ --> ST -->|sendTo| Socket
    end

    subgraph 业务线程
        BH[BusinessHandler]
        MQ --> BH
    end

    Socket --> RT

flowchart TD
    A[开始探测] --> B[STUN A 请求]
    B --> C[得到 M1]
    C --> D[STUN B 请求]
    D --> E[得到 M2]
    E --> F{M1 == M2?}
    F -->|是| G[全锥 / 限制 / 端口限制]
    F -->|否| H[对称型 NAT]
    G --> I[进一步测试过滤规则]
    H --> J[P2P 大概率失败<br/>优先准备 Relay]

flowchart TD
    A[Peer A 想连 Peer B] --> B[通过信令服务获取 B 的候选地址]
    B --> C{尝试直连}
    C -->|成功| D[UDP P2P 直连]
    C -->|失败| E{尝试 NAT 打洞}
    E -->|成功| D
    E -->|失败| F[通过 Relay 中继]
    D --> G[业务通信]
    F --> G

graph LR
    A[直连候选<br/>局域网 IP] -->|优先级最高| B[srflx 候选<br/>STUN 映射公网地址]
    B -->|次高| C[prflx 候选<br/>对端看到的地址]
    C -->|再次| D[relay 候选<br/>TURN/中继服务器]

sequenceDiagram
    participant A as Peer A
    participant SA as STUN/Signaling Server
    participant B as Peer B

    A->>SA: 注册：我的 srflx 是 1.1.1.1:10000
    B->>SA: 注册：我的 srflx 是 2.2.2.2:20000

    A->>SA: 请求连接 B
    SA-->>A: 返回 B 的地址 2.2.2.2:20000
    SA-->>B: 转发 A 的地址 1.1.1.1:10000

    A->>B: 发送 UDP 打洞包（可能到达或被过滤）
    B->>A: 发送 UDP 打洞包
    Note over A,B: 双方都先发包，让各自 NAT 建立映射

    A->>B: 收到 B 的包，回确认
    B->>A: 收到 A 的包，回确认
    Note over A,B: 打洞成功，后续直接通信

flowchart LR
    A[Alice] -->|洋葱隧道| X[出口节点] --> S[信令服务器]
    B[Bob] -->|洋葱隧道| X

sequenceDiagram
    participant A as Peer A
    participant S as Signaling Server（洋葱保护下）
    participant B as Peer B

    A->>S: 发送 X25519 公钥 PA
    S->>B: 转发 PA
    B->>S: 发送 X25519 公钥 PB
    S->>A: 转发 PB

    A->>A: ECDH 计算共享密钥 K
    B->>B: ECDH 计算共享密钥 K

    A->>B: 用 K 加密业务数据，UDP P2P 直连发送
    B->>A: 用 K 加密业务数据，UDP P2P 直连发送

flowchart TD
    A[发送消息] --> B[分配 Seq]
    B --> C[加入重传队列]
    C --> D[UDP 发送]
    D --> E{收到 ACK?}
    E -->|是| F[从队列移除]
    E -->|否| G{超时?}
    G -->|否| E
    G -->|是| H[重传 N 次]
    H --> I{达到最大重试?}
    I -->|否| C
    I -->|是| J[通知上层失败]

stateDiagram-v2
    [*] --> Idle: 用户发起连接
    Idle --> Gathering: 收集 ICE 候选
    Gathering --> Connecting: 开始打洞/直连
    Connecting --> Connected: 收到对端包
    Connecting --> Relaying: 打洞失败，切中继
    Relaying --> Connected: 中继链路建立
    Connected --> Disconnected: 超时未收到心跳
    Disconnected --> [*]

sequenceDiagram
    participant A as Android Alice
    participant D as Directory Server
    participant S as Signaling Server
    participant R as Relay Server
    participant B as Android Bob

    %% 阶段 1：准备节点
    A->>D: HTTPS 获取节点列表
    D-->>A: 返回 Entry/Middle/Exit + 签名
    A->>A: 校验签名，选择路径
    A->>Entry: UDP CREATE Circuit
    Entry-->>A: CREATED
    A->>Middle: 经 Entry 转发 CREATE
    Middle-->>A: CREATED
    A->>Exit: 经 Entry→Middle 转发 CREATE
    Exit-->>A: CREATED

    %% 阶段 2：注册信令
    A->>S: 经洋葱隧道 REGISTER Alice
    B->>S: 经洋葱隧道 REGISTER Bob

    %% 阶段 3：发起 P2P
    A->>S: OFFER（请求连接 Bob）
    S->>B: 转发 OFFER + Alice 候选地址
    B->>S: ANSWER + Bob 候选地址
    S->>A: 转发 ANSWER

    %% 阶段 4：打洞
    A->>B: UDP 打洞包
    B->>A: UDP 打洞包
    A-->>B: 直连成功

    %% 阶段 5：业务通信
    A->>B: 端到端加密业务数据
    B->>A: 端到端加密业务数据

    %% 阶段 6：失败兜底
    alt 打洞失败
        A->>S: 请求 Relay
        S-->>A: 分配 Relay 地址
        S-->>B: 通知走 Relay
        A->>R: 经洋葱→Relay→Bob
    end

flowchart TB
    A[UDP 洋葱网络 + P2P] --> B[目录服务<br/>给节点]
    A --> C[信令服务<br/>撮合 Peer]
    A --> D[中继服务<br/>兜底转发]
    A --> E[Android 客户端<br/>洋葱 + NAT + P2P]
    E --> F[OnionCore<br/>逐跳加密]
    E --> G[NetworkCore<br/>UDP / STUN / ICE]
    E --> H[P2PController<br/>直连 / 打洞 / 中继]
    F --> I[隐私保护]
    G --> J[NAT 穿透]
    H --> K[去中心化通信]
    A --> L[避坑：可靠传输 / 端到端加密 / 后台保活]