第 3 章 协议架构

3.1 协议分层

DTP 实现 必须 按照以下分层组织：

+-----------------------------------------------+
|           应用层 (Application Layer)           |
|   iFay / coFay / Personal Data Heap            |
|   终端应用                                       |
+-----------------------------------------------+
|           DTP 协议层 (DTP Protocol Layer)       |
|   DTP_Engine (DTP_Master / DTP_Slave)         |
|   - Agreement Manager                          |
|   - Frame Codec                                |
|   - DAG Manager                                |
|   - Encryption Module                          |
|   - Session Manager                            |
|   - Resume Manager                             |
+-----------------------------------------------+
|           适配层 (Adapter Layer)                |
|   Transport_Adapter                            |
+-----------------------------------------------+
|           传输层 (Transport Layer)              |
|   BLE / WebSocket / TCP / RTSP / ...           |
+-----------------------------------------------+

实现 不得 跨层调用（例如，应用层 不得 直接访问适配层接口）。

3.2 核心组件

DTP_Engine 必须 包含以下六个核心组件：

3.2.1 Agreement Manager（协商管理器）

Agreement Manager 必须 提供以下能力：

1. 协商流程管理：处理 Request_Frame 和 Response_Frame 的发送与接收。
2. 约定生命周期管理：维护约定从 negotiating 到 terminated 的状态转换。
3. 唯一标识生成：为每个达成的约定生成符合 RFC 4122 的 UUID v4 作为 Agreement_ID。
4. 多约定并发支持：必须 支持单个会话中同时维护多个活跃约定。

3.2.2 Frame Codec（帧编解码器）

Frame Codec 必须 提供以下能力：

1. 序列化：将 LogicalFrame 对象编码为二进制字节序列。
2. 反序列化：将二进制字节序列解码为 LogicalFrame 对象。
3. 往返一致性：对于任意有效的 LogicalFrame 对象，序列化后再反序列化 必须 产生与原始对象等价的 LogicalFrame。
4. 格式化输出（Pretty Printer）：应 提供将 LogicalFrame 转换为人类可读文本的能力，应 包含帧头中所有关键字段。

3.2.3 DAG Manager（DAG 管理器）

DAG Manager 必须 提供以下能力：

1. 环路检测：在 Fragment 加入 DAG 前 必须 验证不会形成环路。检测到环路时 必须 拒绝该 Fragment 并返回 DAG_CYCLE_DETECTED 错误（4001）。
2. 依赖解析：当 Fragment 声明的依赖目标尚未到达时，必须 将该 Fragment 标记为"依赖待解析"状态并缓存。
3. 延迟解析：当被依赖的 Fragment 到达后，必须 自动解析之前缓存的 Fragment。
4. 关系类型支持：必须 支持 derived_from、annotates、supersedes 三种关系类型。

3.2.4 Encryption Module（加密模块）

Encryption Module 必须 提供以下能力：

1. 载荷加密：使用 CAP 预协商的密钥对 Payload 进行加密。
2. 载荷解密：使用 CAP 预协商的密钥对接收到的 Payload 进行解密。
3. 密钥就绪检查：在加密操作前 必须 验证 CAP 已完成密钥交换。
4. 加密元数据生成：必须 在帧头中以明文形式包含加密元数据（算法标识与密钥版本号）。

3.2.5 Session Manager（会话管理器）

Session Manager 必须 提供以下能力：

1. 会话生命周期管理：建立、维护、关闭会话。
2. 状态持久化：在底层连接中断时 必须 持久化会话状态。
3. 状态恢复：在连接恢复且 CAP 重新验证通过后 必须 能够恢复之前的会话状态。
4. 超时检测：必须 实现会话空闲超时检测。

3.2.6 Resume Manager（续传管理器）

Resume Manager 必须 提供以下能力：

1. 序列号分配：为每个发送的 Fragment 分配单调递增的序列号。
2. 未确认缓存：本地缓存尚未被接收方确认的 Fragment。
3. 断点报告：在连接恢复时向对端报告已成功接收的最高序列号。
4. 缓存管理：必须 实现缓存容量上限检测。当缓存达到上限时 必须 暂停发送并返回 BUFFER_FULL 错误（6001）。

