第 5 章 協商機制

5.1 協商原則

DTP 實作 必須 強制執行以下協商原則：

1. 協商先行：任何 Fragment 資料傳輸前，必須 已存在一個狀態為 active 的 Agreement。
2. 無裸傳輸：實作 不得 允許不依賴 Agreement 的資料傳輸。
3. 雙向協商：主端 可 發起資料歸集協商；從端 可 發起資料注入協商。
4. 動態調整：雙方 可 在 Agreement 處於 active 狀態時調整其參數。
5. 明確終止：雙方 可 明確終止 Agreement。終止後 必須 立即停止該約定下的資料傳輸。

5.2 協商訊框類型

協商 必須 透過兩種訊框類型完成：Request_Frame 與 Response_Frame。

5.2.1 Request_Frame

Request_Frame 必須 包含以下欄位：

interface RequestFrame {
  frameType: "request";
  requestId: string;
  requestorRole: "master" | "slave";
  requestType: "collection" | "injection" | "adjustment" | "termination";
  targetAgreementId?: AgreementID;
  proposedParams: AgreementParams;
}

欄位	規範性要求
frameType	必須 為字面量 "request"
requestId	必須 為請求的唯一識別碼。應 使用 UUID v4
requestorRole	必須 為 "master" 或 "slave"，標示請求發起方
requestType	必須 為下表四種類型之一
targetAgreementId	當 requestType 為 "adjustment" 或 "termination" 時 必須 提供
proposedParams	必須 提供完整的 AgreementParams（參見第 5.4 節）

5.2.2 RequestType

值	語義	限制
"collection"	資料歸集請求	必須 由 requestorRole = "master" 發起
"injection"	資料注入申請	必須 由 requestorRole = "slave" 發起
"adjustment"	調整既有約定	必須 提供 targetAgreementId，目標約定 必須 處於 active 狀態
"termination"	終止既有約定	必須 提供 targetAgreementId

實作 必須 拒絕不符合上述限制的請求並返回對應錯誤（參見第 9 章）。

5.2.3 Response_Frame

Response_Frame 必須 包含以下欄位：

interface ResponseFrame {
  frameType: "response";
  requestId: string;
  result: NegotiationResult;
  agreedParams?: AgreementParams;
  agreementId?: AgreementID;
  rejectionReason?: string;
}

欄位	規範性要求
frameType	必須 為字面量 "response"
requestId	必須 為對應 Request_Frame 的 requestId
result	必須 為 NegotiationResult 之一
agreedParams	當 result 為 accepted 或 counter_proposal 時 必須 提供
agreementId	當 result 為 accepted 時 必須 提供，必須 是新產生的 UUID v4
rejectionReason	當 result 為 rejected 時 必須 提供

5.2.4 NegotiationResult

NegotiationResult 必須 是以下三個值之一：

值	語義
"accepted"	接受請求
"rejected"	拒絕請求
"counter_proposal"	提出替代方案

實作 不得 返回未列出的結果值。

5.3 協商流程

5.3.1 資料歸集協商（Master 發起）

資料歸集協商 必須 遵循以下流程：

1. Master 傳送 Request_Frame，requestType = "collection"，requestorRole = "master"。
2. Slave 必須 回覆 Response_Frame，包含以下三種結果之一：
   • "accepted"：同意按 proposedParams 傳輸。必須 在 Response_Frame 中包含新產生的 agreementId。
   • "rejected"：拒絕傳輸。必須 在 rejectionReason 中說明合規性約束（例如 DLP 政策）。不得 因非合規性原因拒絕。
   • "counter_proposal"：提出替代參數。必須 在 agreedParams 中提供修改後的參數。
3. 如 Slave 回覆 counter_proposal，Master 可 傳送新的 Request_Frame 接受、拒絕或繼續協商。
4. Master 必須 持久化記錄 Slave 對每次資料歸集請求的回應結果。

5.3.2 資料注入協商（Slave 發起）

資料注入協商 必須 遵循以下流程：

