# 品牌 App 條款攔截串接規格（Android／iOS）

- 文件類型：技術規格，交接給品牌 App 的 Android、iOS 工程師
- 版本：2026-10-17
- 適用 App：品牌 App Android 版（平台代碼 `studio-android`）、iOS 版（平台代碼 `studio-ios`）
- 本文件已依 17FIT 現行實作校對；若與其他舊版說明不一致，以本文件為準
- 標「暫定」的項目以 17FIT 後端正式通知為準

## 摘要

品牌可以要求會員簽署條款（合約或問卷）。App 要做兩件事：

(1) **強制條款攔截**：會員登入後，只要還有未完成的強制條款，進入任何頁面時 App 就開一個全螢幕 WebView，載入 17FIT 條款服務讓會員填寫。條款服務在會員全部完成後導向 App 指定的 `back_url`，App 攔下這個導向、關閉 WebView、重新查詢。

(2) **提示條款紅點**：「我的帳戶」頁顯示未完成提示條款的數量，點擊後用同一個 WebView 開條款列表。

App 會用到三支 17FIT API 與一個條款服務網址：

| 用途 | 呼叫 | 狀態 |
|---|---|---|
| 查紅點數字 | `GET /appapi/v1.0.0/approval-term/prompt/status/warn` | 已上線 |
| 查中斷表 | `GET /appapi/v1.0.0/approval-term/prompt/break-points` | 已上線 |
| 取開啟條款服務用的 token | `GET /appapi/v1.0.0/approval-term/member-token`（暫定） | **尚未提供，開工前由 17FIT 後端補上** |
| 開啟條款服務 | WebView `POST https://approve.17fit.com/auth` | 已上線 |

條款的列表、填寫、送出畫面全部由條款服務提供，App 不需要做任何條款 UI。

## 術語

| 詞 | 定義 |
|---|---|
| 品牌 App | 17FIT 為單一品牌打包的原生 App |
| studio_id | 品牌的數字 id。App 本來就知道自己屬於哪個品牌 |
| 條款 | 品牌要求會員同意的合約或問卷 |
| 強制條款（break） | 未完成就不能繼續使用 App 的條款。API 中以 `approval_prompt_level = "break"` 表示 |
| 提示條款（warn） | 只提醒、不阻擋的條款。API 中以 `level = warn` 查詢 |
| User Flow | 一種會被攔截的操作情境，以字串 id 識別。目前只有 `any-pages`（登入後任何頁面） |
| 中斷點（Break Point） | 某個 User Flow 在某個平台上的攔截位置，以「頁面類別名稱的正規表達式」描述 |
| 中斷表 | 中斷表 API 回傳的陣列。App 下載後在本機逐頁比對 |
| 條款服務（ApproveTerm） | 17FIT 提供條款頁面的 Web 服務，正式環境網域 `approve.17fit.com` |
| member_token | 開啟條款服務用的一次性 token，由 17FIT API 簽發，有效 60 秒 |
| 攔截守門員 | 本文件建議 App 實作的單例元件（建議類別名 `ApprovalBreakGuard`），負責保存中斷表、比對頁面、開關 WebView |
| 條款 WebView | App 內承載條款服務頁面的全螢幕 WebView 畫面 |
| back_url | App 指定的「完成」網址。條款服務導向它時，代表 App 應關閉 WebView |
| error_url | App 指定的「開啟失敗」網址。條款服務導向它時會附加錯誤參數 |

## 功能概念 (C01)

| 條款種類 | 何時影響會員 | App 行為 | 會員能否略過 |
|---|---|---|---|
| 強制條款（break） | 登入後進入任何被中斷點命中的頁面 | 開全螢幕條款 WebView，關閉前不能操作底下的頁面 | 不能 |
| 提示條款（warn） | 打開「我的帳戶」頁 | 「合約或問卷」項目顯示紅點與數字；點擊開條款 WebView | 能 |

分工：

| 角色 | 負責 |
|---|---|
| 品牌 App | 查中斷表、比對頁面、取 member_token、開關條款 WebView、顯示紅點 |
| 17FIT API | 回傳未完成數量、中斷表、member_token |
| 條款服務 | 條款列表、填寫、送出、記錄完成；完成後導向 back_url |
| 品牌後台 | 決定哪份條款是強制或提示（App 不參與） |

不在本文件範圍：條款 UI、品牌後台設定、電子簽名、其他 17FIT App。

## 整體流程 (C02)

強制條款一次完整攔截的步驟：

