租戶設定

一句話：租戶層級設定子系統的 source of truth；新功能若要動設定（例如 團號 的代碼表、訂單派發 的派發模式）應 extend 本檔，而非各自描述。

畫面（UI = wireframe）：../apps/wireframes/app/admin/settings/page.tsx

1. 範圍與定位

設定是 租戶層級（tenant-scoped）：每個租戶 DB 一列 singleton（tenant_settings.id = 'singleton'），整個租戶共用。

重要：本系統沒有 per-user 個人設定表。 使用者個人層級只有：

• better-auth 帳號（email / 密碼 / 未來 2FA，存各租戶 DB 自己的 user 表，與商業表同庫；無共享 auth_db）
• 會員資料（member_profiles，見 會員）

凡是「整個旅行社的設定」一律進 tenant_settings；凡是「某個人的偏好」目前無對應載體（YAGNI，真需要時再開 user_preferences）。

2. 資料模型

tenant_settings 單例表，欄位分兩處（符合專案 schema 慣例，見 系統總綱）：

模組開通不在這裡：登山 / 海外模組「有沒有開通」是平台方決策，存 control_db.tenant（非 tenant_settings），由 provisioning CLI 管。租戶端只能唯讀看自己方案含哪些模組。見 模組化 §3.1。

派發兩欄（assignment_mode / default_assignee_user_id）已扶正進 drizzle schema（穩定業務欄位一律直接進 schema/business.ts，見 系統總綱）；setup-business-extras.ts 現只 idempotent 建立 singleton 列、不再 ALTER 這兩欄。getTenantSettings 仍以顯式欄位清單的 raw SQL 讀取（避免 schema diff 意外遮蔽）。

3. 存取層

packages/core/src/settings/admin-repo.ts：

• getTenantSettings(db): TenantSettingsRow — 讀 singleton，不存在則 lazy insert
• updateTenantSettings(db, input) — 公司 / Email / 站台 SEO 欄位 partial update（只 patch 表單實際帶到的欄位，缺欄不動 → 各 tab 互不洗資料）；SEO 三欄（site_tagline / seo_default_description / og_image_url）由 seo tab 的 updateSeoSettingsAction 呼叫
• updateAssignmentSettings(db, input) — 派發模式子集（單獨 action / form path）

第一個參數一律 db: ScopedDb（branded type，見 系統總綱）。

4. UI 與權限

/admin/settings（src/app/(admin)/admin/settings/page.tsx），13 個 tab（順序同 code）：

進階會計模組閘（accounting-module §5/§6）：收款帳戶（accounts，含費用路由）/ 費用類別（expense-categories）/ 內外帳費率（ledger-fees）三個 tab 屬 module_accounting。accountingActive(modules) 為 false 時三個 tab（trigger + content）server 端不渲染、目錄資料不抓，其 write action 亦掛 requireAccountingModule() fail-closed。accountant 於 module OFF 無任何可管 tab → 顯示「尚未開通進階會計模組」空狀態；admin 仍看得到其餘非會計 tab。

權限：進站閘 = requirePermission('receiving_account.manage')（admin 走 wildcard、accountant 通過；op / sales 被擋在整頁外）。不再是舊的整頁 role.manage —— F1 把收款帳戶管理從對帳頁移入本頁後，若仍用 role.manage（admin only）會把持有 receiving_account.manage 的 accountant 一併擋在整頁外。進站後再用 isAdmin（hasPermissionForRole(..., 'role', 'manage')）二次守門敏感 tab：admin 看全部 13 tab；accountant 只看得到「收款帳戶」+「費用類別」兩 tab（後者再 gate operating_expense.read），其餘 admin-only tab 不渲染、props 不外漏（defaultValue 對 accountant 落在 accounts）。寫入 action 各自 requirePermission（敏感 tab 對應 role.manage，帳戶 / 費用類別對應 receiving_account.manage / operating_expense.manage）。每次寫入記 audit_log（tenant_settings.update / tenant_settings.assignment_mode.change 等）。

付款憑證已 per-tenant（KMS envelope 加密存租戶 DB，/admin/settings 付款 tab 自填 write-only）。郵件憑證決議維持平台級（寄信是平台代履行的服務職責，與「錢進租戶帳戶」的 ECPay 本質不同）—— per-tenant 的是寄件身分（email_from / email_reply_to / 自有寄件 domain），見 emails。

5. 擴充點（未來設定相關功能掛這）

• 團號：region / airline 代碼表、團號規則 → 新增設定區塊 + 表
• 訂單派發：已落地的派發模式（第四種「依目的地分配」UI 已留 disabled placeholder）
• 模組化：登山 / 海外模組開通由平台方控制（control_db，provisioning CLI），settings 只唯讀顯示方案範圍 —— 不是租戶可自改的設定
• feature flags（未來多租戶規模化）：tenant_settings.feature_* 欄，透過 CLI 改（見 memory wildtw-phase2-multitenant-strategy）
• 開發者 tab（API 金鑰自助申請 + CLI session 檢視 / 撤銷）：設計定案於 tenant-cli §3.1（@better-auth/api-key、PAT 式綁使用者、單一 Authorization: Bearer header 以 toko_sk_ 前綴分派、api_key.manage）；MVP 建立限 admin（settings 既有進站閘不動；開放 sales / op 自建連同 UI 入口列 tenant-cli §11 開放議題）。wireframe 已有（settings 線稿「開發者」tab），code 未實作。資料不進 tenant_settings（key 存 plugin 的 apikey 表、CLI session 即 better-auth session 表）

---

Changelog