1. Slave 傳送 Request_Frame，requestType = "injection"，requestorRole = "slave"。
2. Master 必須 回覆 Response_Frame，包含以下三種結果之一：
   • "accepted"：同意提供資料。必須 在 agreedParams 中說明經過濾的資料範圍（最小化資料集）。必須 在 Response_Frame 中包含新產生的 agreementId。
   • "rejected"：拒絕提供資料。應 在 rejectionReason 中說明原因。
   • "counter_proposal"：提供不同範圍或格式的資料。必須 在 agreedParams 中說明替代方案。
3. Master 在資料注入決策中 必須 擁有完全決定權，不得 被強制接受請求。

5.3.3 協商逾時

實作 必須 為 Request_Frame 設定逾時閾值。如在閾值內未收到對端 Response_Frame：

1. 請求方 應 重發 Request_Frame，重試次數 不得 超過實作配置的上限。
2. 重試上限達到後，請求方 必須 終止協商並向上層應用通知 AGREEMENT_NEGOTIATION_FAILED 錯誤（3003）。

5.4 約定參數（AgreementParams）

AgreementParams 必須 包含以下欄位：

interface AgreementParams {
  dataType: string;
  dataRange: string;
  transferMode: TransferMode;
  frequency: number | null;
  validityPeriod: number;
  priority: Priority;
}

欄位	類型	規範性要求
dataType	string	必須 非空。標示資料類型
dataRange	string	必須 非空。描述資料範圍
transferMode	TransferMode	必須 為下表三個值之一
frequency	number | null	單位 Hz。當 transferMode = "one_time" 時 必須 為 null；其他模式時 必須 為正數
validityPeriod	number	單位毫秒。必須 為正整數
priority	Priority	必須 為下表四個值之一

5.4.1 TransferMode

值	語義
"one_time"	一次性傳輸。Agreement 在資料傳輸完成後 應 自動終止
"periodic"	週期性傳輸。必須 設定 frequency
"streaming"	串流傳輸。必須 設定 frequency

5.4.2 Priority

值	語義
"low"	低優先級
"normal"	一般優先級（預設）
"high"	高優先級
"critical"	緊急優先級

實作 應 在多個約定競爭資源時按 priority 排程。

5.5 約定生命週期

5.5.1 狀態定義

AgreementStatus 必須 是以下四個值之一：

狀態	語義
"negotiating"	協商進行中
"active"	約定生效，資料傳輸中
"suspended"	連線中斷，約定暫停
"terminated"	約定終止

5.5.2 狀態轉換

約定狀態 必須 遵循以下轉換規則：

當前狀態	觸發事件	目標狀態
(無)	Request_Frame 發出	negotiating
negotiating	Response_Frame 返回 accepted	active
negotiating	Response_Frame 返回 rejected	(終止)
active	底層連線中斷	suspended
active	收到 termination 類型 Request_Frame	terminated
active	validityPeriod 逾時	terminated
suspended	連線恢復且 CAP 重新驗證通過	active
suspended	持久化逾時	terminated
terminated	(終態)	(無)

5.5.3 一次性約定的自動終止

當 transferMode = "one_time" 且資料傳輸完成時：

1. 傳送方 必須 在最後一個 Fragment 後透過 requestType = "termination" 的 Request_Frame 終止該約定。
2. 接收方 必須 在收到所有 Fragment 並確認後將約定狀態設為 terminated。

5.6 多約定併發

DTP 實作 必須 支援單一會話中同時維護多個 active 狀態的約定。

實作 必須 滿足：

1. 每個 Fragment 透過其 Agreement_ID 關聯到具體約定。
2. 不同約定的 Fragment 可 在傳輸流中交錯。
3. 多約定的實際傳輸方式（串列或並列）取決於 底層 Transport_Adapter 的能力。
4. 實作 不得 限制單一會話中活躍約定的最大數量低於 16。應 支援任意數量。

5.7 旁觀者協商限制

旁觀者（Observer）角色 必須 滿足：

1. 不得 傳送 Request_Frame。如嘗試傳送，DTP_Engine 必須 拒絕該操作並返回 OBSERVER_WRITE_DENIED 錯誤（8002）。
2. 不得 接收任何 Response_Frame 的決策權。
3. 可 接收資料訊框的唯讀副本。
4. 必須 在加入旁觀時由 Controller 顯式授權。