| 序 | 執行者 | 動作 | 成功結果 | 失敗處置 |
|---|---|---|---|---|
| 1 | App | 會員登入後呼叫中斷表 API（C05） | 取得中斷表，存在記憶體 | 中斷表視為空，放行（C09） |
| 2 | App | 每次頁面顯示時，以頁面類別名稱比對中斷表（C10） | 命中某列，記下該列的 `id` | 未命中：不動作 |
| 3 | App | 呼叫 member_token API（C06） | 取得 `member_token` | 提示錯誤，回待命（C11） |
| 4 | App | 開全螢幕條款 WebView，POST 表單到 `https://approve.17fit.com/auth`（C07） | 條款服務顯示該 flow 的未完成條款清單 | 條款服務導向 `error_url?error_code=...`（C08） |
| 5 | 會員 | 在條款服務內逐份填寫並送出 | 全部完成後條款服務導向 `back_url` | 頁內錯誤由條款服務以 toast 顯示，WebView 不關閉 |
| 6 | App | 攔下 `back_url`（或 `error_url`）導向：取消載入、關閉 WebView | WebView 關閉 | — |
| 7 | App | 本機先移除該 `id` 的所有列，再重新呼叫中斷表 API，完成後再比對目前頁面 | 已完成的條款不再出現，不會再攔 | 重抓失敗：中斷表視為空，放行 |

## API 共通約定 (C03)

適用於 C04、C05、C06 三支 API。

| 項目 | 規則 |
|---|---|
| 主機 | 與 App 目前呼叫的 17FIT appapi 相同 |
| 路徑前綴 | `/appapi/v1.0.0/` |
| 認證 | 沿用 App 呼叫 appapi 的既有方式：query 參數 `agent_token`（App 識別）與 `token`（會員登入 token）。會員身分一律取自 `token`，API 不接受從外部傳入 member id |
| 方法 | 皆為 `GET`，唯讀，可重試 |
| 成功 | HTTP 200，body `{"code": 0, "msg": "success", "message": "", "data": <內容>}` |
| 失敗 | HTTP 400，body `{"code": "<錯誤碼>", "msg": "<錯誤名>", "message": "<中文訊息>", "data": <不固定>}` |
| `code` 型別 | 成功時是數字 `0`；失敗時是字串（例 `"A2009"`、`"00027"`）。解析時把 `code` 一律轉成字串再比較 |
| `data` | 只在成功時有固定形狀；失敗時 App 不讀 `data` |
| 快取 | 伺服器端沒有快取，每次呼叫都是最新狀態 |

## 待完成數量 API（status）(C04)

```text
GET /appapi/v1.0.0/approval-term/prompt/status/{level}
    ?studio_id={studio_id}
    &agent_token=...
    &token=...
```

| 參數 | 位置 | 型別 | 必填 | 規則 |
|---|---|---|---|---|
| level | path | string | 是 | `warn` 或 `break`；其他值回 `A2008`。App 只需要用 `warn` |
| studio_id | query | int | 是 | 數字；缺少或非數字回 `A2006`；會員不屬於此品牌回 `A2009` |
| agent_token | query | string | 是 | C03 |
| token | query | string | 是 | C03 |

成功回應：

```json
{ "code": 0, "msg": "success", "message": "", "data": { "count": 2 } }
```

| 欄位 | 型別 | 說明 |
|---|---|---|
| data.count | int，≥ 0 | 會員在此品牌尚未完成的該等級條款數。App 直接顯示這個數字 |

## 中斷表 API（break-points）(C05)

```text
GET /appapi/v1.0.0/approval-term/prompt/break-points
    ?studio_id={studio_id}
    &platform={platform}
    &agent_token=...
    &token=...
```

| 參數 | 位置 | 型別 | 必填 | 規則 |
|---|---|---|---|---|
| studio_id | query | int | 是 | 同 C04 |
| platform | query | string | 是 | Android 傳 `studio-android`；iOS 傳 `studio-ios`；其他值回 `A2007` |
| agent_token | query | string | 是 | C03 |
| token | query | string | 是 | C03 |

### 每一列的意義

一列＝「一份會員尚未完成的強制條款」×「該條款所屬 User Flow 在本平台的一個中斷點」。

| ID | 來源 | 目標 | 語意 | 來源端基數 | 目標端基數 | 承載欄位 | 何時消失 |
|---|---|---|---|---|---|---|---|
| R01 | User Flow | 中斷表列 | 一個 User Flow 在回應裡展開成的列 | 1 | 1..* | `id` | 會員完成該 flow 的全部強制條款後，該 `id` 的列全部消失 |
| R02 | 未完成的強制條款 | 中斷表列 | 一份條款在本平台展開成的列 | 1 | 1..* | `approval_term_id` | 會員完成該條款後，該 `approval_term_id` 的列消失 |

雙向敘述：

- R01：一個 User Flow 在回應中出現時至少一列、可能多列；一列恰屬一個 User Flow。
- R02：一份未完成的強制條款在回應中至少一列（該 flow 在本平台有幾個中斷點就幾列，目前都是 1 個）；一列恰對應一份條款。

結論：品牌有 3 份強制條款都未完成時，會收到 3 列 `id` 都是 `any-pages` 的資料。**App 必須以 `id` 去重，同一個 `id` 只開一次 WebView**（條款服務會在同一個畫面列出該 flow 的全部未完成條款）。

