# Core 模块分层架构与文件组织规范

## 🎯 职责分工

### `connect/` - 连接工厂层（对外建立连接）

**职责**：**对外**与 Peer 建立各种类型的网络连接，返回标准的 `net.Conn` 接口。

**关键特性**：
- 实现 **9 层降级传输策略**
- 每层独立的连接工厂（Factory）
- 所有工厂实现统一的 `TransportFactory` 接口
- 通过 `StrategyScheduler` 管理优先级和自动降级

**文件组织**（9 个独立工厂）：
```
connect/
├── strategy.go           # 策略调度器（核心）
│   ├── StrategyScheduler    # 管理 9 层工厂的优先级
│   ├── TransportFactory     # 统一接口：Dial() net.Conn
│   └── Layer                # 9 层枚举
│
├── ice.go                # ICE 协商（辅助功能）
│
├── direct_udp.go         # Direct-UDP 工厂 ⏳ 待从 fake_tcp.go 拆分
├── fake_tcp.go           # Direct-FakeTCP 工厂 ✅
├── real_tcp.go           # Direct-RealTCP 工厂 ✅
│
├── turn_udp.go           # TURN-UDP 工厂 ✅ (已重命名)
├── turn_tcp.go           # TURN-TCP 工厂 ⏳ 待从 turn_udp.go 拆分
├── turn_tls.go           # TURN-TLS 工厂 ⏳ 待从 turn_udp.go 拆分
├── turn_quic.go          # TURN-QUIC 工厂 ✅
│
├── webrtc.go             # WebRTC 工厂 ⏳ 待创建
└── ws.go                 # WS/WSS 工厂 ✅ (已重命名)
```

**为什么叫 `connect`**：
- 词源：**Connect to peer**（连接到对端）
- 职责：**建立**网络连接
- 抽象层次：网络层（Network Layer）+ 传输层（Transport Layer）

---

### `transport/` - 传输绑定层（对内对接 WireGuard）

**职责**：**对内**将建立的连接暴露给 WireGuard 使用，实现 `conn.Bind` 接口。

**关键特性**：
- 不关心具体的建连方式（UDP/TCP/TURN）
- 只使用 `net.Conn` 接口
- 负责 WireGuard 数据包的 Read/Write
- 管理 Peer 连接的生命周期

**文件组织**（2 个核心组件）：
```
transport/
├── core_bind.go          # WireGuard Bind 实现
│   └── CoreBind             # 实现 conn.Bind 接口
│       ├── Write(buffers)     # 写入 WireGuard 数据包
│       ├── Read(buffer)       # 读取 WireGuard 数据包
│       └── Dial(peerID)       # 使用 connect.Scheduler 建连
│
└── relay.go              # 数据中继器
    └── Relay                # 基于 net.Conn 的透明转发
        ├── RegisterFactory()  # 注册传输工厂
        ├── GetConnection()    # 获取已建立的连接
        └── Forward()          # 透明读写转发
```

**为什么叫 `transport`**：
- 词源：**Transport WireGuard packets**（传输 WireGuard 数据包）
- 职责：**传输**应用层数据（WireGuard 密文）
- 抽象层次：绑定层（Bind Layer）- WireGuard 专有概念

---

## 📊 完整数据流

```
[WireGuard 内核态]
    ↓ Write(buffers, size, offset)
    ↓ "发送加密数据包"
    
[transport/CoreBind]
    ↓ 检查是否有 Peer 的连接
    ↓ 如果没有 → 调用 Scheduler.Dial()
    ↓ 如果有 → 直接使用现有 net.Conn
    ↓ conn.Write(packet)
    
[connect/StrategyScheduler]
    ↓ 按优先级尝试 9 层工厂
    ↓ Layer1: Direct-UDP.Dial()
    ↓ 失败 → Layer2: FakeTCP.Dial()
    ↓ 失败 → Layer3: RealTCP.Dial()
    ↓ ...
    ↓ 成功 → 返回 net.Conn
    
[底层网络 Socket]
    ↓ UDP Socket.Send()
    ↓ TCP Socket.Connect() + Send()
    ↓ TURN Server.Allocate() + Send()
```

---

## 🔧 当前状态 vs 目标状态

### Connect 目录（连接工厂层）

| 当前文件 | 目标文件名 | 状态 | 说明 |
|---------|-----------|------|------|
| `strategy.go` | `strategy.go` | ✅ | 策略调度器 |
| `ice.go` | `ice.go` | ✅ | ICE 协商 |
| `fake_tcp.go` | `direct_udp.go` | 🔄 | 需要拆分出 Direct-UDP |
| `fake_tcp_factory.go` | 合并到 `fake_tcp.go` | 🔄 | 空文件，可删除 |
| `real_tcp.go` | `real_tcp.go` | ✅ | RealTCP |
| `real_tcp_factory.go` | 合并到 `real_tcp.go` | 🔄 | 空文件，可删除 |
| `turn_udp.go` | `turn_udp.go` | ✅ | 已重命名 |
| `turn_tcp.go` | `turn_tcp.go` | ⏳ | 待从 turn_udp.go 拆分 |
| `turn_tls.go` | `turn_tls.go` | ⏳ | 待从 turn_udp.go 拆分 |
| `turn_quic.go` | `turn_quic.go` | ✅ | QUIC 扩展 |
| `webrtc.go` | `webrtc.go` | ⏳ | 待创建 |
| `ws.go` | `ws.go` | ✅ | 已重命名 |
| `stun.go` | `stun.go` | ✅ | STUN 探测（辅助） |

### Transport 目录（传输绑定层）

| 当前文件 | 目标文件名 | 状态 | 说明 |
|---------|-----------|------|------|
| `core_bind.go` | `core_bind.go` | ✅ | WireGuard Bind |
| `relay.go` | `relay.go` | ✅ | 数据中继 |
| ~~`intercept.go`~~ | ❌ 已删除 | ✅ | 废弃（被 CoreBind 替代） |

---

## ✅ 重构原则

### 1. 保持 9 层独立性
- ❌ **不要合并**不同层的工厂（如 P2P 工厂）
- ✅ **每层对应一个文件**（如 `turn_udp.go`, `turn_tcp.go`）
- ✅ **每层实现统一的接口**（`TransportFactory`）

### 2. 文件名语义化
- ✅ `{layer}.go` - 直接体现传输层类型
- ✅ `{layer}_factory.go` - 强调工厂模式（可选）
- ❌ 避免模糊的名称（如 `p2p_factory.go` 包含 3 层）

### 3. 职责分离
- ✅ `connect/` 负责**建立**连接（Dial）
- ✅ `transport/` 负责**使用**连接（Read/Write）
- ❌ 不要混淆两者的边界

---

## 📝 下一步行动

### Phase 1: 清理空文件
```bash
rm core/connect/fake_tcp_factory.go
rm core/connect/real_tcp_factory.go
```

### Phase 2: 拆分 TURN 工厂
- 从 `turn_udp.go` 中拆分出：
  - `turn_tcp.go` - TURN-TCP 工厂
  - `turn_tls.go` - TURN-TLS 工厂

### Phase 3: 补充缺失的层
- 创建 `direct_udp.go` - Direct-UDP 工厂
- 创建 `webrtc.go` - WebRTC 工厂

### Phase 4: 验证编译
```bash
go build ./cmd/meshray
```

---

*创建时间：2026-03-20*  
*版本：v2.1.0*  
*架构原则：connect 管建连，transport 管传输*