# Core 模块架构重构 - 按新版 README（1-91 行）

## 🎯 核心原则

**被多处调用才独立文件，只被一处调用就合并。不制造不必要的目录层级。**

---

## 📁 新的目录结构

```
core/
├── core.go
├── engine.go
├── bind.go
├── metrics.go
│
├── connect/                      # ✅ 建连层：所有和"怎么连"有关的代码
│   ├── strategy.go               # ✅ 9 层策略调度 + 自动切换 + 恢复探测
│   ├── stun.go                   # ⏳ STUN 协议：候选地址采集（被 direct.go 和 ice.go 调用）
│   ├── direct.go                 # ✅ Layer 1: Direct-UDP（调用 stun.go 获取候选，然后打洞）
│   ├── fake_tcp.go               # ✅ Layer 2: FakeTCP
│   ├── real_tcp.go               # ✅ Layer 3: RealTCP
│   ├── turn.go                   # ⏳ Layer 4-6: TURN-UDP/TCP/TLS（TURN 协议协商 + 建连，自包含）
│   ├── turn_quic.go              # ✅ Layer 5: TURN-QUIC（独立文件，私有扩展）
│   ├── ice.go                    # ✅ Layer 7: ICE + WebRTC（调用 stun.go 收集候选）
│   └── ws.go                     # ⏳ Layer 8: WS/WSS（握手 + 帧收发 + 身份标识，自包含）
│
├── transport/                    # ✅ 传输层：用连接转发数据
│   ├── bind_port.go              # ✅ 本地端口 Bind + 路由标识映射表
│   ├── relay.go                  # ✅ Read/Write 循环 + 链路生命周期
│   └── wgparse.go                # ✅ WG 包解析
│
├── pool/                         # ✅ 连接池
│   └── connpool.go               # ✅ 连接池
│
└── proto/                        # ⏳ gRPC 接口定义
    └── core.proto                # ⏳ 待创建
```

---

## ✅ 已完成的重构

### Step 1: 删除 client/ 目录 ✅

**理由**：不制造不必要的目录层级

```
❌ 旧架构：
   connect/ → 调用 → client/stun_client.go
   connect/ → 调用 → client/turn_client.go
   connect/ → 调用 → client/ws_client.go

✅ 新架构：
   connect/stun.go    ← 被 direct.go 和 ice.go 调用
   connect/turn.go    ← 自包含，不需要拆分
   connect/ws.go      ← 自包含，不需要拆分
```

---

## ⏳ 待完成的工作

### 1. 创建 connect/stun.go

**职责**：STUN 协议实现，被多处调用

```go
// connect/stun.go
package connect

// DiscoverAddress 发现外部地址
func DiscoverAddress(stunServer string) (*net.UDPAddr, error)

// CollectCandidates 收集候选地址
func CollectCandidates(servers []string) []string
```

**调用关系**：
- `direct.go` 调用 → 获取候选地址用于打洞
- `ice.go` 调用 → 收集 ICE 候选

---

### 2. 完善 connect/turn.go

**职责**：TURN 协议协商 + 建连，自包含

```go
// connect/turn.go
package connect

// DialTURN TURN 中继连接建立
func DialTURN(server, username, password, network string, peerAddr string) (net.Conn, error) {
    // 内部实现：
    // 1. Allocate Request（申请中继地址）
    // 2. CreatePermission（允许对端发数据）
    // 3. ChannelBind（绑定高效通道）
    // 4. 返回 net.Conn
}
```

**调用关系**：
- 只被 `strategy.go` 调用 → 不需要拆分

---

### 3. 完善 connect/ws.go

**职责**：WS 握手 + 帧收发 + 身份标识，自包含

```go
// connect/ws.go
package connect

// DialWS WebSocket 连接建立
func DialWS(server, path string, useTLS bool, engineID, peerKey string) (net.Conn, error) {
    // 内部实现：
    // 1. Handshake（HTTP Upgrade）
    // 2. Identify（身份标识）
    // 3. Frame Encode/Decode
    // 4. 返回 net.Conn
}
```

**调用关系**：
- 只被 `strategy.go` 调用 → 不需要拆分

---

## 📊 对比两版架构

| 维度 | 旧架构（第 50-79 行） | 新架构（第 1-91 行） | 改进 |
|------|---------------------|---------------------|------|
| **目录层级** | connect/ + client/ | 只有 connect/ | ⭐⭐⭐ 更简洁 |
| **文件组织** | 按"是否返回连接"分离 | 按"是否被多处调用"分离 | ⭐⭐⭐ 更合理 |
| **stun 实现** | `client/stun_client.go` | `connect/stun.go` | ⭐⭐⭐ 更直接 |
| **turn 实现** | `client/turn_client.go` + `connect/turn.go` | 只有 `connect/turn.go` | ⭐⭐⭐ 避免分裂 |
| **ws 实现** | `client/ws_client.go` + `connect/ws.go` | 只有 `connect/ws.go` | ⭐⭐⭐ 避免分裂 |

---

## 🎯 下一步行动

### P0 - 立即执行

1. **从备份恢复或重写 stun.go**
   - 原来的 `client/stun_client.go` 已删除
   - 需要创建 `connect/stun.go`

2. **更新 direct.go**
   - 改为调用新的 `stun.go`

3. **更新 ice.go**
   - 改为调用新的 `stun.go`

### P1 - 后续完善

4. **完善 turn.go** - 添加完整的 TURN 协议实现
5. **完善 ws.go** - 添加完整的 WS 协议实现
6. **创建 proto/core.proto** - gRPC 接口定义

---

*创建时间：2026-03-24 02:00*  
*版本：v2.2.0（基于新版 README 1-91 行）*  
*状态：⏳ 进行中*