### 回應

成功回應範例（`platform=studio-android`，品牌有 2 份未完成強制條款）：

```json
{
  "code": 0, "msg": "success", "message": "",
  "data": [
    {
      "id": "any-pages",
      "user_flow_display_name": "登入後",
      "approval_policy_type": "once",
      "break_point_id": 4,
      "break_point_pattern_type": "android-fragment",
      "break_point_pattern_value": { "name_regexp": ".*" },
      "setting_owner_type": "studio",
      "setting_owner_id": 1834,
      "approval_prompt_level": "break",
      "signature_prompt_level": "none",
      "approval_term_id": 101
    },
    {
      "id": "any-pages",
      "user_flow_display_name": "登入後",
      "approval_policy_type": "once",
      "break_point_id": 4,
      "break_point_pattern_type": "android-fragment",
      "break_point_pattern_value": { "name_regexp": ".*" },
      "setting_owner_type": "studio",
      "setting_owner_id": 1834,
      "approval_prompt_level": "break",
      "signature_prompt_level": "none",
      "approval_term_id": 102
    }
  ]
}
```

沒有未完成強制條款時：`"data": []`。

| 欄位 | 型別 | App 是否使用 | 說明 |
|---|---|---|---|
| id | string | **使用** | User Flow id，例 `any-pages`。開 WebView 時當作 `user_flow_id` 送出。**欄位名是 `id`，不是 `user_flow_id`** |
| approval_prompt_level | string | **使用** | 恆為 `"break"`；比對時仍要檢查 |
| break_point_pattern_type | string | **使用** | Android 為 `"android-fragment"`；iOS 為 `"ios-view-controller"` |
| break_point_pattern_value | object | **使用** | `{"name_regexp": "<正規表達式>"}`。若收到字串，先當 JSON 解析一次（防禦） |
| user_flow_display_name | string | 選用 | 顯示名稱，例 `"登入後"`，可用於 log |
| approval_term_id | int | 不使用 | 條款 id；只用來理解為何同一 `id` 會重複 |
| break_point_id | int | 不使用 | — |
| approval_policy_type | string | 不使用 | — |
| setting_owner_type | string | 不使用 | 恆為 `"studio"` |
| setting_owner_id | int | 不使用 | 等於 `studio_id` |
| signature_prompt_level | string | 不使用 | — |

回應規則：

| 規則 | 說明 |
|---|---|
| 排序 | 不保證，App 不可依賴順序 |
| 重複 | 同一 `id` 可出現多列（R01） |
| 未知欄位 | App 解析時忽略未知欄位，後端可能新增欄位 |
| 目前上線值 | Android、iOS 各只有一個中斷點：`id = "any-pages"`、`name_regexp = ".*"`，也就是「登入後任何頁面」都攔 |

## member_token API（暫定，待後端提供）(C06)

**這支 API 目前不存在，是唯一阻擋 App 開工串接的項目。** App 可以先用 mock 開發，下列為暫定契約，正式路徑與回應以 17FIT 後端通知為準。

```text
GET /appapi/v1.0.0/approval-term/member-token
    ?studio_id={studio_id}
    &agent_token=...
    &token=...
```

| 參數 | 位置 | 型別 | 必填 | 規則 |
|---|---|---|---|---|
| studio_id | query | int | 是 | 同 C04；會員不屬於此品牌回 `A2009` |
| agent_token | query | string | 是 | C03 |
| token | query | string | 是 | C03 |

成功回應（暫定）：

```json
{
  "code": 0, "msg": "success", "message": "",
  "data": { "member_token": "eyJ0eXAiOiJKV1Qi..." }
}
```

| 欄位 | 型別 | 說明 |
|---|---|---|
| data.member_token | string | 一次性 token，**簽發後 60 秒過期** |

App 規則：

1. 每次開條款 WebView 前都重新呼叫，取得後立刻送出 POST /auth（C07），不要先取好放著。
2. 不重用、不儲存、不解析 token 內容；把它當不透明字串原樣送出。
3. App 不可能也不應該自己產生這個 token。
4. 取得失敗：不開 WebView，提示錯誤，回待命狀態（C11），下次頁面顯示時再試。

## 開啟條款服務：POST /auth (C07)

| 項目 | 值 |
|---|---|
| 網址 | 正式環境 `https://approve.17fit.com/auth`；測試環境網域待 17FIT 提供 |
| 方法 | `POST` |
| Content-Type | `application/x-www-form-urlencoded`，每個值都要 URL encode |
| 送出者 | 條款 WebView 本身（不是 App 的 HTTP client），因為條款服務要在 WebView 內建立登入狀態 |

表單欄位：

