模組化

一句話：把非通用的功能（登山 / 海外 / 訂房 / 抽籤）拆成各自獨立的可選模組、疊在通用核心之上；模組是否開通 = 平台方（control plane）的商業決策（對應 SaaS 方案，租戶不可自行開啟），已開通的前提下登山 / 海外再由租戶逐行程決定要不要套、抽籤由梯次 allocation_mode 決定哪梯走（同社混賣登山團 + 一般團）。

畫面（UI = wireframe）：settings（方案模組唯讀面板，現階段唯一前端觸點）

• 關聯：幾乎所有功能 spec（核心/模組歸類見 §2）· tenant-architecture（control_db + proxy）· trip-pricing（行程層欄位同 PR）· settings（唯讀顯示方案模組）
• 動機來源：2026-05-30 user —「旅行社不一定只賣登山，要適度模組化才能拆開販售」。兩個拆售情境都要：① 平台賣 ERP 給其他旅行社（SaaS，平台決定開哪些模組）② 荒野自己型錄混賣一般旅遊（逐行程套）。

1. 五個可選模組

登山模組是獨立可拆模組（2026-06-23 user 裁決）：抽掉登山模組，基礎功能（下單 / 金流 / 出團準備核心 / 對帳 / 分房 / 住宿）照常可用。登山模組專屬 = 裝備租借 + 抽籤(lottery) + 入山/入園/山屋/登山險 deadline + 登山分級審核(climbing-screening) + 人頭使用次數限制(permit 配額)。出團準備的核心骨幹（對款 / 派車 / 餐食 / 投保 / 換領隊）不屬登山模組 —— 那是所有出團團都要的通用流程（見 departure-prep 的核心 vs 登山子集分界、§3.3）。

登山 / 海外是疊在「行程」上的能力層（同一條 tour 加不加）；訂房 / 抽籤是子系統（訂房賣住宿、抽籤介接國家公園抽籤）—— 四者都由平台授權開關，但訂房 / 抽籤的 gate 只到「整個子系統開不開」（無逐行程旗標，granularity 各是房型存量 / 梯次 allocation_mode，見 §3.2）。

登山 vs 海外為何拆兩個而非一包：兩者各自獨立——一條行程可能只需其一：

綁成單一「進階」開關 → 京都自由行會多出「入山證」欄、玉山團會多出「護照」欄。故必須兩個獨立開關。

2. 核心 vs 模組（功能歸類）

改任何 spec 前，先確認它屬核心還是模組：模組功能必須受 §3 的 gate，不可預設啟用。

🟦 核心（任何旅行社都有，與登山/海外無關）

order-assignment · trip-pricing（直客/同業價·訂金/尾款·包團·費用含不含）· control-finance（payables 請款核簽）· dashboard / leaderboard · member-ownership（CRM/同業）· group-code · settings · content-authoring · room-assignment（分房 = 任何含住宿團都需要，含 travelers.gender 硬約束）· traveler-validation（身分證/緊急聯絡人/金額 = 通用 PII）· consent（同意書框架本身通用）· departure-prep 核心骨幹（對款唯讀派生 / 派車 / 餐食 / 投保旅平·旅責 / 換領隊 = 所有出團團都要，不 gate；見 departure-prep）

🟩 登山模組（受登山 gate）

climbing-screening · equipment-inventory（裝備租借 + 庫存彙總）· departure-prep 的登山專屬子集（入山證 / 入園證 / 山屋床位核准證 deadline + 許可證文件 + 登山險 deadline；非整個 departure-prep）· 人頭使用次數限制（國家公園 permit 配額，奇萊南華 / 嘉明湖 / 北大武，以身分證計次；enforcement 隨 climbing-screening / lottery epic）

🟧 海外模組（受海外 gate）

document-expiry（護照效期） · passport-ocr

🟪 訂房模組（受訂房 gate）

lodging-inventory（旅宿主檔 + 房型 + 每晚共用庫存 + 日曆價）· lodging-direct-booking（散客直訂 + orders 重塑）· lodging-tour-package（行程配套住宿）

🟥 抽籤模組（受抽籤 gate）

lottery-integration（入園抽籤介接：推應募名單 / 收中籤結果 / 觸發下游）· backup-itinerary-failover（未中籤自動轉備案行程）

🟫 進階會計模組（受 module_accounting gate）

payment-accounts-reconciliation · account-settlement · currency-exchange · operating-expenses · internal-external-ledger 的淨利 / 分析面 · control-finance 的出款批次 / 匯款檔（§5.5 / §5.6）。掛帳台帳（訂單應收 + departure_costs 成本掛帳含代墊/憑證兩金額 + payables 請款核簽 + 團控毛估 + Excel 匯出）留核心——拆分點與歸屬 SSOT 見 accounting-module。internal-external-ledger / control-finance 橫跨邊界（登記核心 / 分析結算模組）。

