SPECIFICATION

第 1 章概述與協定定位

本章界定 DTP 的協定範圍（§1.1）、協定定位（§1.2）、與 CAP 的關係（§1.3）、設計目標（§1.4）、主從模型（§1.5）與一致性等級（§1.6），並在 §1.7「版本管理與相容性」中以規範性形式給出 DTP 的版本管理規則——使本協定自帶版本說明，便於標準實作者直接查閱，無需檢索外部文件。

1.1 協定範圍

資料隧道協定（DTP）應當是 iFay 生態系統中負責終端裝置與 Fay 實例之間雙向資料傳輸的應用層協定。

DTP 必須實作以下兩個核心資料流：

資料歸集（Data Collection）：從終端（Slave）流向 Fay（Master），用於將終端產生的資料持久化到 iFay 的 Personal Data Heap。
資料注入（Data Injection）：從 Fay（Master）流向終端（Slave），用於將經 iFay 過濾後的最小化資料集臨時提供給終端應用。

DTP 不得用於其他用途。

1.2 協定定位

DTP 必須作為應用層協定運行於既有傳輸協定之上，包括但不限於 BLE、RTSP、WebSocket、TCP。

DTP 必須透過 Transport_Adapter 抽象層與具體傳輸協定互動（參見第 3.4 節）。DTP 核心不得依賴任何具體傳輸協定的實作細節。

1.3 與 CAP 的關係

DTP 必須與控制授權協定（CAP）協同工作，遵循以下分工：

CAP 負責連線授權、身分驗證與金鑰交換。
DTP 負責協商式資料流傳輸。

DTP 實作必須在 CAP 完成身分驗證與金鑰交換後才開始資料傳輸。如 CAP 尚未就緒，DTP 實作必須拒絕傳送資料並返回 KEY_NOT_READY 錯誤（錯誤碼 2002，參見第 9 章）。

1.4 設計目標

DTP 實作必須滿足以下設計目標：

目標	規範性要求
傳輸無關性	DTP 核心邏輯必須與具體傳輸協定解耦
協商優先	所有資料傳輸必須基於已達成的約定（Agreement）
資料主權	主端必須對資料流擁有最終決策權
端對端加密	負載（Payload）必須加密傳輸
語境保全	每個資料片段必須攜帶結構化上下文中繼資料
可恢復性	實作必須支援基於序列號的續傳機制

1.5 主從模型

DTP 必須區分以下兩種角色：

主端（Master）：自然人使用者或 Fay（iFay / coFay）。必須擁有資料歸集發起權和資料注入決策權。
從端（Slave）：軟體或硬體終端。僅可發起資料注入申請，不得發起資料歸集請求。

DTP 實作必須強制執行以下約束：

在任意時刻，一個從端不得同時被多於一個 Fay 作為控制者（Controller）。
控制者可邀請其他 Fay 作為旁觀者（Observer）。
旁觀者不得發起請求或修改約定，必須只能接收資料流的唯讀副本。
主端發起資料歸集請求時，從端應接受。從端可拒絕，但拒絕必須附帶合規性理由（參見第 5.3.1 節）。
從端發起資料注入申請時，主端必須擁有完全決定權，可接受、拒絕或提出替代方案。

1.6 一致性等級

實作必須宣告其一致性等級：

完整一致（Full Conformance）：實作滿足所有 必須（MUST） 與 應（SHOULD） 規則。
核心一致（Core Conformance）：實作滿足所有 必須（MUST） 規則，但可不滿足部分 應（SHOULD） 規則。
不一致（Non-Conformance）：實作不滿足某條 必須（MUST） 規則。宣告為 DTP 的實作不得處於此狀態。

1.7 版本管理與相容性（Version Management & Compatibility）

本節為規範性（Normative）。 本節是 DTP 版本管理規則的唯一權威來源（Single Source of Truth）。正文其他位置（含第 10 章「版本管理」與變更日誌，如有）凡涉及版本規則之處，必須以本節為準，不得重新定義本節已規定的規則。

