嚮導 / 領隊 Portal

一句話：嚮導 / 領隊專屬的受限 login portal —— 只看自己帶的梯次，讀出團 dossier（基礎資訊 / 司機 / 住宿 / 訂餐 / 成員名單）、寫成本與發票填報（經手），取代「發 Google 表單給嚮導填」的舊作法。建構於既有 departure_costs / expense_proofs / departure_* 營運表之上，不另起平行資料模型。

畫面（UI = wireframe）：嚮導 portal · 我帶的梯次 · 單一梯次 dossier + 填報

1. 目標 / 問題

荒野現行讓帶隊嚮導 / 領隊用 Google 表單 / 試算表回報出團資訊與代墊成本（見 GS「0501玉山」出團前準備工作表：現場領隊本人逐筆填車資 / 餐費 / 接駁＋發票繳回狀態）。問題：

• PII 全攤開：試算表把旅客身分證 / 電話 / 緊急聯絡原始值給有連結的人，零稽核、零範圍控制。
• 資料雙寫脫節：嚮導填的成本要人工搬進 ERP，落差大。
• 無範圍：嚮導看得到不該看的梯次 / 旅客。

本檔讓嚮導 / 領隊有受限 login，在 ERP 內：scoped 到自己帶的梯次、讀 dossier、現場拍照填成本 / 發票直接落 departure_costs（經手＝嚮導，覆核在後台），PII 遮罩＋reveal 稽核。

範圍：guide 角色 + guide↔user 連結 + 梯次 scoping + 嚮導 portal UI（dossier 唯讀 + 成本 / 發票填報）。 不做：淨利 / 內外帳分析 / 證明單核簽 / 轉請款（後台 admin / accountant，見 internal-external-ledger）；嚮導排班指派本身（後台，departure_guide_assignments）；嚮導薪資 / 出款（payables(payee_type='guide')，見 control-finance §5）。

2. 資料模型

不新增成本 / dossier 表；只加「guide 實體 ↔ user 帳號」一條連結，其餘全 reuse。

2.1 guides 欄位（目錄主檔）

guides 是嚮導目錄主檔（後台建檔，見 §4.3）。實際欄位（權威 code：packages/core/src/schema/business.ts）：

• 一對一：guides.user_id 唯一（guides_user_id_unique；NULL 可多筆＝多個未開通嚮導）；user.role='guide' 的帳號至多對一個 guide 實體。
• 連結建立 = 後台邀請嚮導開帳號（§4.3 / §5，比照 staff 邀請），不是 self-signup。
• 嚮導僱用型態（正式 / 協作 / 外聘）決策：保留並落地（2026-07-01，三方稽核 D2）。此為僱用/合作關係維度，與 roster_role（帶團職能 leader/assistant/both）是不同軸——roster_role 是排班時可帶團 / 協作的職能，僱用型態是這位嚮導與公司的關係。已落地：guides.engagement_type（值域 full_time/partner/external 對應 正式/協作/外聘，DB CHECK 約束）+ 後台目錄建/編表單 <Select> 暴露 + 名錄列表 <FilterSelect> 篩選。

2.2 梯次 scoping 來源（既有，不改）

嚮導「我帶的梯次」= departure_guide_assignments 中 guide_id = 該 user 對應 guide 且指派為 confirmed 的 departure_id 集合（含 role='leader' 與 'assistant'）。這是嚮導所有讀寫的範圍閘，比照 sales owner-id 只看自己訂單（member-ownership）。

2.3 reuse 的既有表（讀 / 寫）

3. 邏輯 / 存取層

3.1 梯次 scoping（所有讀寫的閘）

每個嚮導端 repo 函式都以「該 user 的 guide.id → departure_guide_assignments confirmed 梯次集合」為範圍，伺服器端強制，不信任 client 傳入的 departure_id。存取非自己梯次 → fail-closed（404 / 403）。比照 owner-id 守衛寫在 query 層，不靠 UI 隱藏。

3.2 成本 / 發票填報（嚮導＝經手）

嚮導送出一筆成本 = 該梯次 departure_costs 一筆，handler 語意為嚮導本人，並進覆核佇列（review_status='pending'，internal-external-ledger §2.1.3）。