3.3 状态机

DTP_Engine 必须 实现以下状态机：

                 [Idle]
                    |
                    | 收到连接请求
                    v
             [WaitingForCAP]
                    |
                    | CAP 验证 + 密钥交换完成
                    v
             [SessionEstablished]
                    |
                    | 发起或收到 Request_Frame
                    v
              [Negotiating]
                    |
                    | Agreement 达成
                    v
              [Transmitting]
                    |
                    | 连接中断
                    v
                [Suspended]
                    |
                    | 连接恢复 + CAP 重新验证
                    v
                [Resuming]
                    |
                    | 续传握手完成
                    v
              [Transmitting]

完整的状态转换规则 必须 遵循下表：

当前状态	触发事件	目标状态	备注
Idle	收到连接请求	WaitingForCAP
WaitingForCAP	CAP 验证 + 密钥交换完成	SessionEstablished
WaitingForCAP	CAP 失败或超时	Idle	必须 释放相关资源
SessionEstablished	发起或收到 Request_Frame	Negotiating
SessionEstablished	会话超时	Idle	必须 关闭会话
Negotiating	Agreement 达成	Transmitting
Negotiating	协商失败或被拒绝	SessionEstablished
Transmitting	持续传输 Fragment	Transmitting	自循环
Transmitting	收到 adjustment 类型 Request_Frame	Negotiating
Transmitting	底层连接断开	Suspended	必须 持久化会话状态
Transmitting	Agreement 终止且无其他活跃约定	SessionEstablished
Suspended	连接恢复且 CAP 重新验证通过	Resuming
Suspended	会话超时	Idle	必须 释放资源
Resuming	续传握手完成	Transmitting
Resuming	恢复失败	Idle	必须 关闭会话

实现 不得 引入未在上表列出的状态转换。

3.4 Transport_Adapter 接口

Transport_Adapter 必须 提供以下接口：

interface Transport_Adapter {
  // 连接管理
  connect(endpoint: TransportEndpoint): Connection;
  disconnect(connectionId: ConnectionID): void;

  // 数据传输
  send(connectionId: ConnectionID, data: Uint8Array): void;
  onReceive(handler: (connectionId: ConnectionID, data: Uint8Array) => void): void;

  // 状态事件
  onConnectionStateChange(handler: (connectionId: ConnectionID, state: ConnectionState) => void): void;
}

Transport_Adapter 的具体实现 必须 满足以下规范性要求：

1. send() 操作 必须 是非阻塞的。
2. 当底层连接状态发生变化时，必须 通过 onConnectionStateChange 回调通知 DTP_Engine。
3. 必须 为每种支持的传输协议（BLE、WebSocket、TCP、RTSP）提供统一的接口实现。
4. 不得 修改 DTP_Engine 传递的二进制数据。

3.5 主从交互时序

完整的 DTP 交互 必须 遵循以下五个阶段：

阶段 1：CAP 预处理

DTP_Engine 必须 等待 CAP 完成身份验证与密钥交换。在此阶段，DTP 不得 发送任何数据帧。

阶段 2：DTP 会话建立

CAP 完成后，DTP_Engine 必须 生成唯一的 Session_ID（UUID v4）并进入 SessionEstablished 状态。

阶段 3：协商

阶段 3a（数据归集协商）：Master 可 发送 requestType = collection 的 Request_Frame，Slave 必须 通过 Response_Frame 回复 accepted、rejected 或 counter_proposal。

阶段 3b（数据注入协商）：Slave 可 发送 requestType = injection 的 Request_Frame，Master 必须 通过 Response_Frame 回复。

阶段 4：数据传输

Agreement 达成后，发送方 必须 通过数据帧发送 Fragment，每个 Fragment 必须 携带其所属的 Agreement_ID（或省略以继承上下文，参见第 4.5 节）。

阶段 5：连接中断与恢复

底层连接中断时，DTP_Engine 必须 进入 Suspended 状态并持久化会话。连接恢复后，必须 通过 CAP 重新验证，然后进入 Resuming 状态完成续传握手。