| 欄位 | 強制條款攔截（break） | 提示條款紅點（warn） | 規則 |
|---|---|---|---|
| auth_type | `member_token` | `member_token` | 必填，固定值；其他值回 `A2004` |
| member_token | C06 取得的值 | 同左 | 必填；過期回 `A2002` |
| back_url | App 定義的完成網址 | 同左 | 必填；必須是合法 https 網址，否則 `A2001` |
| error_url | App 定義的錯誤網址 | 同左 | 必填；空值回 `A2003` 且**不會回到 App**（C08） |
| success_entry | `user-flow` | `terms` | 決定進入哪個畫面 |
| user_flow_id | 命中列的 `id`（例 `any-pages`） | 不送 | `success_entry=user-flow` 時必填，缺少回 `A2001` |
| by_pass_single_item | `1` | 不送 | `success_entry=user-flow` 時必填，缺少回 `A2001` |

範例（break，URL encode 前）：

```text
auth_type=member_token
member_token=eyJ0eXAiOiJKV1Qi...
back_url=https://app-callback.example.com/approve-term/back
error_url=https://app-callback.example.com/approve-term/error
success_entry=user-flow
user_flow_id=any-pages
by_pass_single_item=1
```

送出後的畫面：

| success_entry | 會員看到 | 何時導向 back_url |
|---|---|---|
| `user-flow` | 「流程攔截頁」：列出該 flow 全部未完成條款，會員逐份點入填寫 | 全部完成時；或載入時已無未完成條款 |
| `terms` | 「條款列表頁」：列出品牌全部條款 | 會員按頁面上的「返回」 |

已知行為：`by_pass_single_item=1` 原本的用意是「只有一份條款時直接進填寫頁」，目前尚未生效，只有一份條款也會先顯示流程攔截頁。後端修正後自動生效，App 照送 `1`、不需改動。

## 導回契約：back_url／error_url (C08)

App 不需要真的有這兩個網頁。它們只是「關閉 WebView 的訊號」：App 攔下導向、取消載入、關閉 WebView。

| 事件 | 條款服務的動作 | WebView 收到的導向 | 導向觸發方式 | App 動作 |
|---|---|---|---|---|
| 流程攔截頁：全部條款完成 | 導向 back_url | `back_url` 原字串，不附加任何參數 | 頁面 JavaScript `window.location.href` | 取消載入、關閉、重抓（C09） |
| 流程攔截頁：載入時已無未完成條款 | 導向 back_url | 同上 | 同上 | 同上 |
| 條款列表頁：按「返回」 | 導向 back_url | 同上 | 同上 | 取消載入、關閉、重查紅點（C13） |
| POST /auth 驗證失敗 | 導向 error_url 並附加參數 | `error_url` ＋ `?error_message=<encoded>&error_code=<碼>&status=fail`（error_url 本身已有 `?` 時改用 `&` 接） | HTTP 302 | 取消載入、讀 `error_code`、關閉、提示（C14） |
| POST /auth 驗證失敗且沒帶 error_url | 顯示條款服務自己的錯誤頁 | 不會導向 App 的網址 | — | App 無從得知；因此 **error_url 一定要帶** |
| 條款頁內部錯誤（例：網路中斷） | 顯示 toast | 不導向 | — | 不需處理；WebView 維持開啟 |

規則：

1. back_url 導向時**不會附加 `user_flow_id`**。App 自己記住觸發的 `id`；若想從網址讀回，可直接寫進 back_url，例：`https://app-callback.example.com/approve-term/back?user_flow_id=any-pages`。
2. back_url 與 error_url 用不同路徑，App 以「網址以 back_url 開頭」「網址以 error_url 開頭」判斷。
3. 使用 https 網址。自訂 scheme（如 `myapp://`）不保證通過驗證，不要使用。
4. 網址主機用 App 團隊自己控制的網域；因為導向一定會被攔下，該網址不需要可以連線。
5. 攔截點要同時涵蓋 JavaScript 導向與 HTTP 302 導向（C12 的兩個平台做法都已涵蓋）。

## 中斷表生命週期 (C09)

| 時機 | 動作 |
|---|---|
| 登入成功 | 抓中斷表；抓完立刻對目前顯示中的頁面比對一次 |
| 冷啟動且已登入 | 同上 |
| 關閉條款 WebView（back_url 或 error_url） | 先在本機移除觸發的 `id` 的所有列，再重抓；重抓完成後才回到待命並比對目前頁面 |
| 切換品牌（studio_id 改變） | 清空並重抓 |
| 從背景回到前景 | 重抓（建議；是否採用待確認，見未決事項） |
| 登出 | 清空中斷表 |
| 抓取失敗（逾時、HTTP 400、斷網） | 中斷表視為空，放行不攔截；下一個重抓時機再試 |
| 未登入 | 不抓、不比對 |

儲存：只放記憶體，不寫入磁碟。原因：條款完成狀態以伺服器為準，寫入磁碟會在離線或換帳號時用到過期資料。

## 頁面比對規則 (C10)