每筆成本兩個金額（對齊 GS 領隊薪資申請單「申請總額 vs 發票總金額」成對欄）——這兩欄 departure_costs 早已具備（internal-external-ledger §2.1），嚮導端把它們拆成兩個明確輸入，不再只填單一「金額」：

• 有發票 / 收據：is_declarable=true。憑證影像上傳待物件儲存（GCS）上線（§5 開放議題）——第一版嚮導先填憑證金額即可送出，實體發票 / 收據自行留存、後台覆核時繳交（cost-form 現為 Alert 佔位，刻意不放假的拍照 input 以免影像被靜默丟棄）。憑證 / 發票金額預設帶入代墊額，可上修可下修（無 ≤ 代墊額 上限——實務常見「停車費代墊 300、卻拿到 2,000 發票」，internal-external-ledger §3.3）。
• 無發票：is_declarable=false、憑證 / 發票金額強制 0，同步開立一張 expense_proofs（經手＝嚮導），送後台核准。嚮導仍可拿回代墊額（amount_twd），只是這筆不可申報。
• 領隊費本身（嚮導勞務，非代墊支出）走同一張 departure_costs（category='領隊費'），單一金額、無發票（自然人勞務 → 掛支出證明單 / 扣繳，非開發票），不出現「憑證額」欄。
• 外幣成本（海外領隊現場日幣 / 外幣憑證，internal-external-ledger §2.1.4）：嚮導可選幣別、填外幣金額；內帳匯率第一版預設當日台銀牌告（internal_rate_source='published'），外帳台銀牌告；若該團走預換外幣池（fx_account）由後台覆核時調整來源。嚮導端不顯示淨利 / WAC，只填外幣金額與幣別。
• 送出後嚮導不可改（append-only 對嚮導端）：更正洽線控 / 會計走後台沖正。

覆核 → 代入帳表 → 退款給嚮導（後台，嚮導端不顯示）：

1. 不再「送出即生效」：嚮導送出的成本 review_status='pending'，不計入淨利 / 可申報 / 轉請款，直到會計覆核。
2. 會計覆核 approve（ledger.approve，強制 approver ≠ handler）→ review_status='approved'（代入帳表）；若掛 pending 證明單一併核准。
3. 轉請款給嚮導：approved 的嚮導代墊成本可一鍵 convertCostsToPayable(payee_type='guide')（control-finance §5），進請款管理走出款核簽，把代墊款退還嚮導。

覆核 / 核准 / 轉請款 / 淨利全在後台（admin / accountant），嚮導端不顯示淨利、毛利、收入、覆核狀態。

這是「成本登記」的嚮導 surface；線控 / op 的 surface 在團控成本登記頁（internal-external-ledger §4 / control-finance §4），其登記直接 review_status='approved'（現場營運即生效）。兩個 surface 寫同一份 departure_costs。

3.3 PII reveal（遮罩 + 稽核）

成員名單預設遮罩敏感欄。身分證 / 護照走 KMS reveal：嚮導點「顯示」才解密、且寫 traveler.decrypt audit（RevealSchema 僅接受 idNumber / passportNo 兩欄，order-scoped reveal、防 IDOR），沿用 travelers 既有 reveal 流程。電話 / 緊急聯絡為明文低敏欄，UI 遮罩但不解密（無 reveal action，不進 KMS）。嚮導只能 reveal 自己帶梯次的旅客（scoping 二次收斂：traveler→order→departure ∈ 自己 confirmed 梯次）。相較舊試算表「原始 PII 全攤開」，這是收斂。

3.4 dossier 組裝（唯讀派生）

dossier 各區從既有 repo 讀組合，不複製：基礎資訊（departures/trips）、車（departure_transport）、食（departure_catering + 飲食彙總）、宿（住宿軸）、成員名單（travelers + room-assignment 分組）。嚮導端不顯示金流真相（應收 / 實收 / 淨利）。

4. UI 與權限

4.1 版面（獨立 portal · 行動裝置優先）

獨立最小殼（非後台 sidebar），頂列 + 窄欄置中、大觸控目標（嚮導多在山下用手機）：