本節按以下固定順序組織：三條正交版本軸（§1.7.1）→ MAJOR.MINOR 語義與變更判定（§1.7.2）→ 版本協商與相容性規則（§1.7.3）→ 編輯版次與勘誤（§1.7.4）→ 版本號落地表與實作者須知（§1.7.5）。

1.7.1 三條正交版本軸

DTP 的版本資訊必須沿三條相互正交的軸獨立管理。這三條軸不得合併為單一版本號；每條軸擁有獨立的取值空間、記錄位置與演進規則，且一條軸的變更不得強制另外兩條軸隨之變更（正交性的可觀測定義）。

軸	含義	取值空間	記錄位置	進入線格式？
協定版本（Protocol Version）	互通契約	`dtp/MAJOR.MINOR`（兩級、無 PATCH；`MAJOR`、`MINOR` 均為非負整數）	訊框標頭 `protocolVersion` 欄位、schema 檔名	是
文件狀態（Document Status）	文件生命週期	列舉 `Draft / Final / Deprecated / Obsolete`（任一時刻恰取一個值）	front matter 的 `status` 欄位	否
編輯版次（Editorial Edition）	勘誤與澄清	以發布日期錨定的 `YYYY-MM-DD`（如 `2025-10-25`）	front matter 的 `date` 欄位與發布目錄名	否

關於文件狀態與目錄的關鍵約束（完整目錄約定與定稿治理流程見第 10 章，其規則錨點以本節為準）：

文件狀態必須是 front matter 標記，不得編碼進檔案路徑或目錄名。
某個已發布版次當前是 Final 還是 Deprecated / Obsolete，僅由其檔案的 status 欄位決定，不得依據目錄名判斷。

1.7.2 `MAJOR.MINOR` 語義與變更判定

MAJOR（主版本）

MAJOR 用於破壞互通的變更。判定基準：若一個嚴格按 MAJOR.0 舊版實作的對端會拒絕或誤解新報文，則該變更為破壞互通變更。此類變更包括但不限於：

變更權威 schema 欄位的語義；
移除報文或錯誤碼；
重定義錯誤碼；
變更狀態機的吸收態（absorbing state）。

WHEN 發生一次破壞互通的變更，MAJOR 必須遞增 1，且 MINOR 必須歸零（重置為 0）。

不同 MAJOR 之間不保證互通。

MINOR（次版本）

MINOR 用於向後相容的增補，包括但不限於：新增可選欄位、新增報文、新增錯誤碼、新增參數、新增屬性。判定基準：嚴格按 MAJOR.0 舊版實作的對端既不會拒絕、也不會誤解新報文。

WHEN 發生一次向後相容的增補，MINOR 必須遞增 1，MAJOR 必須保持不變。在同一 MAJOR 內，較高 MINOR 必須向後相容至 MAJOR.0。

變更判定規則（有序、可判定）

對任一變更，必須按以下順序判定其落點，產出唯一檔位：

若嚴格實作 MAJOR.0 舊版的對端會拒絕或誤解新報文 → 判定為 MAJOR；
否則，若該變更新增了線格式可見內容（訊框標頭/報文/錯誤碼/參數等線上可見結構）→ 判定為 MINOR；
否則（僅文字變更、無線格式變化）→ 不變更協定版本，改用編輯版次（見 §1.7.4）。
若一處變更可同時匹配多個檔位，必須取較高檔位。

1.7.3 版本協商與相容性規則

本小節為規範性。

線格式約束

僅協定版本的 MAJOR.MINOR 進入線格式（即訊框標頭 protocolVersion 欄位與 schema 檔名）。
協定版本必須始終進入線格式；實作不得提供將協定版本排除出線格式的設定。
文件狀態與編輯版次不得進入線格式。實作不得依據文件狀態或編輯版次改變報文處理行為——即：線格式完全相同的兩條訊息，其處理結果不得因這兩條軸取值不同而產生差異。
IF 接收到的訊息在線格式中缺失協定版本資訊（訊框標頭缺少 protocolVersion，或缺少 major / minor 子欄位，或其值非非負整數），THEN 實作必須以協定錯誤拒絕該訊息，且不得以預設或推斷版本進行處理。

