SPECIFICATION

第 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 必須提供以下能力：

協商流程管理：處理 Request_Frame 和 Response_Frame 的傳送與接收。
約定生命週期管理：維護約定從 negotiating 到 terminated 的狀態轉換。
唯一識別碼產生：為每個達成的約定產生符合 RFC 4122 的 UUID v4 作為 Agreement_ID。
多約定併發支援：必須支援單一會話中同時維護多個活躍約定。

3.2.2 Frame Codec（訊框編解碼器）

Frame Codec 必須提供以下能力：

序列化：將 LogicalFrame 物件編碼為二進位位元組序列。
反序列化：將二進位位元組序列解碼為 LogicalFrame 物件。
往返一致性：對於任意有效的 LogicalFrame 物件，序列化後再反序列化必須產生與原始物件等價的 LogicalFrame。
格式化輸出（Pretty Printer）：應提供將 LogicalFrame 轉換為人類可讀文字的能力，應包含訊框標頭中所有關鍵欄位。

3.2.3 DAG Manager（DAG 管理器）

DAG Manager 必須提供以下能力：

環路偵測：在 Fragment 加入 DAG 前必須驗證不會形成環路。偵測到環路時必須拒絕該 Fragment 並返回 DAG_CYCLE_DETECTED 錯誤（4001）。
依賴解析：當 Fragment 宣告的依賴目標尚未到達時，必須將該 Fragment 標記為「依賴待解析」狀態並快取。
延遲解析：當被依賴的 Fragment 到達後，必須自動解析之前快取的 Fragment。
關係類型支援：必須支援 derived_from、annotates、supersedes 三種關係類型。

3.2.4 Encryption Module（加密模組）

Encryption Module 必須提供以下能力：

負載加密：使用 CAP 預協商的金鑰對 Payload 進行加密。
負載解密：使用 CAP 預協商的金鑰對接收到的 Payload 進行解密。
金鑰就緒檢查：在加密操作前必須驗證 CAP 已完成金鑰交換。
加密中繼資料產生：必須在訊框標頭中以明文形式包含加密中繼資料（演算法識別與金鑰版本號）。

3.2.5 Session Manager（會話管理器）

Session Manager 必須提供以下能力：

會話生命週期管理：建立、維護、關閉會話。
狀態持久化：在底層連線中斷時必須持久化會話狀態。
狀態恢復：在連線恢復且 CAP 重新驗證通過後必須能夠恢復之前的會話狀態。
逾時偵測：必須實現會話閒置逾時偵測。

3.2.6 Resume Manager（續傳管理器）

Resume Manager 必須提供以下能力：

序列號分配：為每個傳送的 Fragment 分配單調遞增的序列號。
未確認快取：本地快取尚未被接收方確認的 Fragment。
中斷點回報：在連線恢復時向對端回報已成功接收的最高序列號。
快取管理：必須實現快取容量上限偵測。當快取達到上限時必須暫停傳送並返回 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 的具體實作必須滿足以下規範性要求：

send() 操作必須是非阻塞的。
當底層連線狀態發生變化時，必須透過 onConnectionStateChange 回呼通知 DTP_Engine。
必須為每種支援的傳輸協定（BLE、WebSocket、TCP、RTSP）提供統一的介面實作。
不得修改 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 狀態完成續傳交握。

第 3 章 協定架構