比對前先以 `id` 去重。對每個不重複的列，三個條件都成立才算命中：

1. `approval_prompt_level == "break"`
2. `break_point_pattern_type` 等於本平台：Android `"android-fragment"`；iOS `"ios-view-controller"`
3. `break_point_pattern_value.name_regexp` 對「目前頁面名稱」做**完整比對**（整個字串都要符合，不是部分包含）

| 項目 | Android | iOS |
|---|---|---|
| 「頁面」指的是 | Fragment | UIViewController |
| 頁面名稱 | `fragment.javaClass.simpleName`，例 `ScheduleFragment` | `String(describing: type(of: viewController))`，例 `ScheduleViewController`（不要用 `NSStringFromClass`，它會帶模組前綴） |
| 完整比對 | `Regex(pattern).matches(name)` | `NSRegularExpression(pattern: "^(?:" + pattern + ")$")` |
| release 版名稱保留 | R8／ProGuard 加 `-keepnames class * extends androidx.fragment.app.Fragment`，否則名稱會被混淆成 `a`、`b` | 不需處理 |

其他規則：

| 規則 | 說明 |
|---|---|
| 正規表達式無法編譯 | 略過該列並記 log，不可閃退 |
| 排除頁面 | 條款 WebView 所在頁面、登入頁、啟動頁、註冊頁不比對。建議做法：這些頁面實作一個標記介面 `SkipBreakCheck` |
| 頁面名稱是對外契約 | 後端以頁面類別名稱設定中斷點。重構改名前先通知 17FIT |
| 新增中斷點不需改版 | 17FIT 後端新增 User Flow 或中斷點時，App 只要照本節通用規則比對，就會自動生效 |

範例：`name_regexp = "CancelSubscriptionFragment"` 只命中該頁；`"CancelSubscription.*"` 命中所有以 `CancelSubscription` 開頭的頁面；`".*"` 命中所有頁面。

## 攔截狀態機 (C11)

以下是建議設計，用來避免兩個問題：(1) 條款 WebView 所在頁面本身被 `.*` 命中，又開第二個 WebView；(2) 關閉 WebView 後底層頁面重新 resume／appear，用尚未更新的中斷表再攔一次。

| 起始狀態 | 事件 | 條件 | 目標狀態 | 動作 |
|---|---|---|---|---|
| 未就緒 | 登入成功、冷啟動已登入 | — | 重抓中 | 呼叫中斷表 API |
| 重抓中 | 中斷表 API 成功 | — | 待命 | 存中斷表；對目前頁面執行一次「頁面顯示」 |
| 重抓中 | 中斷表 API 失敗 | — | 待命 | 中斷表設為空（放行） |
| 待命 | 頁面顯示 | 頁面是 `SkipBreakCheck` | 待命 | 無 |
| 待命 | 頁面顯示 | 沒有命中（C10） | 待命 | 無 |
| 待命 | 頁面顯示 | 命中某 `id` | 攔截中 | 記下 `id`；取 member_token；開條款 WebView 並 POST /auth |
| 攔截中 | 頁面顯示（任何頁面） | — | 攔截中 | 忽略 |
| 攔截中 | 取 member_token 失敗 | — | 待命 | 不開或關閉 WebView；提示錯誤 |
| 攔截中 | WebView 導向 back_url | — | 重抓中 | 取消載入；本機移除該 `id`；關閉 WebView；呼叫中斷表 API |
| 攔截中 | WebView 導向 error_url | — | 重抓中 | 取消載入；讀 `error_code`；關閉 WebView；提示錯誤（C14）；呼叫中斷表 API |
| 任何狀態 | 登出 | — | 未就緒 | 清空中斷表；清除條款服務網域的 cookie |

不變量：

- 同一時間最多一個條款 WebView。
- 只有「待命」狀態會觸發攔截。
- 「重抓中」回到「待命」之後才重新比對目前頁面。

## 原生實作（Android／iOS）(C12)

### 掛載點

| 平台 | 「頁面顯示」事件來源 | 備註 |
|---|---|---|
| Android | `supportFragmentManager.registerFragmentLifecycleCallbacks(callback, true)` 的 `onFragmentResumed` | 第二個參數 `true` 讓子 Fragment 也觸發 |
| iOS | 共用 base ViewController 的 `viewDidAppear(_:)` | 若沒有共用 base class，改掛 `UINavigationControllerDelegate.navigationController(_:didShow:animated:)`，並另外處理 tab 切換與 modal |

選「頁面顯示後覆蓋」而不是「跳頁前攔截」的理由：返回鍵、切換 tab、推播、deep link 都不一定經過共用的跳頁函式，跳頁前攔截會漏攔；頁面顯示事件涵蓋所有進入方式。會員完成後 WebView 關閉，人已經在原本要去的頁面。

### 條款 WebView 規格

