WIP

2026-05-29 20:54:08 -07:00
parent 95fa37ebdf
commit fe50ea3d30
6 changed files with 99 additions and 295 deletions
@@ -2,7 +2,7 @@

 **教會:** River Of Life Christian Church In Arcadia (ROLAC)  
 **規模:** 50–100 人  
-**文件版本:** v0.2 (2026-05-24)
+**文件版本:** v0.3 (2026-05-29)

 ---

@@ -522,6 +522,7 @@ Ministry（事工部門）  ×  大類（Category Group）  ×  子項目（Sub-
  餐飲部門 > 餐飲 > 消耗品
  餐飲部門 > 餐飲 > 出餐費用
  行政     > 辦公 > 文具耗材
+  行政     > 人事 > 薪資
  兒童事工 > 教材 > 印刷費用
 ```

@@ -577,17 +578,20 @@ Expense                     ← 每筆支出
 | Food & Beverage / 餐飲 | 出餐費用 · 食材採購 · 器具 · 消耗品 | 餐飲、兒牧 |
 | Training / 教育訓練 | 課程費用 · 書籍 · 研討會 · 差旅 | 敬拜、PPT/影音、音控、兒牧 |
 | Materials / 教材 | 印刷費用 · 手工材料 · 版權購買 | 兒牧、講道、司會 |
-| Facility / 場地 | 場地租金 · 水電 · 保險 · 裝飾 | 場地組、行政 |
+| Facility / 場地 | 場地租金 · 水電 · 財產保險 · 裝飾 | 場地組、行政 |
 | Printing / 印刷 | 週報 · 程序單 · 海報 | 行政、招待、兒牧 |
 | Missions / 宣教 | 奉獻轉帳 · 宣教士支援 · 差旅 | 行政 |
 | Benevolence / 關懷 | 急難救助 · 慰問禮品 · 探訪費用 | 行政 |
 | Other / 其他 | 雜支 | 所有 |
+| Personnel / 人事 | 薪資 · 薪資稅費 · 員工福利 · 勞工保險 · 酬庸 · 同工進修 · 外包勞務 | 行政 |
+
+> **分類備注：** `Facility > 財產保險` 為建築物／場地責任險；員工健保等歸 `Personnel > 員工福利`。同工代墊報銷（`StaffReimbursement`）依實際購買物選大類，薪資／福利付款才歸人事。

 **Ministry × 大類 常用對應（供財務設定參考）**

 | Ministry | 最常用大類 |
 |----------|-----------|
-| 行政 Administration | 辦公耗材 · 印刷 · 場地 · 宣教 · 關懷 |
+| 行政 Administration | 人事 · 辦公耗材 · 印刷 · 場地 · 宣教 · 關懷 |
 | 講道 Preaching | 教材 · 書籍（Training） |
 | 司會 Emcee | 印刷（程序單） |
 | 敬拜 Worship | 設備 · 教育訓練 · 耗材 |
@@ -677,6 +681,7 @@ finance/
 | 審核 / 批准 | `finance`、`super_admin` |
 | 建立廠商直接付款 | `finance`、`super_admin` |
 | 查看所有支出 | `finance`、`pastor`、`super_admin` |
+| 查看人事類支出 | `finance`、`pastor`、`super_admin`（事工領袖不可見） |
 | 查看自己的申請 | 提交者本人 |
 | 月底對帳 | `finance`、`super_admin` |

@@ -1223,7 +1228,7 @@ AuditLog（bigint PK，immutable，所有操作均記錄）
 | 後端 API | **ASP.NET Core (C#)** | REST API |
 | ORM | **Entity Framework Core** | Code-first migrations |
 | 資料庫 | **PostgreSQL** | 自架於 Docker |
-| 檔案儲存 | **Azure Blob Storage** | 教友照片、PDF 收據、CMS 媒體 |
+| 檔案儲存 | **本地檔案儲存（現階段）→ Azure Blob Storage（未來）** | 透過 `IFileOperationService` 抽象，現以 `LocalFileOperationService`（base folder 由 config 設定）實作，未來切換 `AzureFileOperationService`。教友照片、PDF 收據、CMS 媒體 |
 | 原始碼管理 | **Gitea** | 自架，Docker 容器 |
 | CI/CD | **Jenkins** | 自架，Docker 容器 |
 | 容器化 | **Docker + Docker Compose** | 所有服務容器化 |
@@ -1310,6 +1315,45 @@ assets/i18n/zh-TW.json
 - **ASP.NET Core Identity** — 使用者管理、密碼雜湊
 - **全新資料庫** — 無舊資料遷移需求，直接 EF Code-First Migration

+### 檔案儲存抽象層 (File Storage Abstraction)
+
+> **背景（2026-05-29 決定）：** Microsoft 拒絕了我們的 Nonprofit / Azure 申請，**現階段無法使用 Azure Blob Storage**。  
+> 因此先改用**本地檔案儲存**（base folder 由 config 設定），未來取得 Azure 額度後再切換為 Azure Blob，**業務程式碼不需改動**。
+
+**設計：以介面抽象隔離儲存後端**
+
+所有檔案讀寫（教友照片、PDF 收據、CMS 媒體、收據照片、敬拜樂譜/影片等）一律透過 `IFileOperationService` 介面操作，業務層不直接依賴任何特定儲存實作。
+
+```
+IFileOperationService              ← 抽象介面（業務層僅依賴此介面）
+├── SaveAsync(path, stream)        → 儲存檔案，回傳相對路徑 / 識別碼
+├── GetAsync(path)                 → 讀取檔案串流
+├── DeleteAsync(path)              → 刪除檔案
+├── ExistsAsync(path)             → 是否存在
+└── GetUrlAsync(path, expiry?)     → 取得存取 URL（本地：API 代理路徑；Azure：SAS URL）
+
+LocalFileOperationService          ← 現階段實作（✅ Phase 1）
+├── Base folder 從 config 讀取（e.g. FileStorage:BasePath）
+├── 路徑沿用既有結構（cms/images/、finance/receipts/、worship/… 相對於 base folder）
+├── Private 檔案經由 API 代理 + 角色授權提供存取（取代 SAS URL）
+└── 容器化時 base folder 對映到 Docker volume，確保持久化
+
+AzureFileOperationService          ← 未來實作（🔜 取得 Azure 額度後）
+├── 對映到 Azure Blob Container
+├── GetUrlAsync 回傳具時效的 SAS URL
+└── 切換方式：DI 註冊改綁此實作 + 一次性資料搬移，業務程式碼零改動
+```
+
+**設定範例（appsettings）**
+```jsonc
+"FileStorage": {
+  "Provider": "Local",            // Local | Azure（未來）
+  "BasePath": "/data/rolac-files" // 本地 base folder（容器內對映 volume）
+}
+```
+
+> **與本文件其他段落的關係：** 文中所有提到 `Azure Blob`／blob 路徑的地方（§3.5 CMS 圖片、§3.6d `finance/receipts/`、§3.12e `worship/...`），現階段一律改由 `IFileOperationService` + `LocalFileOperationService` 以對應相對路徑儲存於 config 的 base folder 下；待 Azure 開通後切換 `AzureFileOperationService` 即還原為 Blob 儲存，路徑結構不變。
+
 ---

 ## 7. 開發階段規劃 (Roadmap)
@@ -1322,6 +1366,7 @@ assets/i18n/zh-TW.json
 - [X] 認證系統（JWT + Refresh Token + ASP.NET Identity）
 - [X] RBAC 框架（角色 + Ministry Scope middleware）
 - [ ] Audit Log 基礎建設
+- [ ] 檔案儲存抽象層（`IFileOperationService` + `LocalFileOperationService`，base folder 從 config 讀取）
 - [ ] Mobile-first UI 元件庫設定（底部導覽、touch target 規範）

 ### Phase 1 — 六月上線 MVP（5 週，目標 2026-06-30）
@@ -1334,22 +1379,22 @@ assets/i18n/zh-TW.json
 - [ ] 聯絡表單

 #### 教友管理
- [ ] 教友 CRUD（基本資料、照片上傳至 Azure Blob）
+- [ ] 教友 CRUD（基本資料、照片上傳，經 `IFileOperationService` → 本地儲存）
 - [ ] 家庭單元管理
 - [ ] 搜尋 / 篩選（姓名、狀態、小組）
 - [ ] 教友狀態（會員 / 訪客 / 前會員）
 - [ ] i18n 語言切換 UI（EN / 中 按鈕）

 #### 奉獻追蹤（手動）
- [ ] 奉獻類型設定（Tithe / Offering / Special）
- [ ] 單筆奉獻記錄（現金 / 支票 / Zelle / PayPal）
- [ ] **主日奉獻袋批次輸入（OfferingSession）** ← 鍵盤優先快速錄入
+- [X] 奉獻類型設定（Tithe / Offering / Special）
+- [X] 單筆奉獻記錄（現金 / 支票 / Zelle / PayPal）
+- [X] **主日奉獻袋批次輸入（OfferingSession）** ← 鍵盤優先快速錄入
 - [ ] 個人奉獻歷史查詢（教友 App 端）
 - [ ] 年度收據 PDF 產生（QuestPDF，EIN 42-2682968）
 - [ ] 年度收據 Email 批次寄送

 #### 支出追蹤 & 報銷
- [ ] 支出類別設定（愛宴 / 辦公用品 / 宣教…）
+- [ ] 支出類別設定（11 大類種子：設備 / 餐飲 / 人事 / 宣教…）
 - [ ] 廠商直接付款記錄（含支票號碼）
 - [ ] 同工代墊報銷申請（含收據照片上傳）
 - [ ] 財務審核流程（Pending → Approved → Paid）
@@ -1464,3 +1509,4 @@ assets/i18n/zh-TW.json
 | 17 | 兒童特殊欄位 | 緊急聯絡人、過敏、接送授權，暫緩 | 🟢 低 | ⏳ 未來再評估 |
 | 18 | CCLI License 號碼 | 教會是否已有 CCLI License？需填入系統設定 | 🟡 中 | ⏳ 待確認 |
 | 19 | ~~Phase 2/3 模組分配~~ | **已決定**：Phase 2 = 服事表排班 + 主日出席統計 + 小組管理；Phase 3 = 事工預算 | 🔴 高 | ✅ 決定 |
+| 20 | ~~檔案儲存後端~~ | **已決定**：Microsoft 拒絕申請，暫無法用 Azure Blob。改以 `IFileOperationService` 抽象，現階段用 `LocalFileOperationService`（base folder 由 config 設定），未來取得 Azure 額度後切換 `AzureFileOperationService`（見 §6 檔案儲存抽象層） | 🔴 高 | ✅ 決定 |