3. 兩層 gate 機制

某模組功能對一條行程生效 ⟺ 平台層授權開（control plane）且 行程層旗標開（租戶設）。

3.1 平台層授權（control plane —— 平台方決定，租戶不可改）

模組是否開通給某租戶 = 平台的商業決策（對應訂閱方案），故放 control_db（平台目錄），由 provisioning CLI 管理。不放 tenant_settings —— 那是租戶自己可編輯的設定，放那裡等於人人自助開通，破壞拆售。

// packages/core/src/schema/control.ts — control_db `tenant` 表 append（平台層）
/** 平台授權：此租戶是否開通各模組（對應訂閱方案）。租戶端唯讀。 */
moduleClimbing: boolean("module_climbing").notNull().default(false),
moduleOverseas: boolean("module_overseas").notNull().default(false),
moduleLodging: boolean("module_lodging").notNull().default(false),
moduleLottery: boolean("module_lottery").notNull().default(false),
// 抽籤模組（13-task SDD 已落地：control_db 欄 + proxy active list + TenantModules.lottery + lotteryActive() + requireLotteryModule）。
// 進階會計模組（F0 已落地此欄 + helper accountingActive / requireAccountingModule；
// F6 掛帳台帳 .xlsx 匯出核心 + 各進階會計頁掛閘）。荒野 = true（DEV_TENANT_MODULES 含 accounting）。
moduleAccounting: boolean("module_accounting").notNull().default(false),

• 預設 false：新租戶 = 乾淨的通用旅行社 ERP；平台依方案開通。
• 管理 = provisioning CLI：bun run tenant set-modules --slug <s> --enable climbing[,overseas]（與既有 tenant create / suspend / set-domain 同層，直連 control_db）。
• /admin/settings 不可編輯：最多唯讀顯示「你的方案包含：登山模組」（settings）。要開/關走平台 CLI。
• 未來可由 control_db.subscription 方案等級自動帶（方案→模組 entitlement 映射）；本 spec 先用 tenant 上的旗標。

租戶 app 怎麼讀到授權（沿用既有 proxy 解析路徑）：apps/web/src/proxy.ts 本來就用 host 反查 control_db.tenant_domain 取 db_name + 檢查 tenant.status；一併取模組旗標，經 NextResponse.next({ request: { headers }}) 寫 anti-tamper header x-tenant-modules（同 x-tenant-db 慣例：一律覆寫 client 值）。dev 用 DEV_TENANT_MODULES env fallback。

3.2 行程層旗標（租戶自己設 —— 已授權前提下逐行程套）

trips 新增兩個 boolean（drizzle schema，與 trip-pricing / climbing-screening 的 trips 欄位同一 PR）：

// packages/core/src/schema/business.ts — trips append
/** 此行程是否為登山團（顯示審核分數/入山/裝備等登山欄位與流程）。 */
isClimbing: boolean("is_climbing").notNull().default(false),
/** 此行程是否出國（顯示護照效期/OCR）。 */
isOverseas: boolean("is_overseas").notNull().default(false),

• 行程旗標只能在平台已授權該模組時於 trip-edit 設為 true（UI：未授權 → checkbox 不出現、視同 false）。
• 訂房模組無逐行程旗標：它是獨立產品線（賣住宿不是行程），gate 只到「整個訂房子系統開不開」—— module_lodging on → 出旅宿 nav / 直訂 / 配套；off → 整組不存在。物業 / 房型「存不存在」就是它的細粒度。

3.3 生效判定（單一 helper）

// packages/core/src/modules.ts
export interface TenantModules {
  climbing: boolean;
  overseas: boolean;
  lodging: boolean;
  lottery: boolean;
}

/** 平台授權的模組（來自 control_db，經 proxy 注入的 x-tenant-modules header 讀取）。
 *  async + cache(headers())，同 getCurrentTenantDb 慣例（不傳 ctx）；header 缺失 → 全 false（fail-closed）。 */
export const getTenantModules: () => Promise<TenantModules>;

/** 此行程是否套登山功能（審核器/入山/裝備）= 平台授權 且 行程是登山團。
 *  caller 先 `const modules = await getTenantModules()` 再傳入（helper 不自呼叫，省去每次 await）。 */