| 項目 | Android | iOS |
|---|---|---|
| 元件 | `android.webkit.WebView` | `WKWebView` |
| 禁用 | Chrome Custom Tabs（無法攔截導向） | `SFSafariViewController`（無法攔截導向） |
| 送出 POST | `webView.postUrl(authUrl, formBytes)` | `URLRequest`，`httpMethod = "POST"`，header `Content-Type: application/x-www-form-urlencoded`，`httpBody` 為表單 |
| 攔截導向 | `WebViewClient.shouldOverrideUrlLoading`；另在 `onPageStarted` 做同樣判斷作為保險 | `WKNavigationDelegate.webView(_:decidePolicyFor:decisionHandler:)` 回 `.cancel` |
| 設定 | `javaScriptEnabled = true`、`domStorageEnabled = true`、接受 cookie | 預設值即可 |
| 呈現 | 全螢幕 | `modalPresentationStyle = .fullScreen`、`isModalInPresentation = true` |
| 返回鍵／手勢 | 返回鍵：`canGoBack()` 時 `goBack()`，否則不動作；**不關閉** | 不可下滑關閉；不放關閉按鈕 |

### Android（Kotlin）片段

```kotlin
// 頁面顯示事件：在主 Activity onCreate 註冊一次
val pageCallbacks = object : FragmentManager.FragmentLifecycleCallbacks() {
    override fun onFragmentResumed(fm: FragmentManager, f: Fragment) {
        ApprovalBreakGuard.onPageShown(f.javaClass.simpleName, skip = f is SkipBreakCheck)
    }
}
supportFragmentManager.registerFragmentLifecycleCallbacks(pageCallbacks, true)

// 比對：去重 → 三個條件 → 回傳命中的 id
fun findHit(rows: List<BreakRow>, pageName: String): String? =
    rows.distinctBy { it.id }.firstOrNull { r ->
        r.level == "break" && r.patternType == "android-fragment" &&
            runCatching { Regex(r.nameRegexp).matches(pageName) }.getOrDefault(false)
    }?.id

// 表單
fun formBody(fields: List<Pair<String, String>>): ByteArray =
    fields.joinToString("&") { (k, v) ->
        URLEncoder.encode(k, "UTF-8") + "=" + URLEncoder.encode(v, "UTF-8")
    }.toByteArray(Charsets.UTF_8)

// 開啟與攔截
webView.settings.javaScriptEnabled = true
webView.settings.domStorageEnabled = true
CookieManager.getInstance().setAcceptCookie(true)
webView.webViewClient = object : WebViewClient() {
    override fun shouldOverrideUrlLoading(
        view: WebView, request: WebResourceRequest,
    ): Boolean = handleUrl(request.url.toString())
    override fun onPageStarted(view: WebView, url: String, favicon: Bitmap?) {
        if (handleUrl(url)) view.stopLoading()
    }
}
fun handleUrl(url: String): Boolean {
    when {
        url.startsWith(BACK_URL) -> ApprovalBreakGuard.onWebViewClosed(errorCode = null)
        url.startsWith(ERROR_URL) -> {
            val code = Uri.parse(url).getQueryParameter("error_code")
            ApprovalBreakGuard.onWebViewClosed(errorCode = code)
        }
        else -> return false
    }
    return true
}
webView.postUrl(AUTH_URL, formBody(listOf(
    "auth_type" to "member_token",
    "member_token" to token,
    "back_url" to BACK_URL,
    "error_url" to ERROR_URL,
    "success_entry" to "user-flow",
    "user_flow_id" to flowId,
    "by_pass_single_item" to "1",
)))
```

`onWebViewClosed` 要確保只執行一次（兩個 callback 都可能收到同一個網址）。

### iOS（Swift）片段

```swift
// 頁面顯示事件：所有頁面共用的 base class
class BaseViewController: UIViewController {
    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        let name = String(describing: type(of: self))
        ApprovalBreakGuard.shared.onPageShown(name, skip: self is SkipBreakCheck)
    }
}

// 完整比對
func fullMatch(_ pattern: String, _ name: String) -> Bool {
    guard let re = try? NSRegularExpression(pattern: "^(?:\(pattern))$") else {
        return false
    }
    return re.firstMatch(in: name, range: NSRange(name.startIndex..., in: name)) != nil
}

// 表單
func formBody(_ fields: [(String, String)]) -> Data {
    // 只保留 RFC 3986 unreserved 字元，其餘全部 percent-encode
    let allowed = CharacterSet(charactersIn:
        "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~")
    func enc(_ s: String) -> String {
        s.addingPercentEncoding(withAllowedCharacters: allowed)!
    }
    let s = fields.map { "\(enc($0.0))=\(enc($0.1))" }.joined(separator: "&")
    return Data(s.utf8)
}

// 開啟
var req = URLRequest(url: URL(string: authURL)!)
req.httpMethod = "POST"
req.setValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")
req.httpBody = formBody([
    ("auth_type", "member_token"), ("member_token", token),
    ("back_url", backURL), ("error_url", errorURL),
    ("success_entry", "user-flow"), ("user_flow_id", flowId), ("by_pass_single_item", "1"),
])
webView.load(req)
vc.modalPresentationStyle = .fullScreen
vc.isModalInPresentation = true
topViewController.present(vc, animated: true)

// 攔截
func webView(_ webView: WKWebView, decidePolicyFor action: WKNavigationAction,
             decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
    let url = action.request.url?.absoluteString ?? ""
    if url.hasPrefix(backURL) {
        decisionHandler(.cancel)
        ApprovalBreakGuard.shared.onWebViewClosed(errorCode: nil)
        return
    }
    if url.hasPrefix(errorURL) {
        let items = URLComponents(string: url)?.queryItems
        let code = items?.first { $0.name == "error_code" }?.value
        decisionHandler(.cancel)
        ApprovalBreakGuard.shared.onWebViewClosed(errorCode: code)
        return
    }
    decisionHandler(.allow)
}
```

