LINE 頻道全景：從選單到每一頁 LIFF

01系統全景圖

一個 Cloudflare Worker 做三件事：bot webhook（聊天訊息與卡片）、/api/*（資料）、靜態 LIFF（public/index.html，單頁 app）。LINE 上有三個場景，全部通到同一個 LIFF，用 URL 參數決定情境：

flowchart LR
  G["💬 群組聊天
bot 選單 + Flex 卡片
連結都帶 ?g=群組id"]
  L["🖥️ LIFF 工作台
指派·審核·日報·證據·總覽·我的工項"]
  P["👤 1:1 聊天
Rich Menu 底欄·跨專案·指揮中心"]
  G <--> L
  L <--> P
    

核心迴圈，五步：

flowchart LR
  A["1 · 上傳請款單"] --> B["2 · 畫框指派
框 + 監工 + 張數 + 截止"]
  B --> C["3 · 群組通知
你被指派 N 項"]
  C --> D["4 · 監工拍照
LIFF 或直接丟照片"]
  D --> E["5 · 主任審核
採認 / 退回"]
  E -->|退回| D
  E -->|採認| F(["完成"])
    

設計鎖定：沒有 OCR — 系統不讀掃描上的字。「框 + 人 + 張數」就是資料模型，照片證據掛在框上，任何格式的請款單都能用。標註後的掃描圖是指派 → 拍照 → 審核三步共享的物件。

02選單與 Rich Menu

群組選單 = bot 發的 imagemap 圖片（不是 Rich Menu）

LINE 的 Rich Menu 不會出現在群組，所以群組入口是一張 bot 發的橫幅圖片訊息（imagemap，menuImagemap()）。bot 被加進群組時、或有人打喚起詞時發出（見第 3 章）。

群組 imagemap 選單1040×219 · 服務路徑 /menu/12/寬度（12 是換圖用的 cache-bust 序號，LINE 會快取舊圖 — 換美術必 bump + 重發選單）。每個 tap zone 的連結都帶 ?g=群組id — bot 從 webhook 事件知道群組並烙進 URL；LIFF 絕不依賴 liff.getContext 拿群組。

1:1 Rich Menu（在 OA Manager 手動設定）

1:1 Rich Menu 底欄2500×843 · 在 OA Manager 上傳與設定 tap 區，程式不管這張圖。四個 tile：問 Eagle（送文字）· 我的工項 ?v=mine · 我的照片 ?v=photos · 我的儀表板 ?v=dash。只有加 OA 好友的人才有 1:1。美術源檔在 line-channel-design/menu-art/。

歡迎訊息（兩種）

03喚起詞完整對照 程式核對

「怎麼叫出選單 / Eagle / AI」在群組裡其實有 多層規則，不是單一關鍵字。以下逐條對照 src/index.js 與 src/parse.js 的實際判斷（這是最容易被文件寫漏的地方）。

六層規則

群組收到一句文字，bot 怎麼判斷

webhook 依這個優先順序逐層判斷（第一個命中就回，後面不看）：

flowchart TD
  M["群組收到文字"] --> Q1{"選單關鍵字？
選單 · menu · ai"}
  Q1 -->|是| MENU["發 imagemap 選單"]
  Q1 -->|否| Q2{"主任打「提醒全部」？"}
  Q2 -->|是| REMIND["@提及未交監工 + 1:1 推卡"]
  Q2 -->|否| Q3{"@提及 OA，或 wantsEagle？"}
  Q3 -->|"打招呼 / 純 @提及"| GREET["狀態列 + 問 Eagle 按鈕卡"]
  Q3 -->|"真的問句"| ANS["回答（文字 / Flex 卡）"]
  Q3 -->|否| Q4{"像出工日報？"}
  Q4 -->|是| DAILY["整理成日報卡（確認 / 修改）"]
  Q4 -->|否| Q5{"句中含
menu·eagle·ai·指派·工項？"}
  Q5 -->|是| MENU2["發選單"]
  Q5 -->|否| SILENT(["安靜 — 不打擾群組"])
    

為什麼要這麼多層：群組是工班聊天的地方，bot 不能話多。所以只有「明確喚起（選單/@提及）」或「明顯在問 Eagle（主題詞＋問句）」才出聲；一般閒聊（「油漆好了啦」）保持安靜。分類器 wantsEagle() 有單元測試護著（parse.test.js 內 3 個 wantsEagle 案例）。

04加入與身分

• 身分是每群一份：同一人可以在 A 群當主任、B 群當監工（跨群雙身分在 1:1 有檢視切換，見第 8 章）。
• 第一次在某群開 LIFF → 角色選擇頁。一群只有一位工地主任（/api/members 伺服器端擋），被佔走會鎖卡並顯示「已由 X 擔任」。
• 加入或變更角色時，bot 在群組廣播：「{名字} 加入工項 · 身分：工地主任 / 監工」。

第一次進來：選身分非成員開任何 LIFF 連結都先落到這頁（route() 判斷 MY_ROLE 為空）。工地主任卡若已被佔 → 鎖定。

已加入頁 ?v=join再點加入不會重問，直接給前往按鈕（主任 → 指派工項；監工 → 查看工項）。

05工地主任（群組）

底部導覽五個 tab（NAV_SUPER）：指派工項 · 審核 · 出工日報 · 證據 · 總覽。點左上 logo = 回角色首頁（主任 → 指派工項）。

指派：上傳 → 畫框 → 指派 → 通知

1 上傳請款單（主任首頁）拍照（相機）或從相簿/檔案。選完直接進編輯器，不設預覽頁；「更換」在編輯器 header。

2 編輯器：工具箱展開右上 ⊕ 展開：框選（預設）· 移動 · 復原 · 刪除全部 · 收起。旋轉獨立在左下、縮放 pill 右下（pinch / 滾輪 / ±）、⤢ 全螢幕、「看工項」跳到清單。

3 畫框（未指派）拖一個框 → 自動彈指派抽屜。框上的標籤與把手反向縮放（旋轉/縮放後維持恆定大小與正向）。點已指派的框＝重開抽屜編輯（tap 與拖曳以 6px 區分）。

4 指派抽屜真實工班名單（本群成員）。需要照片 N（預設 2，拍滿＝完成，無手動「標記完成」）· 截止日（預設 +7 天）· 樓層/位置（樓層＝綠色 F、區域＝中性圖標；填了樓層＝一層一任務，逐層分別拍照與審核）。

5 已送出POST /api/assign：存 D1 + 掃描圖進 R2 + 群組推播「你被指派 N 項」。「再上傳一張」＝開新掃描（多掃描模型，一掃描一卡）；「完成」＝liff.closeWindow()。

審核：採認 / 退回（逐樓層）

sequenceDiagram
  participant C as 監工
  participant G as 群組
  participant S as 主任
  participant L as LIFF 審核頁
  C->>G: 拍滿張數
  G-->>S: 完成卡「審核 ›」
  S->>L: 深連 ?rev=請款單_框
  S->>L: 逐樓層 採認 / 退回
  L-->>G: 結果（採認✅ / 退回↩️@監工）
    

6 審核清單（tab「審核」）主任預設落「待採認」。一掃描一卡（圖上編號 pin），每列一人 + 狀態 pill。已採認的人灰在原位（不消失）；整卡全採認才沉到「已完成」摺疊區。

7 審核詳情 ?rev=請款單_框聊天卡「審核 ›」深連到這頁（可帶樓層直接選定）。點清單列或圖上的框選取；逐樓層 → 底欄「採認 1F｜退回」；已採認的樓層變灰不可再選；全部樓層完成或已採認才開放「全部採認」。

8 證據燈箱審核情境的燈箱直接帶「退回｜採認」（監工看自己照片時是「刪除這張 / 再拍一張」）。滑動換張 + 頁點。

• 退回要填理由（quick-reply）→ 該樓層回到待處理；監工重拍新照片會自動清掉退回狀態。退回一定推播群組並 @提及監工。
• 採認單項時安靜（不洗版）；某人整組工項全數採認才發「已採認 {名字} 的全部工項 ✅」。

出工日報：聊天自動解析 → LIFF 檢視與修改

flowchart LR
  T["群組貼派工訊息
（任意格式）"] --> P["bot 錨點解析
parseDailyLog()"]
  P --> K["「已整理」卡
樓層/區域 chips + 人數"]
  K -->|"確認（主任限定）"| C["✅ 已確認 → 進日報頁"]
  K -->|"修改"| E["LIFF 編輯器
?v=daily&edit=1"]
  E --> C
  C --> R["出工 vs 照片落差
→ 請工班補拍 推播"]
    

解析器（src/parse.js；parse.test.js 共 22 個案例涵蓋解析器與 wantsEagle）吃工地實際會貼的格式：

• 日期：民國（115.7.1）、西元、M.D 都認得；同日期重貼＝覆蓋舊版並提醒重新確認。
• 樓層 / 位置：單層、範圍（23F 28F）、以上/以下；區域詞自動判別（車道、前中庭、北側… 台灣工地詞庫）→ 樓層綠 chip、區域中性 chip。
• 人數：前置或後置、含不含「人」都可；0 人照列不丟。
• 看不懂的行不會默默消失 → 卡上 ⚠ 未整理提示，編輯器裡可「加入」（轉成正式列）或「移除」。

9 出工日報 ?v=daily今日 / 7日 / 月 + ‹› 日期導航（可帶 &d=日期 落到特定日）。已確認徽章、出工合計與較上次差異、⚠ 建議 banner（已派 26 人但收到 0 張照片 → 請工班補拍）。只顯示已確認的日報。

10 日報修改 &edit=1（主任限定，確認也是）逐列展開編輯（樓層可留空、人數可 0）、新增一項、合計自動重算 → 儲存並確認，重發修正卡到群組。

證據 · 總覽 · 說明

11 證據 ?v=evidence上：待採認工作清單 — 逐樓層浮出（1F 拍完就出現，不等 2F），點列深連審核詳情該樓層。下：全專案照片流（全部 / 已採認 / 待採認 / 被退回 + 日期分組）。

12 總覽 ?v=overview完成率環 + 已完成/進行中/待處理 + 待採認/逾期計數 + 工班排行（全部 / 本週 / 今日）。排行的綠色 podium 只給真實達成，0/N 顯示素色條。

13 使用說明 ?v=help走 LIFF 白色 chrome — 不外開瀏覽器，因為 LINE 內建瀏覽器會忽略 theme-color。主任 / 監工兩段步驟教學。

06監工（群組）

底部導覽四個 tab（NAV_CREW）：我的工項 · 我的照片 · 排行 · 問 Eagle。點 logo → 我的工項。

14 我的工項 ?v=mine「我的｜全部」tab（監工預設我的）、頂部進度條、最新在上排序、一掃描一卡（accordion）+ 編號 pin 找自己的框、「你」tag、待處理 / 逾期 chip。

15 工項詳情：拍照回報進度 X/N、聚焦綠框（其他變暗）。逐項「拍照」→ 原生相機 → 未拍滿自動續拍、拍滿 N 張自動完成 → 群組完成卡 + 主任 1:1 審核卡。縮圖點開燈箱（刪除這張 / 再拍一張；掉到 N 以下會退回待處理）。主任開別人的＝代為拍照。

16 我的照片 ?v=photos自己的證據流 + 已採認 / 待採認 / 被退回篩選 + 日期分組。

17 排行同一支 ?v=overview，角色決定內容：監工只看工班排行，主任看完整儀表板。

18 問 Eagle ?v=ask即時狀態（完成 / 待處理 / 逾期）+ 常見問題 accordion。群組情境只回本專案。

19 守門監工點「指派工項」→ 不硬擋，落到我的工項 + 提示「只有工地主任可以指派工項」。審核 deep-link 同理被擋（modal「只有工地主任可以審核工項」）。

07聊天拍照回報（不開 LIFF 也能交）

監工不一定會開 LIFF 拍照 —— 直接把照片丟進群組（或 1:1）也算回報。Worker 收到照片 → 下載進 R2 → 進待歸檔佇列（pending_capture），約 2 秒 debounce 把一波連發照片收成一張卡（LINE 每張照片是獨立 webhook）。

flowchart LR
  P["照片進群組 / 1:1
每張是獨立 webhook"] --> C["2 秒收批
「這是哪一項?」卡"]
  C --> K["點一下歸檔
（cap: postback）"]
  K --> D{"拍滿張數？"}
  D -->|是| F["完成卡 → 審核流"]
  D -->|否| W["繼續等照片"]
  C -.->|"混批 / >13 張 / 1:1"| S["整理照片頁
?v=capture&b=批次"]
    

「這是哪一項?」卡（captureAskCard()）回顯照片 + 該監工未完成的工項/樓層按鈕（標籤唯一：「工項N · 第M張 · 樓層」）；主任會看到全工班的代傳選項（名字前綴）。沒待辦且不是主任 → bot 安靜（不打擾閒聊丟圖）。

20 整理照片 ?v=capture&b=批次未歸檔照片托盤（可全選）→ 點一個工項歸進去（選取優先 + 確認抽屜）。每列＝工項 · 第 M 張 + 進度 / 逾期 chip。1:1 丟照片一律走這頁（跨專案）。

081:1 個人（指揮中心）

模型：群組＝工班佈告欄；主任的 1:1＝指揮中心。1:1 導覽四個 tab（NAV_PERSONAL）：儀表板 · 我的工項 · 我的照片 · 問 Eagle（Rich Menu 是入口，LIFF 底欄同構）。所有頁面跨專案彙整，多群以專案分組。

21 我的儀表板 ?v=dash主任視角：頂部「N 項待採認」CTA、完成率環、總工項/照片/平均、採認/退回/接受率、本週/今日/逾期、近 7 日長條、各請款單進度。Rich Menu 的主要落點。

22 雙身分切換（lens）有的群當主任、有的當監工 → 右上「檢視：… ▾」下拉切視角（以工地主任檢視 / 以監工檢視）。純 UI 視角，不改伺服器授權；單一身分的人看不到這顆。

23 我的工項（跨專案） ?v=mine「我的工項｜待採認」tab；每卡帶所屬群組的角色 badge。在 1:1 拍照會寫回原專案群組（完成推播落在原群）。

24 待採認佇列 ?v=mine&tab=review主任視角才有：所有專案待審一字排開。聊天卡「前往待採認 ›」落這。

25 我的照片（跨專案） ?v=photos跨 N 個專案 · 共 M 張 + 篩選；其餘同群組版。

26 問 Eagle（1:1） ?v=ask跨專案彙總（含「待你採認 N 項」管理者列）。1:1 打任何字 bot 都會答，不用喚起詞。

09聊天卡片總表

所有卡片共用一個殼（flexCard()）：tone 色條頂欄 + 內文 + 綠色主 CTA（primaryBtn，次要動作灰色）。瀏覽器渲染不出 Flex — 改動要在手機上用「新觸發的訊息」驗（舊卡片永遠凍結在發送當下）。

四種代表卡片的長相（示意，非實際渲染 — 聊天卡片只在 LINE 對話裡呈現，無法截圖）：

計費（reply 免費 / push 計額度）見第 11 章。

10LIFF 路由 / Deep-link

單一入口 liff.line.me/2010491601-uK7jHMCT（＝ worker 根路徑）。route() 分流順序：help / photos / capture（不需成員身分）→ 1:1 個人模式（沒有 g）→ 載入成員 → 非成員一律先落角色選擇 → rev= 審核深連 → 各 v= 畫面。

參數表

開發輔助參數

只有 ?as / ?name（身分 mock）被 hostname 鎖在 localhost；?p=1 / ?dev=1 在線上 workers.dev 也會作用。跑法：cd line-worker && npx wrangler dev --remote（接真實 remote D1）→ http://localhost:8787/?g=…&as=…。

11Worker API · 資料層 · 排程

Routes

寫入授權

• LIFF 寫入帶 liff.getAccessToken() → worker 打 LINE /v2/profile 驗人 → 依 members 角色授權（主任 / 本人）。
• 匿名請求 → 403。localhost dev-mock 也因此唯讀。
• 聊天 postback（採認 / 確認 / 提醒全部…）在 webhook 端用 roleOf() 再驗一次主任身分。

資料層（D1 + R2）

wa_evidence / wa_session 是 WhatsApp 頻道的表（同一個 worker 的另一條線），不屬於 LINE。

測試 · 排程 · 計費

• 測試：npm test 共 34 個案例（parse.test.js 22：日報解析 + wantsEagle 分類；boxpatch.test.js 12：逐框 patch 防覆蓋）。
• 排程：cron 0 0 * * *（UTC 00:00 ＝ 台灣 08:00）掃所有群組：今明到期或逾期的未回報工項 → 發 digest 卡（帶「提醒全部」按鈕）；沒有到期項就不發。
• 計費：reply（回應使用者動作）免費不限量；push 計入 OA 月額度（台灣 Light 200 / Standard 3,000 / Premium 6,000 則）— digest、指派通知、完成卡、催工班都是 push。

12檔案與交接

帳號與環境

檔案地圖

部署流程

• 部署：cd line-worker && npm run deploy（wrangler 是本地 devDependency — 一次性指令用 npx wrangler …）。
• 部署後必驗 live：curl + ?cb=隨機值 抓 LIFF 首頁、grep 本次改動的標記字串 — 「No updated asset files」訊息可能伴隨舊資產，眼見為憑。
• 換選單美術：重出 menu-*.png → bump /menu/序號 → 部署 → 在群組重發選單（打「選單」）。
• 資料庫異動：只跑增量 migrate-*.sql（npx wrangler d1 execute eagle-line --remote --file=…）。

Eagle AI · LINE 頻道系統文件 · 2026-07-07 · 截圖 28 張 + 選單素材 2 張（shots/）· 喚起詞、路由、API、資料層均已對照 line-worker/ 原始碼核實 · 僅供內部交接。