# ROLAC Church Management System — Project Planning
**教會:** River Of Life Christian Church In Arcadia (ROLAC)
**規模:** 50–100 人
**文件版本:** v0.3 (2026-05-29)
---
## 目錄
1. [專案目標](#1-專案目標)
2. [系統模組總覽](#2-系統模組總覽)
3. [模組詳細規劃](#3-模組詳細規劃)
- 3.1 [教友管理 (Member Management)](#31-教友管理-member-management)
- 3.2 [權限控管 & 多角色 (RBAC)](#32-權限控管--多角色-rbac)
- 3.3 [小組架構 (Cell Groups / Ministry Structure)](#33-小組架構-cell-groups--ministry-structure)
- 3.4 [服事表 (Service Roster)](#34-服事表-service-roster)
- 3.5 [教會首頁 CMS](#35-教會首頁-cms)
- 3.6 [奉獻追蹤 (Giving / Donations)](#36-奉獻追蹤-giving--donations)
- 3.7 [年度收據 (Annual Giving Statement)](#37-年度收據-annual-giving-statement)
- 3.8 [Audit Log](#38-audit-log)
- 3.9 [報表 (Reports)](#39-報表-reports)
- 3.10 [Ministry Scope](#310-ministry-scope)
- 3.11 [未來 AI 整合](#311-未來-ai-整合)
4. [角色與權限矩陣](#4-角色與權限矩陣)
5. [資料模型草圖](#5-資料模型草圖)
6. [技術架構建議](#6-技術架構建議)
7. [開發階段規劃 (Roadmap)](#7-開發階段規劃-roadmap)
8. [開放議題 & 待決策](#8-開放議題--待決策)
---
## 1. 專案目標
| 目標 | 說明 |
|------|------|
| 數位化教友資料 | 取代紙本或分散的試算表，集中管理教友資訊 |
| 透明化財務 | 讓奉獻記錄可查詢、可稽核，年底產生合規收據 |
| 強化小組連結 | 清楚呈現小組架構，追蹤出席與服事參與 |
| 簡化行政工作 | 服事排班、通知、報表自動化，減少人工作業 |
| 對外溝通 | CMS 管理教會網站，發佈消息/活動 |
| 安全與稽核 | 完整 Audit Log，細緻的角色權限，保護敏感資料 |
| 可擴展性 | 為未來 AI 功能（關懷提醒、智能報表）預留介面 |
---
## 2. 系統模組總覽
```
ROLAC CMS
├── 公開前台 (Public Website — rolac.org)
│ └── 教會首頁 CMS（雙語）
└── 後台管理 (Admin Portal — app.rolac.org)
├── 教友管理
├── 小組架構 & Ministry Scope
├── 主日出席記錄
├── 服事表
├── 敬拜歌曲庫
├── 代禱事項
├── 奉獻追蹤（含線上奉獻）& 年度收據
├── 支出追蹤 & 報銷
├── 月結對帳
├── 報表
├── Audit Log
├── 權限控管 (RBAC)
└── [未來] AI 整合
```
---
## 3. 模組詳細規劃
### 3.1 教友管理 (Member Management)
**核心資料欄位**
| 欄位群 | 欄位 |
|--------|------|
| 基本資料 | 姓名 (中/英)、生日、性別、照片 |
| 聯絡資訊 | 電話、Email、地址 |
| 教會狀態 | 會員/訪客/前會員、受洗日期、入會日期、離會原因 |
| 家庭關係 | 家庭單元 ID、配偶、子女 |
| 小組歸屬 | 所屬小組、負責牧者/組長 |
| 服事歷史 | 參與服事記錄 |
| 自定義標籤 | 關懷需求、恩賜標籤、語言偏好 (中/英) |
**功能清單**
- 新增 / 編輯 / 軟刪除 教友資料
- 家庭單元管理（一個家庭多位成員）
- 進階搜尋與篩選（按小組、狀態、生日月份…）
- 生日/週年紀念提醒
- 匯入 / 匯出 CSV
- 個人資料變更歷史（誰改了什麼）
---
### 3.2 權限控管 & 多角色 (RBAC)
**設計原則**
- 最小權限原則：每個角色只能存取完成工作所需的資源
- Ministry Scope：部分角色僅能看到自己負責的 Ministry 資料
- 細粒度到 Resource + Action 層級
**預設角色（見第 4 節矩陣）**
> ROLAC 為靈糧堂體制，無長老制。
| 角色 | 中文說明 | 層級 |
|------|----------|------|
| `super_admin` | 系統管理員，全權存取 | 系統 |
| `pastor` | 牧師，全覽教友與財務摘要 | 牧者 |
| `board_member` | 理事，教會治理委員 | 治理 |
| `coworker_chair` | 同工會主席，統籌各事工領袖 | 領導 |
| `ministry_leader` | 事工領袖，僅限自身 Ministry 範圍 | 事工 |
| `district_leader` | 區長，管理轄下多個小組 | 小組 |
| `cell_leader` | 小組長，僅限自身小組 | 小組 |
| `coworker` | 同工，參與指定事工的一般同工 | 同工 |
| `finance` | 財務同工，管理奉獻與支出報表 | 功能 |
| `secretary` | 行政秘書，管理教友資料與排班 | 功能 |
| `worship_leader` | 敬拜領袖，管理歌曲庫與敬拜歌單（Phase 暫緩）| 功能 |
| `member` | 一般教友，查看個人資料與服事表 | 教友 |
| `visitor` | 訪客，僅限公開頁面 | 教友 |
---
### 3.3 小組架構 (Cell Groups / Ministry Structure)
**資料結構（樹狀）**
```
教會 (Church — River Of Life Christian Church In Arcadia)
└── Ministry (事工部門)
└── Cell Group (小組)
└── Member (教友)
```
**ROLAC 實際事工部門（初始種子資料）**
| # | 英文名稱 | 中文名稱 | 主要職責 |
|---|----------|----------|----------|
| 1 | Administration | 行政 | 教會行政、秘書、文件管理 |
| 2 | Preaching | 講道 | 主日講道、查經帶領 |
| 3 | Emcee | 司會 | 主日流程主持 |
| 4 | Worship | 敬拜 | 敬拜帶領、詩歌、樂器 |
| 5 | PPT / Media | PPT／影音 | 投影片製作、直播、錄影 |
| 6 | Sound | 音控 | 現場音響、混音 |
| 7 | Facility | 場地組 | 場地佈置、清潔、設備 |
| 8 | Hospitality | 招待 | 門口招待、訪客關懷、奉獻袋收集 |
| 9 | Children | 兒牧 | 兒童主日學、托兒 |
| 10 | Catering | 餐飲 | 每週愛宴、餐飲採購 |
> 這 10 個 Ministry 為系統初始種子資料（`DbInitializer`），可在後台新增 / 修改。
**功能清單**
- 建立 / 管理 Ministry 與小組層級
- 指派組長與副組長
- 成員歸屬管理（一個教友可屬於多個 Ministry）
- 出席記錄（每次小組聚會）
- 成員轉移與歷史追蹤
- 小組狀態（活躍 / 暫停 / 解散）
- Ministry Scope 權限綁定
---
### 3.3b 主日出席記錄 (Sunday Service Attendance)
> **記錄方式（已確定）：** 招待同工（Greeting Team）統計總人數後，由秘書或招待組長手動輸入。
**統計分類**
| 類別 | 說明 |
|------|------|
| 大人 (Adults) | 成年會眾人數 |
| 青少年 (Teenagers) | 青少年人數 |
| 兒童 (Children) | 兒童主日學人數 |
| 合計 (Total) | 系統自動加總 |
**資料模型**
```
SundayAttendance
├── Id
├── ServiceDate (日期)
├── ServiceType (主日崇拜 / 特別活動 / 節日崇拜)
├── AdultCount
├── TeenCount
├── ChildrenCount
├── TotalCount (computed: Adult + Teen + Children)
├── Notes (備註，例：聖誕主日特別人數)
├── RecordedByUserId (誰輸入)
└── CreatedAt / UpdatedAt
```
**功能清單**
- 每週輸入三個類別人數（簡單表單）
- 合計自動計算
- 月 / 季 / 年 出席趨勢圖
- 出席率計算（以平均或最高值為基準）
- 節日 / 特別活動標記
- 匯出 CSV 供外部報表使用
---
### 3.4 服事表 (Service Roster)
**ROLAC 主日服事槽位（初始種子資料）**
每個槽位屬於一個 Ministry，一次服事可填入一個或多個同工。
| Ministry | 服事槽位 | 人數 | 頻率 |
|----------|---------|------|------|
| 講道 | 講員 Preacher | 1 | 每週 |
| 司會 | 主持人 Emcee | 1 | 每週 |
| 敬拜 | 敬拜帶領 Worship Leader | 1 | 每週 |
| 敬拜 | 敬拜團員 Worship Team | 2–5 | 每週 |
| 敬拜 | 司琴 Pianist | 1 | 每週 |
| PPT/影音 | PPT 操作 Slide Operator | 1 | 每週 |
| PPT/影音 | 攝影 / 直播 Livestream | 0–1 | 每週 |
| 音控 | 音控 Sound Engineer | 1 | 每週 |
| 場地組 | 場地佈置 Setup | 2–3 | 每週 |
| 場地組 | 場地收拾 Teardown | 2–3 | 每週 |
| 招待 | 門口招待 Greeter | 2–3 | 每週 |
| 招待 | 奉獻袋 Offering Collection | 2 | 每週 |
| 兒牧 | 兒童主日學老師 | 1–2 | 每週 |
| 兒牧 | 兒童助教 Assistant | 0–1 | 每週 |
| 餐飲 | 愛宴負責人 Catering Lead | 1 | 每週 |
| 餐飲 | 愛宴協助 Catering Help | 2–4 | 每週 |
**功能清單**
- 定義服事槽位（綁定 Ministry，雙語名稱）
- 每週排班（從教友庫中指派到各槽位）
- 週期性排班範本（每週 / 隔週 / 每月輪換）
- 自動衝突檢查（同一人同一主日多個衝突槽位）
- 缺席替換流程（申請 → 系統建議替補 → 確認）
- Email / Push Notification 服事提醒（服事前 2 天）
- 公開服事表嵌入網站（確認後才公開）
- 服事統計（每人參與頻率）
---
### 3.5 教會首頁 CMS
> **雙語範圍（已確定）：** 網站前台完整支援 **英文 (EN) + 繁體中文 (zh-TW)** 切換。
> 所有可見文字均需提供兩個語言版本，包含 SEO meta 欄位。
**頁面 / 內容類型**
| 類型 | 說明 |
|------|------|
| 首頁 Hero | 輪播橫幅、主題文字（雙語） |
| 關於我們 | 教會簡介、異象、牧師介紹（雙語） |
| 主日資訊 | 時間、地點、Google Map（地址雙語） |
| 消息公告 | 可分類標籤、發佈排程（標題 + 內文雙語） |
| 活動日曆 | 事件列表，可連結報名表單（雙語） |
| 媒體 | 主日講道影片/音訊嵌入（YouTube/Podcast）（標題雙語） |
| 奉獻頁面 | 線上奉獻說明（雙語） |
| 聯絡表單 | 訪客詢問，通知至指定 Email（表單標籤雙語） |
**雙語內容資料模型**
CMS 所有可編輯的文字欄位，一律使用平行欄位儲存：
```
CmsContent
├── Id
├── PageSlug (e.g. "home", "about", "announcements")
├── SectionKey (e.g. "hero.title", "hero.subtitle")
├── ContentType (Text | RichText | ImageUrl | Url)
├── ValueEn ← 英文版本
├── ValueZh ← 繁體中文版本
├── IsPublished
├── PublishAt (排程發佈)
├── UpdatedByUserId
└── UpdatedAt
Announcement
├── Id
├── TitleEn / TitleZh
├── BodyEn / BodyZh (Rich text)
├── Category
├── IsPublished
├── PublishAt
├── ExpiresAt
└── CoverImageUrl
Event
├── Id
├── TitleEn / TitleZh
├── DescriptionEn / DescriptionZh
├── Location (共用，或 LocationEn / LocationZh)
├── StartAt / EndAt
├── RegistrationUrl
└── CoverImageUrl
```
**後台 CMS 編輯器 UI（Admin App）**
每個可編輯欄位都採用**並排雙欄**編輯介面：
```
┌──────────────────────┬──────────────────────┐
│ English │ 繁體中文 │
│ ───────────────── │ ───────────────── │
│ [Welcome to ROLAC] │ [歡迎來到生命之河] │
└──────────────────────┴──────────────────────┘
```
- 兩欄同時顯示，編輯器可獨立輸入
- 儲存時驗證：若只填一種語言，提示警告（但允許儲存）
- 預覽模式可切換 EN / zh-TW 即時檢視
**前台語言切換 UI**
- Header 右上角 `EN | 中` 切換按鈕
- 語言偏好存於 `localStorage`（訪客也記住）
- URL 策略：使用 Angular `i18n` route prefix 或 query param，二擇一：
- 方案 A（推薦）：`rolac.org/en/about` vs `rolac.org/zh/about` — 對 SEO 最友善
- 方案 B：`rolac.org/about?lang=zh` — 實作較簡單
**SEO 雙語支援**
每個頁面在 `` 中加入：
```html
```
- Meta title / description 依當前語言動態注入
- 使用 Angular `Meta` service 或 `ngx-seo`
**技術需求**
- 富文本編輯器：**Quill** 或 **TipTap**（Angular 皆有 wrapper）
- 圖片上傳 → Azure Blob `cms/images/`
- 預覽草稿後才發佈
- 發佈排程（`PublishAt` 欄位 + 背景排程 Job）
---
### 3.6 奉獻追蹤 (Giving / Donations)
**奉獻類型**
- 什一奉獻 (Tithe)
- 感恩奉獻 (General Offering)
- 特別奉獻 (Special/Project，可自訂名稱)
- 慣例奉獻 (Pledge)
**支付方式（完整）**
| 方式 | 類型 | 狀態 | 說明 |
|------|------|------|------|
| **現金 (Cash)** | 線下手動 | ✅ Phase 1 | 信封號碼（選填）、匿名旗標 |
| **支票 (Check)** | 線下手動 | ✅ Phase 1 | 支票號碼 |
| **Zelle** | 線下手動 | ✅ Phase 1 | 交易參考碼，無 API |
| **PayPal (手動)** | 線下手動 | ✅ Phase 1 | Transaction ID 手輸 |
| **Stripe (線上)** | 線上支付 | 🔜 Phase 4 | 信用卡 / Apple Pay / Google Pay |
| **PayPal Checkout (線上)** | 線上支付 | 🔜 Phase 4 | PayPal 按鈕嵌入 |
**資料模型重點欄位**
```
Giving
├── Id
├── MemberId (可為 null → 匿名 / 訪客線上奉獻)
├── GiverName (線上匿名奉獻者填寫的名字，可 null)
├── GiverEmail (線上奉獻用，發確認信)
├── GivingDate
├── Amount (decimal, 原始金額)
├── FeeAmount (decimal, 手續費，預設 0)
├── NetAmount (computed: Amount − FeeAmount)
├── GivingCategoryId (Tithe / Offering / Special…)
├── PaymentMethod (Cash | Check | Zelle | PayPal | Stripe | PayPalCheckout)
├── PaymentSource (Manual | OnlineStripe | OnlinePayPal)
├── ReferenceNumber (支票號 / Zelle ref / Stripe PaymentIntent ID / PayPal txn)
├── EnvelopeNumber (現金信封號碼，選填)
├── IsAnonymous (bool)
├── FundProjectId (特別奉獻專案，可 null)
├── IsRecurring (bool, 定期奉獻)
├── RecurringScheduleId (FK → GivingRecurringSchedule，可 null)
├── Notes
├── RecordedByUserId (手動輸入者；線上奉獻為 null)
└── StripeEventId (防重複，Webhook idempotency key)
GivingRecurringSchedule ← 定期線上奉獻
├── Id
├── MemberId
├── Amount
├── GivingCategoryId
├── Frequency (Weekly | BiWeekly | Monthly)
├── NextChargeDate
├── StripeSubscriptionId
├── Status (Active | Paused | Cancelled)
└── CreatedAt
```
**功能清單**
- 手動記錄奉獻（含現金/支票/Zelle/PayPal）
- **主日奉獻袋批次輸入**（Phase 1，見 §3.6c）
- 線上奉獻頁（Phase 4，見 §3.6b）
- 定期自動奉獻（Stripe Subscription，Phase 4）
- PayPal / Stripe 手續費分開記錄，IRS 收據用 **NetAmount**
- 奉獻目標 / 專案進度條
- 個人奉獻歷史（本人可查）
- 月結對帳報表
---
#### 3.6c 主日奉獻袋批次輸入 (Sunday Offering Batch Entry — Phase 1)
**業務場景**
主日聚會結束後，財務同工收到奉獻袋，需要逐一開袋，將每筆現金信封或支票對應到教友姓名，登入系統記錄，年底才能產生個人奉獻收據。
**工作流程**
```
財務同工開啟「主日奉獻錄入」
│
▼
選擇日期（預設今天）
│
▼
┌───────────────────────────────────────┐
│ 逐筆快速錄入介面 │
│ ───────────────────────────────── │
│ 搜尋教友：[_______________] ← 即時搜尋 │
│ 奉獻類型：[Tithe ▼] │
│ 支付方式：[● 現金 ○ 支票] │
│ └─ 現金：信封號碼 [___] (選填) │
│ └─ 支票：支票號碼 [___] (必填) │
│ 金額： [$________] │
│ 備注： [_______________] (選填) │
│ │
│ [+ 新增] [匿名奉獻] │
│ ───────────────────────────────── │
│ 已錄入 12 筆 | 小計：$1,250.00 │
└───────────────────────────────────────┘
│
▼
所有信封錄入完成
│
▼
對帳確認頁（顯示今日所有筆數 + 總計）
財務同工核對實際金額 = 系統合計
│
▼
確認送出 → 系統 Bulk Insert
```
**UI 設計要點**
| 要點 | 說明 |
|------|------|
| 教友搜尋 | 即時搜尋（姓名中英文 / 拼音），顯示照片方便確認 |
| 鍵盤優先 | Tab 鍵在欄位間切換，Enter 新增，不需滑鼠 |
| 支付方式切換 | 選「支票」才出現支票號碼欄；選「現金」才出現信封號欄 |
| 匿名奉獻 | 一鍵匿名，不需搜尋教友，仍記錄金額供帳目平衡 |
| 即時小計 | 每新增一筆，當日累計金額即時更新 |
| 對帳視圖 | 最後一步顯示完整清單，供財務核對實際鈔票 / 支票 |
| 可編輯 | 送出前可點任一筆修改或刪除 |
| 送出後修改 | 需財務角色才可編輯，修改記錄進 Audit Log |
**資料模型補充**
```
OfferingSession ← 每次主日錄入為一個 Session
├── Id
├── SessionDate (主日日期)
├── Status (Open | Submitted)
├── CashTotal (computed)
├── CheckTotal (computed)
├── TotalAmount (computed)
├── SubmittedByUserId
├── SubmittedAt
└── Givings[] (關聯當次錄入的所有 Giving 記錄)
```
> **為什麼需要 OfferingSession？**
> 將同一主日的所有奉獻筆數綁在一起，方便財務同工核對「這次錄入的總計」是否與實際收到的現金＋支票金額吻合，在確認前可以整批修改，確認後進 Audit Log。
---
#### 3.6d 支出追蹤 & 報銷 (Expense Tracking & Reimbursement — Phase 1)
**業務場景**
| 場景 | 說明 |
|------|------|
| 代墊報銷 | 同工先自掏腰包買教會物品，事後憑收據向教會申請報帳 |
| 廠商付款 | 教會直接開支票給廠商（例：每週愛宴午餐外燴）|
| 雜支現金 | 小額現金支出（如停車費、文具）|
**支出流程**
```
【場景 A：代墊報銷】
同工提交報銷申請
（日期、金額、類別、說明、收據照片）
│
▼
財務同工審核
├── 批准 → 開支票 / 現金還款給同工
│ 記錄支票號碼 + 付款日期
└── 退回 → 填寫退回原因
【場景 B：廠商直接付款（如愛宴）】
財務同工直接建立支出記錄
（廠商名稱、金額、支票號碼、日期、類別）
→ 狀態直接為「已付款」
```
**支出分類架構（兩層 + Ministry）**
每筆支出標記三個維度：
```
Ministry（事工部門） × 大類（Category Group） × 子項目（Sub-Category）
範例：
敬拜事工 > 影音 > 設備
敬拜事工 > 影音 > 教育訓練
餐飲部門 > 餐飲 > 消耗品
餐飲部門 > 餐飲 > 出餐費用
行政 > 辦公 > 文具耗材
行政 > 人事 > 薪資
兒童事工 > 教材 > 印刷費用
```
> **設計原則：** 大類（影音、餐飲）是跨 Ministry 共用的，同一大類可出現在不同 Ministry。
> 例如：敬拜事工和兒童事工都可能有「影音 > 設備」的支出。
**資料模型**
```
ExpenseCategoryGroup ← 大類（Level 1）
├── Id
├── NameEn / NameZh (影音 A/V、餐飲 Food、辦公 Office…)
├── SortOrder
└── IsActive
ExpenseSubCategory ← 子項目（Level 2）
├── Id
├── ExpenseCategoryGroupId (FK → ExpenseCategoryGroup)
├── NameEn / NameZh (設備 Equipment、教育訓練 Training、出餐費用 Catering…)
├── SortOrder
└── IsActive
Expense ← 每筆支出
├── Id
├── ExpenseDate
├── Description (說明)
├── Amount
├── MinistryId (哪個事工部門承擔此支出)
├── CategoryGroupId (大類，FK → ExpenseCategoryGroup)
├── SubCategoryId (子項目，FK → ExpenseSubCategory)
├── PaymentMethod (Cash | Check | CreditCard | BankTransfer)
├── CheckNumber (若 PaymentMethod = Check)
├── PayeeType (Vendor | StaffReimbursement)
├── PayeeName (廠商名稱 或 同工姓名)
├── MemberId (若 PayeeType = StaffReimbursement → 指向同工)
├── ReceiptBlobPath (收據照片，Azure Blob: finance/receipts/)
├── Status (Draft | PendingApproval | Approved | Paid | Rejected)
├── RejectionReason
├── SubmittedByUserId
├── ApprovedByUserId
├── ApprovedAt
├── PaidAt
├── Notes
└── CreatedAt
```
**預設大類 & 子項目（種子資料，可在後台自訂）**
| 大類（EN / 中）| 子項目 | 常用於 Ministry |
|----------------|--------|-----------------|
| Equipment / 設備 | 購置 · 租借 · 維修 | 敬拜、PPT/影音、音控、場地組、兒牧 |
| Consumables / 耗材 | 電池 · 配件 · 清潔用品 · 文具 | 音控、PPT/影音、場地組、招待、行政 |
| Food & Beverage / 餐飲 | 出餐費用 · 食材採購 · 器具 · 消耗品 | 餐飲、兒牧 |
| Training / 教育訓練 | 課程費用 · 書籍 · 研討會 · 差旅 | 敬拜、PPT/影音、音控、兒牧 |
| Materials / 教材 | 印刷費用 · 手工材料 · 版權購買 | 兒牧、講道、司會 |
| Facility / 場地 | 場地租金 · 水電 · 財產保險 · 裝飾 | 場地組、行政 |
| Printing / 印刷 | 週報 · 程序單 · 海報 | 行政、招待、兒牧 |
| Missions / 宣教 | 奉獻轉帳 · 宣教士支援 · 差旅 | 行政 |
| Benevolence / 關懷 | 急難救助 · 慰問禮品 · 探訪費用 | 行政 |
| Other / 其他 | 雜支 | 所有 |
| Personnel / 人事 | 薪資 · 薪資稅費 · 員工福利 · 勞工保險 · 酬庸 · 同工進修 · 外包勞務 | 行政 |
> **分類備注：** `Facility > 財產保險` 為建築物／場地責任險；員工健保等歸 `Personnel > 員工福利`。同工代墊報銷（`StaffReimbursement`）依實際購買物選大類，薪資／福利付款才歸人事。
**Ministry × 大類 常用對應（供財務設定參考）**
| Ministry | 最常用大類 |
|----------|-----------|
| 行政 Administration | 人事 · 辦公耗材 · 印刷 · 場地 · 宣教 · 關懷 |
| 講道 Preaching | 教材 · 書籍（Training） |
| 司會 Emcee | 印刷（程序單） |
| 敬拜 Worship | 設備 · 教育訓練 · 耗材 |
| PPT/影音 Media | 設備 · 耗材 · 教育訓練 |
| 音控 Sound | 設備 · 耗材 · 教育訓練 |
| 場地組 Facility | 設備 · 場地 · 耗材（清潔） |
| 招待 Hospitality | 耗材 · 印刷（程序單） |
| 兒牧 Children | 教材 · 設備 · 餐飲 · 教育訓練 |
| 餐飲 Catering | 餐飲（出餐費用 · 食材 · 器具） |
**UI 選擇流程（錄入時）**
```
選擇 Ministry → 選擇大類 → 選擇子項目
[餐飲 ▼] [餐飲 ▼] [出餐費用 ▼]
[敬拜 ▼] [設備 ▼] [購置 ▼]
```
- 大類清單不依 Ministry 過濾（保持靈活）
- 選定大類後，子項目自動篩選對應選項
- 找不到適合子項目 → 選「其他」並填說明
**狀態流轉**
```
廠商直接付款： (finance 直接建立) → Paid
同工報銷申請： Draft → PendingApproval → Approved → Paid
└─────────────────→ Rejected
```
**月底對帳（月結報表）**
這是整個財務閉環的核心：
```
月結對帳表（MonthlyStatement）
期初餘額（Opening Balance） $X,XXX.XX
+ 本月奉獻收入（從 Giving 表加總） $X,XXX.XX
+ 其他收入（手動補充） $ .00
− 本月支出（從 Expense 表加總） $X,XXX.XX
= 帳面期末餘額（Calculated Closing） $X,XXX.XX
銀行對帳單餘額（Bank Statement Balance） $X,XXX.XX
差異（Difference） $ 0 ← 目標為零
```
```
MonthlyStatement
├── Id
├── Year / Month
├── OpeningBalance (手動輸入上月結餘，首月由財務設定)
├── TotalGiving (auto: SUM Giving WHERE month)
├── TotalOtherIncome (手動補充)
├── TotalExpenses (auto: SUM Expense WHERE month AND Status=Paid)
├── CalculatedClosingBalance (computed)
├── BankStatementBalance (財務同工手動輸入)
├── Difference (computed: Calculated − Bank)
├── Notes
├── Status (Draft | Reconciled)
├── ReconciledByUserId
└── ReconciledAt
```
> **Phase 3 預算功能（MinistryBudget）預留欄位：**
> 分類架構現在就做好，Phase 3 只需增加 `MinistryBudget` 表，
> 按 Ministry + CategoryGroup + SubCategory 設定年度預算額，
> 對比實際 Expense 計算使用率，不需改動 Expense 結構。
**收據照片上傳（Azure Blob）**
```
finance/
└── receipts/
└── {year}/{month}/{expenseId}-{filename}.jpg
```
- 使用 Capacitor Camera 拍攝，即時上傳
- 或桌機版直接上傳圖片檔
- Private，API 產生 SAS URL（限財務角色存取）
**權限**
| 操作 | 角色 |
|------|------|
| 提交報銷申請 | 所有登入用戶（含 member） |
| 審核 / 批准 | `finance`、`super_admin` |
| 建立廠商直接付款 | `finance`、`super_admin` |
| 查看所有支出 | `finance`、`pastor`、`super_admin` |
| 查看人事類支出 | `finance`、`pastor`、`super_admin`（事工領袖不可見） |
| 查看自己的申請 | 提交者本人 |
| 月底對帳 | `finance`、`super_admin` |
---
#### 3.6b 線上奉獻頁 (Online Giving — Phase 4)
**推薦：Stripe（主要）+ PayPal 按鈕（次要）**
| 比較項目 | Stripe | PayPal |
|----------|--------|--------|
| Nonprofit 費率 | **1.5% + $0.30**（需申請 Stripe Nonprofit Rate） | **1.99% + $0.49**（PayPal Giving Fund for 501c3） |
| C# SDK | ✅ 官方 Stripe.net | ✅ PayPalCheckoutSdk |
| Apple Pay / Google Pay | ✅ 原生支援 | ❌ 需另外設定 |
| Webhook 可靠性 | ✅ 非常成熟 | ⚠️ 歷史上較多問題 |
| 定期奉獻 | ✅ Stripe Subscription | ⚠️ 較複雜 |
**線上奉獻頁流程（rolac.org/give）**
```
訪客/教友進入 /give 頁面
│
▼
選擇奉獻��金（Tithe / General / Special）
選擇金額（預設選項 $50 / $100 / $200 / 自訂）
選擇頻率（一次性 / 每月）
填寫姓名、Email（非登入狀態）
│
▼
Stripe Payment Element（信用卡 / Apple Pay / Google Pay）
│
▼
Stripe 處理付款
│
┌──┴──┐
成功 失敗
│
▼
Stripe Webhook → POST /api/webhooks/stripe
→ 自動建立 Giving 記錄（PaymentSource = OnlineStripe）
→ Email 確認信給奉獻者
→ 若有 MemberId → 加入個人奉獻歷史
```
**Stripe Webhook 安全驗證（C#）**
```csharp
[HttpPost("/api/webhooks/stripe")]
public async Task StripeWebhook()
{
var json = await new StreamReader(Request.Body).ReadToEndAsync();
var stripeEvent = EventUtility.ConstructEvent(
json,
Request.Headers["Stripe-Signature"],
_stripeConfig.WebhookSecret // 環境變數
);
if (stripeEvent.Type == EventTypes.PaymentIntentSucceeded)
{
var intent = stripeEvent.Data.Object as PaymentIntent;
await _givingService.RecordOnlineGivingAsync(intent);
}
return Ok();
}
```
**環境變數（加入 .env）**
```
STRIPE_SECRET_KEY=sk_live_...
STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
PAYPAL_CLIENT_ID=...
PAYPAL_CLIENT_SECRET=...
```
---
### 3.7 年度收據 (Annual Giving Statement)
**功能清單**
- 依年度、教友產生正式奉獻收據
- PDF 格式，含教會抬頭、稅務資訊（EIN）、奉獻明細
- 批次產生（一次為所有符合條件的教友生成）
- Email 直接寄送給教友
- 收據補發 / 作廢紀錄
- 符合 IRS 501(c)(3) 格式要求
---
### 3.8 Audit Log
**記錄範圍**
| 事件類型 | 範例 |
|----------|------|
| 資料異動 | 教友資料修改、刪除 |
| 財務操作 | 奉獻新增、編輯、刪除 |
| 權限變更 | 角色指派、撤銷 |
| 認證事件 | 登入成功、失敗、密碼重設 |
| 系統設定 | 設定變更 |
**記錄欄位**
```
- timestamp (UTC)
- actor_id (who)
- actor_role
- action (CREATE / UPDATE / DELETE / LOGIN / …)
- resource_type
- resource_id
- before_snapshot (JSON)
- after_snapshot (JSON)
- ip_address
- user_agent
```
**存取控制**
- 只有 `super_admin` 與 `pastor` 可查看 Audit Log
- Audit Log 本身不可刪除（只能 Archive）
---
### 3.9 報表 (Reports)
**預設報表清單**
| 報表名稱 | 說明 | 受眾 |
|----------|------|------|
| 教友統計 | 按狀態/性別/年齡/小組分佈 | 牧師、理事、同工會主席 |
| 新人追蹤 | 過去 N 個月新訪客/受洗趨勢 | 牧師 |
| 出席報表 | 主日 & 小組出席率趨勢 | 牧師、組長 |
| 奉獻摘要 | 月/季/年 奉獻總額、按類型分佈 | 財務、牧師 |
| 服事參與 | 每人服事頻率、空缺率 | 事工負責人 |
| 關懷追蹤 | 標記需關懷教友的跟進記錄 | 牧師、組長 |
**技術需求**
- 圖表視覺化（Bar / Line / Pie）
- 可匯出 CSV / PDF
- 報表可設定排程自動寄送
---
### 3.10 Ministry Scope
**概念說明**
Ministry Scope 讓 `ministry_leader` 與 `cell_leader` 只能存取屬於自己事工範圍的教友、服事與報表資料，不會看到其他事工的敏感資訊。
**實作要點**
- 每筆資源（教友、服事項目、奉獻記錄）綁定 `ministry_id`
- API 層強制過濾（後端 Row-Level Security 或 Middleware）
- 跨事工存取需由上層角色（coworker_chair / pastor）代為操作
- Audit Log 記錄跨 Scope 操作
---
### 3.12 敬拜歌曲庫 (Worship Song Library)
> **用途：** 集中管理教會使用的詩歌，整合歌詞庫、敬拜排序規劃、YouTube 參考連結與教會自錄影片。
---
#### 3.12a 歌曲資料庫 (Song Catalog)
**核心欄位**
```
Song
├── Id
├── TitleEn / TitleZh
├── ArtistEn / ArtistZh (原唱/作者)
├── AlbumEn / AlbumZh (選填)
├── CcliNumber (string, 選填) ← CCLI 版權號碼
├── DefaultKey (e.g. "G", "Ab")
├── Tempo (Slow | Mid | Fast)
├── TimeSignature (e.g. "4/4", "3/4")
├── Language (EN | ZH | Bilingual)
├── Tags (string[], e.g. ["Worship","Praise","Christmas"])
├── IsActive (bool, 是否仍在使用)
├── CreatedByUserId
└── UpdatedAt
SongLyrics ← 歌詞分段存放
├── Id
├── SongId
├── SectionType (Verse | Chorus | Bridge | PreChorus | Outro | Intro)
├── SectionOrder (int, 排序)
├── LyricEn
└── LyricZh
SongMedia ← 多媒體連結
├── Id
├── SongId
├── MediaType (YouTubeReference | ChurchRecording | SheetMusic | ChordChart)
├── Title
├── YouTubeVideoId (只存 ID，e.g. "dQw4w9WgXcQ")
├── BlobPath (Azure Blob，教會自錄影片/樂譜 PDF)
└── UploadedAt
```
**功能清單**
- 新增 / 編輯 / 封存詩歌
- 雙語歌詞分段輸入（Verse / Chorus / Bridge…）
- 搜尋：標題、標籤、CCLI 號碼、語言篩選
- 上傳樂譜 PDF / 和弦表 → Azure Blob（`worship/sheets/`）
- 關聯 YouTube 參考影片（只存 Video ID，嵌入播放，不下載）
- 上傳教會自錄影片 → Azure Blob（`worship/recordings/`）
- 匯出歌詞 PDF（用於投影或印刷）
---
#### 3.12b 敬拜規劃 / 歌單 (Worship Set / Setlist)
**概念：** 每次主日或特別聚會，敬拜負責人規劃當次要唱的詩歌清單及順序。
```
WorshipSet
├── Id
├── ServiceDate
├── ServiceType (主日崇拜 | 禱告會 | 特別聚會)
├── LeadWorshiperId (敬拜帶領人 → Member)
├── Status (Draft | Confirmed | Completed)
├── Notes
├── CreatedByUserId
└── SetItems[]
WorshipSetItem
├── Id
├── WorshipSetId
├── SongId
├── ItemOrder (歌曲順序)
├── PlayKey (本次演唱調性，可與 Song.DefaultKey 不同)
├── Notes (e.g. "唱兩遍，不含橋段")
└── IsSkipped (bool, 臨時略過)
```
**功能清單**
- 建立歌單，從歌曲庫拖曳/搜尋新增詩歌
- 調整歌曲順序（拖曳排序）
- 指定每首歌本次演唱調性
- 歌單狀態：草稿 → 確認 → 完成
- 一鍵產生 **歌單 PDF**（供投影、印刷或發給敬拜隊）
- 歌單 PDF 包含：歌名（雙語）、歌詞、本次調性、備注
- **歷史歌單統計：** 哪些詩歌最常使用（供 AI 整合預留）
---
#### 3.12c YouTube 連結策略
> **重要：直接下載 YouTube 影片違反 YouTube 服務條款（ToS），無論用途。**
| 做法 | 合法性 | 建議 |
|------|--------|------|
| 嵌入 YouTube Player（`