### 守門員共用邏輯（偽碼）

```text
on pageShown(name, skip):
  if state != Ready or !loggedIn or skip: return
  flowId = findHit(breakPoints, name)              # C10
  if flowId == null: return
  state = Presenting; triggeredId = flowId
  token = GET member-token(studio_id)              # C06；失敗 → state = Ready、提示、return
  openWebView(POST AUTH_URL, form(token, BACK_URL, ERROR_URL,
              success_entry = "user-flow", user_flow_id = flowId,
              by_pass_single_item = "1"))

on webViewClosed(errorCode):                       # 只執行一次
  closeWebView()
  breakPoints = breakPoints.filter(r -> r.id != triggeredId)
  state = Refreshing
  breakPoints = GET break-points(studio_id, PLATFORM) or []   # 失敗 → []
  state = Ready
  pageShown(currentPageName, currentPageSkip)
  if errorCode != null: showError(errorCode)       # C14
```

## 提示條款紅點流程 (C13)

| 序 | 執行者 | 動作 | 成功結果 | 失敗處置 |
|---|---|---|---|---|
| 1 | App | 進入「我的帳戶」頁時呼叫 `status/warn?studio_id=`（C04） | 取得 `data.count` | 不顯示紅點 |
| 2 | App | `count > 0` 時在「合約或問卷」項目顯示紅點與數字 | — | — |
| 3 | 會員 | 點「合約或問卷」 | — | — |
| 4 | App | 取 member_token（C06），開條款 WebView，POST /auth：`success_entry=terms`，不送 `user_flow_id`、`by_pass_single_item` | 條款服務顯示條款列表頁 | 導向 error_url（C14） |
| 5 | 會員 | 填寫條款，或按頁面上的「返回」 | 條款服務導向 back_url | — |
| 6 | App | 攔下 back_url，關閉 WebView，重新呼叫 `status/warn` 更新紅點 | 紅點數字更新 | 維持原數字 |

提示條款流程不經過攔截守門員的「攔截中」狀態；但開啟期間也不應觸發強制條款攔截（條款 WebView 頁面屬於 `SkipBreakCheck`）。

## 錯誤碼與 App 處置 (C14)

17FIT API（C04、C05、C06）的錯誤：HTTP 400，讀 body 的 `code`。

| code | msg | 觸發條件 | App 處置 |
|---|---|---|---|
| 00027 | UserNotFound | 會員 `token` 缺少或無效 | 依 App 既有做法導回登入 |
| 00003 | Unauthorized | `agent_token` 無效 | 依 App 既有做法重取 agent_token |
| A2006 | InvalidStudioId | `studio_id` 缺少或不是數字 | 記 log；不攔截／不顯示紅點 |
| A2007 | InvalidPlatform | `platform` 不是 `studio-android`／`studio-ios` | 記 log；不攔截 |
| A2008 | InvalidLevel | `level` 不是 `warn`／`break` | 記 log；不顯示紅點 |
| A2009 | MemberNotInStudio | 會員不屬於這個品牌 | 記 log；不攔截／不顯示紅點 |
| A2000 | UnknowError | 伺服器未預期錯誤 | 記 log；不攔截；下一個重抓時機再試 |

POST /auth 的錯誤：條款服務導向 error_url，讀 query 的 `error_code`。

| error_code | 觸發條件 | App 處置 |
|---|---|---|
| A2001 | 欄位缺漏或格式錯（back_url／error_url 不是合法網址、缺 member_token、break 情境缺 user_flow_id 或 by_pass_single_item） | 關閉 WebView；提示「發生錯誤，請再試一次」；回待命 |
| A2002 | member_token 過期（超過 60 秒）或無效 | 關閉 WebView；提示「畫面逾時，請再試一次」；回待命，下次頁面顯示時重新取 token |
| A2003 | 沒帶 error_url | 不會回到 App（條款服務顯示自己的錯誤頁）。App 一律帶 error_url 即可避免 |
| A2004 | `auth_type` 不是 `member_token` | 同 A2001 |