協商規則

WHEN 進行握手或引導（bootstrap），雙方必須各自宣告其支援的協定版本集合，該集合不得為空。
版本選擇必須遵循：先取雙方共同支援的最高 MAJOR，再取該 MAJOR 下雙方共同支援的最高 MINOR。
較高 MINOR 的一方必須能夠服務較低 MINOR 的對端：必須按對端宣告的較低版本語義處理其報文，不得僅因對端 MINOR 較低而拒絕。
IF 雙方不存在任何共同支援的 MAJOR，THEN 實作必須直接以協定錯誤拒絕，且不得進行盡力而為（best-effort）的降級。（該錯誤的具體綁定見第 10 章 VERSION_INCOMPATIBLE / 7001。）
WHEN 接收到 MAJOR 相同但 MINOR 更高的報文，實作必須以自身最高 MINOR 的語義解讀已知欄位並忽略不識別的可選欄位，不得拒絕、丟棄或報錯。

憑證與密碼套件

WHEN 進行版本滾動升級，實作必須保持既有的、未過期的憑證或權杖（credentials / tokens）繼續有效，不得僅因版本變更而使其失效。
WHERE 協定已具備密碼套件（cipher-suite）協商機制，版本協商必須複用同一口徑（各自宣告、取共同最高）。

協商時序（Hello / Hello_Ack）與「會話內版本一致、不得中途切換」的操作機制見第 10 章。

1.7.4 編輯版次與勘誤

本小節描述的約束為**非規範性（Non-normative）**治理約束，但其「不得偽裝升級」一條對協定版本號的正確性具有約束力。

WHEN 定稿後進行純文字勘誤（訂正錯字、補充範例、澄清表述、修復連結），必須保持協定版本號（MAJOR.MINOR）不變；該勘誤必須由一個新的發布日期目錄承載，既有的已發布目錄必須保持凍結，從而舊引用與連結不得被破壞。
編輯版次應在變更日誌（如有）中以 Editorial 類目登記；front matter 必須以 edition / date 欄位標註其版次。
編輯版次僅允許非規範性改動，不得觸及線格式語義、規範性陳述、錯誤碼、狀態機或互通行為。
硬約束：IF 一項修改觸及線格式語義，THEN 必須按 §1.7.2 遞增 MINOR 或 MAJOR，且不得將其偽裝為勘誤（編輯版次）發布。

1.7.5 版本號落地表與實作者須知

落地表

落點	放什麼	規範性約束
線信封 `protocolVersion` 欄位	`MAJOR.MINOR`	僅放 `MAJOR.MINOR`，不含其他級別
schema 檔名	跟隨 `MAJOR.MINOR`	不得隨編輯版次重新命名（保持引用穩定）
content-type	`application/dtp`	標識協定族；其 `version=` 參數僅作閘道路由便利，不屬於線格式語義
front matter `status` / `date`	文件治理標記	不進入線格式
git tag	`dtp-v<MAJOR.MINOR>-<狀態>`	tag 必須同時涵蓋正文 + 測試向量 + schema

實作者須知（必讀）

判斷互通只看協定版本（MAJOR.MINOR），不得依據文件狀態或編輯版次。
同一 MAJOR 必須向下相容至 MAJOR.0。
不得把勘誤（編輯版次）當作協定升級。
不得依賴 schema 檔名來編碼編輯版次。
Draft 期間無相容性承諾。

完整的目錄與狀態約定、以及定稿（Draft → Final）的標準動作見第 10 章「協定演進與治理」；其中涉及的 git tag 格式、狀態列舉與編輯版次定義，必須以本節（§1.7）為規則錨點。

第 1 章 概述與協定定位