• /guide 我帶的梯次：scoped 梯次卡列表（行程 / 日期 / 人數 / 領隊 vs 協作 / 待補成本筆數 / 階段）。
• /guide/[departureId] 單一梯次 dossier：以 tab 切分（手機友善，少長捲）：
  • 出團資訊：基礎資訊 grid + 車 / 食 / 宿 status 卡（沿用出團前準備卡）；宿含分房表（房間 / 房友 chip / 性別 / 同行夥伴分組，沿用分房表）。
  • 成員名單：旅客表（PII 遮罩 + reveal 稽核）。
  • 證件：入山 / 入園 / 床位 / 營位證清單，唯讀 + 下載隨身（申請在 departure-prep，嚮導不負責申請）。
  • 成本 / 發票：已送出列（顯示代墊額 / 憑證額兩欄）+ 新增 dialog（類別 → 項目 → 幣別 → 代墊 / 實付金額（外幣即時換算顯示）→ 有發票？→ 有則填憑證 / 發票金額（預設帶入代墊額、可改，提示「發票額可大於代墊額」；影像上傳待物件儲存上線，現為 Alert 佔位）/ 無則開支出證明單，憑證額 = 0），帶待覆核計數。兩金額語意見 §3.2。

4.2 權限（新角色 guide + 新 permission）

新增角色 guide，不在 adminRoles（不得碰使用者管理 / better-auth admin 端點）。permission（packages/core/src/permissions-ac.ts 註冊）：

departure_cost.create 把「成本登記」從 2026-06-23 的 ledger.manage（admin/accountant 限定）拆出來：成本＋憑證登記是 per-departure 現場作業（線控 / 嚮導），淨利分析才是敏感財務。詳見 internal-external-ledger §4.2。

嚮導讀寫一律經 §3.1 的梯次 scoping 閘二次收斂（即使有 action，也只限自己帶的梯次）。

4.3 後台嚮導目錄（/admin/guides）

嚮導目錄 CRUD 是後台管理 surface（與嚮導本人的受限 portal 分權），權限 guide: ['read', 'manage']（packages/core/src/permissions-ac.ts）：

• 列表頁（page.tsx，requirePermission('guide.read')）：卡片格（頭像 / 姓名 / 狀態 / 資歷 / 專長 badge / 聯絡方式），狀態 + 關鍵字 filter bar，KPI（合作 / 在線 / 停用）。帶隊數 / 評分為 Phase 4 佔位（顯示破折號）。
• 建 / 編表單（guide-form.tsx）：name / slug（不填自動產生）/ years_experience / status / contact_phone / contact_email / avatar_url / specialties（逗號分隔）/ bio。actions 經 guide.manage gate（createGuideAction / updateGuideAction / archiveGuideAction，各寫 guide.create / .update / .archive audit）。
• 開通登入（§5）：卡片對 active、未連結帳號的嚮導顯示「開通登入」，經 inviteGuideAccountAction（guide.manage）產一次性暫時密碼手動轉交；已連結顯示「已開通」badge。連結建立即 §2.1 的 guides.user_id。
• repo：packages/core/src/guides/admin-repo.ts（listGuides / createGuide / updateGuide / archiveGuide / inviteGuideAccount）。

目錄 CRUD 用 guide.*（後台管理）；嚮導本人 portal 用 guide_portal.read（§4.2）—— 兩套權限、兩個 surface，別混。帶團排班（指派 / 換領隊）是第三套 guide_roster.*，見 guide-roster §4.2。

5. 開放議題

• 嚮導開帳號流程（已定）：後台 /admin/guides 卡片「開通登入」邀請，inviteGuideAccount 建 user.role='guide' + 連結 guides.user_id（一對一，競態守衛 user_id IS NULL），印一次性暫時密碼手動轉交（比照 staff 邀請）。嚮導屬 staff-tier，2FA 一律強制（/2fa-setup 接受所有 staff-tier，含 guide）。
• 協作 vs 正領隊權限差異：第一版兩者 dossier / 填報相同（都進 departure_cost.create）；是否限協作只填成本、不看全名單，待定。
• 離線 / 弱訊號：山下訊號差，成本 / 發票是否需離線暫存後補送（PWA / 本地暫存），第一版線上即時。
• 發票照片儲存：走物件儲存（GCS）＋與 departure_costs / expense_proofs 關聯；保存策略與代收轉付收據分流，待 travelinvoice 對齊。
• 嚮導端通知：行前提醒 / 待補成本提醒是否複用 emails / 罐頭範本推播。

Changelog