提示文字為建議，App 可依自己的文案調整。`error_message` 參數是給工程師看的中文訊息，不建議直接顯示給會員。

## 限制與非功能要求 (C15)

| 項目 | 規則 | 驗證方式 |
|---|---|---|
| member_token 時效 | 簽發後 60 秒過期；取得後立即送出 POST /auth | 取得 token 後等 61 秒才送出，應導向 error_url 且 `error_code=A2002` |
| 條款 WebView 數量 | 同一時間最多 1 個 | 快速連續切換頁面，只出現一個 WebView |
| 資料即時性 | API 沒有伺服器快取；會員完成條款後，下一次呼叫中斷表 API 就不含該條款 | 完成後立刻呼叫，回 `[]` 或少了該條款的列 |
| 失敗策略 | 中斷表抓取失敗時放行，不能讓 App 卡住 | 斷網登入，App 可正常使用 |
| 排序 | 不依賴回應順序 | — |
| Android release | 必須保留 Fragment 類別名稱（C10） | release 版 log 印出的頁面名稱是原始類別名稱 |
| 舊版 App | 舊版不攔截；新版上線即生效 | — |

## 驗收條件 (C16)

| # | Given | When | Then |
|---|---|---|---|
| (1) | 未登入 | 瀏覽任何頁面 | 不呼叫中斷表 API、不開 WebView |
| (2) | 已登入，品牌有 1 份未完成強制條款 | 登入完成 | 第一個顯示的頁面上開條款 WebView，顯示流程攔截頁 |
| (3) | 品牌有 4 份未完成強制條款 | 呼叫中斷表 API | 回 4 列、`id` 皆為 `any-pages`；App 只開 1 個 WebView |
| (4) | 條款 WebView 開啟中 | 會員完成全部條款 | App 攔到 back_url、關閉 WebView、重抓後中斷表為空、停在原頁面 |
| (5) | 同 (4) | WebView 關閉、底層頁面再次 resume／appear | 不再開 WebView |
| (6) | 條款 WebView 開啟中 | Android 按返回鍵／iOS 下滑 | WebView 不關閉 |
| (7) | 取得 member_token 後 | 等 61 秒再 POST /auth | 導向 error_url、`error_code=A2002`；App 關閉 WebView 並提示 |
| (8) | 品牌沒有強制條款 | 呼叫中斷表 API | 回 `"data": []`；不攔截 |
| (9) | 已登入 | 從推播或 deep link 直接開某頁 | 該頁顯示時被攔 |
| (10) | 斷網 | 登入 | 中斷表抓取失敗；App 放行可使用 |
| (11) | `studio_id` 是會員不屬於的品牌 | 呼叫中斷表 API | HTTP 400、`code = "A2009"`；不攔截 |
| (12) | 品牌有 M 份未完成提示條款 | 進入「我的帳戶」 | 紅點數字＝`data.count`＝M |
| (13) | 同 (12) | 點入填寫 1 份後返回 | 紅點數字變 M-1 |
| (14) | Android release 建置（R8 開啟） | 進入任一頁面 | log 中的頁面名稱是原始 Fragment 類別名稱 |
| (15) | 會員 A 登出、會員 B 在同一裝置登入 | 會員 B 被攔截 | WebView 顯示的是會員 B 的條款 |
| (16) | iOS | 條款 WebView 的 ViewController 顯示 | 不會因 `.*` 再開第二個 WebView |

## 未決事項與假設

| 項目 | 目前假設 | 誰決定 | 影響 |
|---|---|---|---|
| member_token API 的正式路徑與回應 | 暫定 `GET /appapi/v1.0.0/approval-term/member-token?studio_id=`，回 `data.member_token` | 17FIT 後端 | **阻擋串接**；App 可先用 mock 開發 |
| 測試環境的 appapi 主機、條款服務網域、測試品牌與帳號 | 由 17FIT 提供 | 17FIT | 阻擋測試 |
| 單一條款直接進填寫頁（by_pass_single_item） | 目前未生效，App 照送 `1` | 17FIT 後端 | 不影響 App 實作 |
| 從背景回到前景是否重抓 | 重抓 | 17FIT PM | 影響 C09 一列 |
| 攔截中是否提供「登出」出口 | 不提供 | 17FIT PM | 影響 C12 返回鍵行為 |
| back_url／error_url 實際網址 | `https://<App 團隊控制的網域>/approve-term/back`、`.../approve-term/error` | App 團隊 | 只要是合法 https 網址即可 |

## 出處

- 依據 17FIT 後端現行實作與正式環境設定整理，校對日期 2026-10-17。
- 回應範例中的 `setting_owner_id`、`approval_term_id` 數值為示意值。
- 標「暫定」或列在未決事項的項目，以 17FIT 後端或 PM 的正式通知為準。