export function climbingActiveFor(trip: { isClimbing: boolean }, modules: TenantModules): boolean {
  return modules.climbing && trip.isClimbing;
}
/** 此行程是否套海外功能（護照）= 平台授權 且 行程出國。 */
export function overseasActiveFor(trip: { isOverseas: boolean }, modules: TenantModules): boolean {
  return modules.overseas && trip.isOverseas;
}
/** 訂房子系統是否啟用（無逐行程旗標，純看平台授權）。 */
export function lodgingActive(modules: TenantModules): boolean {
  return modules.lodging;
}
/** lodging WRITE server action 開頭的模組閘：off 時即使持 lodging.manage 也擋下。 */
export async function requireLodgingModule(): Promise<void>; // throws 'module_disabled' if off

抽籤模組（已落地，13-task SDD）：TenantModules 現含 climbing / overseas / lodging / lottery。lotteryActive(modules) = return modules.lottery；requireLotteryModuleOr404 在所有手動裁決 write action 入口 fail-closed（不只藏 nav）。module_lottery 欄在 control schema + proxy active list 均已加入。

進階會計模組（已落地）：TenantModules 含 accounting；accountingActive(modules) = return modules.accounting；requireAccountingModule()（off 時 throw 'module_disabled'，比照 requireLodgingModule）+ 頁閘 requireAccountingModuleOr404()（off → 404）；control schema 已加 module_accounting、proxy active 推導已納入 accounting。子系統型 gate（無逐行程旗標，比照訂房）。拆分點與涵蓋範圍見 accounting-module。

各模組 spec 的觸發點都先過這個閘：

• climbing-screening：runOrderScreening 先判 climbingActiveFor → false 則 verdict not_required、不寫審核（取代原「grade NULL → not_required」隱性判斷）。
• equipment-inventory：裝備租借 / 需求調查 / 跨梯次彙總 UI 與查詢只對 climbingActiveFor 的梯次跑。
• departure-prep：只有登山專屬子集過閘 —— 入山/入園/山屋/登山險 deadline + 許可證文件區、人頭使用次數限制只對 climbingActiveFor 的梯次顯示；核心骨幹（對款 / 派車 / 餐食 / 投保 / 換領隊）不過閘，任何梯次都有。
• document-expiry / passport-ocr：只對 overseasActiveFor 的行程顯示護照欄與效期警示。
• lottery-integration / backup-itinerary-failover：lotteryActive() 為 false 時，梯次不出現 allocation_mode=lottery 選項、抽籤介接 / 轉備案功能整組不存在。

4. 既有設計已半支援

• climbing-screening 已 null-gated（行程沒評鑑分數 → not_required）。本 spec 升級為明確旗標 is_climbing，UI 可據此整組顯隱。
• traveler-validation 性別檢查已是條件式。
• 多租戶 = control_db + DB per tenant + proxy header 注入，天生能讓平台層授權下放到租戶 app（同 x-tenant-db 機制）。

→ 模組化是平台層加授權旗標 + proxy 注入 + 行程層標旗標 + UI 顯隱，不是打掉重練。

5. UI 顯隱規則

• nav（登山/海外）：目前無登山/海外專屬 nav 項（審核器在訂單派發頁、入山在團控、護照在團控），故 nav 不需大改；顯隱主要在頁內區塊。未來若加專屬 nav（如「裝備調度」），其 _shell.js nav 項需依平台授權顯隱。
• 訂房模組（整組顯隱）：module_lodging on → 出「旅宿管理」nav（_shell.js）+ trip-edit「配套住宿」區 + 直訂建單；off → 整組不存在。物業/房型存不存在是其細粒度（無逐行程旗標）。

6. 行程類型 UI（trip-edit）

trip-edit 基本資料頂端加「行程類型」區（checkbox 僅在平台已授權對應模組時出現）：

行程類型（決定顯示哪些欄位與流程）
☑ 登山團   ☐ 海外團

• 勾「登山團」→ 顯示審核評鑑分數 / 高山經驗 / 分級標籤欄群（climbing-screening）。
• 勾「海外團」→ 顯示護照效期相關欄（document-expiry）。
• 兩個都不勾 = 一般旅遊團，只剩核心欄位（名稱/價格/訂金/含不含/分房）。
• 平台未授權某模組 → 對應 checkbox 不出現（該租戶根本不做這類團）。

7. 影響範圍

8. 未決事項

9. 連結

• 動機：user 2026-05-30（拆售/混賣 + 「模組應由平台方決定」）
• 平台層：tenant-architecture（control_db + proxy header 注入 + provisioning CLI）
• 租戶層唯讀：settings
• 行程層：trip-pricing（trips 欄位同 PR）
• 被 gate 的模組：climbing-screening、departure-prep、equipment-inventory（登山）；document-expiry、passport-ocr（海外）；lodging-inventory、lodging-direct-booking、lodging-tour-package（訂房）；lottery-integration、backup-itinerary-failover（抽籤）

Changelog