系統設計總綱

一句話：本系統的現行總覽——系統邊界、租戶架構、核心資料模型、安全不變式與主要模組入口；精確欄位以 code 為準，完成度以 roadmap 為準。

1. 產品邊界

系統的目標是取代舊電商平台（BVShop）與人工 Google Sheet 之間最核心的斷點：

• 公開站上架 tour / lodging；
• 會員登入、報名、結帳、同意書；
• 後台訂單、旅客、付款、請款核簽、團控基本作業；
• append-only audit / consent；
• 多租戶本地可跑通，平台化架構已鋪好。

2. 架構

• Next app 負責 UI / route handler / server actions。
• packages/core 是資料與服務層 workspace package，透過 @toko-cloud/core/* import。
• Schema 集中在 packages/core/src/schema/business.ts 與 control.ts。
• app 目錄只留 UI、hooks、src/lib/utils.ts 與 MDX render helpers。

3. 多租戶

• control_db：平台租戶目錄、domain、subscription、module 授權。
• 每租戶一個 <tenant>_db：auth 表與商業表同庫。
• apps/web/src/proxy.ts 由 host 反查 control DB，寫入 x-tenant-db 與 module headers；查無或停用 fail closed。
• Server 端用 getCurrentTenantDb() 取得 tenant DB；repo first arg 為 db: ScopedDb。
• 商業表不加 tenant scope 欄位；DB 即租戶邊界。

詳細設計見 tenant-architecture。

4. Auth / RBAC

• better-auth per-tenant instance，由 getAuthForTenant(dbName) 快取。
• auth 表與商業表同庫，使用同一份 user FK。
• RBAC 用 better-auth admin plugin + createAccessControl。
• Permission 格式為 resource.action，statement catalog 在 packages/core/src/permissions-ac.ts。
• 角色集：admin / sales / op / accountant / customer。

5. 訂單與金流

• orders：訂單是 operational shell；商品在 order_lines；產品細節在 tour_booking_lines / lodging_booking_lines。
• order-money-model：金流是七層分類帳；應收、收款計畫、意圖、嘗試、現金、退款、出款核簽分離。
• trip-pricing：tour 價格政策與訂金規則。
• lodging-inventory：旅宿 / 房型 / 每晚庫存。
• lodging-direct-booking：訂房成交 flow。
• control-finance：團控掛帳、成本、promo 與 payables 請款核簽。

6. Append-Only 與 Race-Safe

• audit_log 與 consent_signatures append-only。
• 財務真相如 charge lines / cash transactions 採 append-only discipline，改錯以反向列表達。
• Tour 席次預留用 conditional update + CHECK constraint。
• Lodging 每晚庫存用 per-night conditional update + CHECK constraint。
• order number 由 per-DB sequence + SQL function 產生。

7. Design System

• 公開站使用 src/components/ui/* 與 src/app/globals.css token。
• 後台 primitive 用 @toko-cloud/ui/*（packages/ui workspace 套件）、domain 元件用 @/components/admin/*，搭配 Base UI primitives 與 .admin-scope token。
• 後台 page/route code 不直接寫裸 form/table/button primitives；治理細節見 admin-design-system。

8. 模組

平台授權模組：

• module_climbing：登山審核、前置文件、裝備等。
• module_overseas：護照、證件效期、海外流程。
• module_lodging：訂房庫存、直訂、行程配套住宿。

模組 gate 詳見 modules。

9. Payment Provider

• 本地可用 test provider；外部 provider 以 adapter 接入。
• ECPay 是 provider adapter，不是 schema 設計中心。
• 付款事實只在 payment_transactions；pending / failed / expired 等嘗試留在 attempts / provider events。

10. Changelog