ROLAC/docs/UI_ARCHITECTURE.md

ROLAC — UI 架構設計

文件版本: v0.1 (2026-05-24)

---

目錄

1. 前端整體架構
2. Angular 專案結構
3. Landing Page — 公開網站設計
4. Admin / User Portal — 後台設計
5. Kendo UI 元件對應清單
6. Angular Material 使用範圍
7. 設計系統 (Design Tokens)
8. Responsive / Mobile 規範
9. Kendo UI 授權注意事項

---

1. 前端整體架構

單一 Angular 專案 (Monorepo — Angular Workspace)
│
├── 公開路由 /  →  Landing Page
│   src/app/public/
│   技術: Tailwind CSS + 自訂元件 + Angular Animations
│   對象: 訪客、潛在新教友
│
├── 教友入口 /portal/  →  User Portal
│   src/app/portal/
│   技術: Angular Material + Kendo UI
│   對象: 一般教友（查看服事、奉獻歷史、個人資料）
│
└── 後台管理 /admin/  →  Admin Dashboard
    src/app/admin/
    技術: Angular Material + Kendo UI
    對象: 管理員、牧師、財務、秘書等

↓ Capacitor 打包
iOS App  /  Android App
└── 打包 /portal/ 為主入口（App 不含 Landing Page）

為什麼用單一 Angular 專案？

• Capacitor 只能打包一個 Web App
• 共用 Auth service、API service、ngx-translate
• 共用 Design Token（顏色、字型）保持品牌一致性
• 一個 Jenkins pipeline 搞定所有 build

---

2. Angular 專案結構

src/
├── app/
│   ├── core/                    ← 全域服務 (Auth, API, i18n, Error)
│   │   ├── services/
│   │   ├── guards/
│   │   ├── interceptors/
│   │   └── models/
│   │
│   ├── shared/                  ← 跨模組共用元件
│   │   ├── components/          (語言切換器、頁頭、頁腳、Loading)
│   │   └── pipes/               (雙語 pipe: {{ item | localizedName }})
│   │
│   ├── public/                  ← Landing Page（Tailwind）
│   │   ├── home/
│   │   ├── about/
│   │   ├── events/
│   │   ├── media/
│   │   ├── giving/
│   │   └── contact/
│   │
│   ├── portal/                  ← 教友 User Portal（Material + Kendo）
│   │   ├── dashboard/
│   │   ├── my-roster/
│   │   ├── my-giving/
│   │   └── my-profile/
│   │
│   └── admin/                   ← 後台管理（Material + Kendo）
│       ├── dashboard/
│       ├── members/
│       ├── attendance/
│       ├── groups/
│       ├── roster/
│       ├── giving/
│       ├── cms/
│       ├── reports/
│       ├── audit-log/
│       └── settings/
│
├── assets/
│   ├── i18n/
│   │   ├── en.json
│   │   └── zh-TW.json
│   └── images/
│
└── styles/
    ├── _tokens.scss             ← Design Tokens（色彩、字型、間距）
    ├── _material-theme.scss     ← Angular Material 主題
    ├── _kendo-theme.scss        ← Kendo UI 主題覆寫
    └── tailwind.css             ← Tailwind（public/ 使用）

---

3. Landing Page — 公開網站設計

設計方向

目標： 有設計感、溫暖、現代，反映教會的歡迎文化
技術： Tailwind CSS + 自訂 Angular 元件 + Angular Animations
不使用 Angular Material 或 Kendo UI（避免 Material Design 的企業感）

視覺風格建議

元素	建議
色調	以教會品牌色為主（深藍/金或暖色系），建議 2 主色 + 1 強調色
字型	Google Fonts：標題用 serif（如 Playfair Display），內文用 sans-serif（Inter）
圖像	真實教會照片優先；輔以 abstract/light 背景插圖
動畫	入場淡入（Angular Animations）、滾動觸發（Intersection Observer）
圖示	Heroicons 或 Phosphor Icons（免費，SVG）

各區塊設計

rolac.org
│
├── [Navbar]
│   Logo | 導覽連結 | EN/中 切換 | [Visit Us] CTA 按鈕
│
├── [Hero Section]
│   全版背景圖（教會聚會照片）
│   主標題 + 副標題（雙語動態切換）
│   兩個 CTA：[Join Us] [Watch Online]
│   滾動指示箭頭
│
├── [Welcome / About Section]
│   左側：短文介紹教會異象
│   右側：牧師照片 + 名字
│   底部：[Learn More] 連結
│
├── [Service Times]
│   卡片式：主日崇拜時間 / 地點 / 停車資訊
│   嵌入 Google Maps
│
├── [Announcements / Events]
│   最新 3 則公告卡片（從 CMS 動態取得）
│   [View All] 連結
│
├── [Media — Latest Sermon]
│   YouTube Embed 最新一篇講道
│   標題 + 日期 + 講員
│   [Sermon Archive] 連結
│
├── [Giving Section]
│   感召文字 + 奉獻方式說明（現金/支票/Zelle/PayPal）
│   簡潔卡片排版，非強迫式
│
├── [Connect / Cell Groups]
│   鼓勵加入小組的呼召
│   [Contact Us] 或 [填寫訪客卡] 按鈕
│
├── [Contact Section]
│   地址、電話、Email
│   聯絡表單
│
└── [Footer]
    Logo | 快速連結 | 社群媒體 | © | 隱私政策

Tailwind 使用策略

<!-- 範例：Hero Section -->
<section class="relative h-screen flex items-center justify-center overflow-hidden">
  <div class="absolute inset-0 bg-cover bg-center"
       [style.backgroundImage]="'url(' + heroImage + ')'">
    <div class="absolute inset-0 bg-black/50"></div>
  </div>
  <div class="relative z-10 text-center text-white px-4 max-w-4xl mx-auto">
    <h1 class="text-5xl md:text-7xl font-serif mb-6 animate-fade-in">
      {{ 'home.hero.title' | translate }}
    </h1>
    <p class="text-xl md:text-2xl mb-10 text-white/90">
      {{ 'home.hero.subtitle' | translate }}
    </p>
    <div class="flex gap-4 justify-center flex-wrap">
      <a routerLink="/about"
         class="btn-primary px-8 py-4 rounded-full text-lg font-semibold">
        {{ 'home.hero.joinUs' | translate }}
      </a>
    </div>
  </div>
</section>

Landing Page 在 Mobile App 中的處理

Landing Page 僅存在於 rolac.org 網站，不 納入 Capacitor App
App 啟動後直接跳到 Login 畫面或 Portal Dashboard

---

4. Admin / User Portal — 後台設計

整體 Layout

┌──────────────────────────────────────────────────┐
│ [ROLAC Logo]  [模組標題]    [EN|中]  [通知] [頭像] │  ← Top Toolbar (Angular Material MatToolbar)
├──────────┬───────────────────────────────────────┤
│          │                                       │
│  [側邊   │         Main Content Area             │
│   導覽]  │                                       │
│          │   (Kendo Grid / Form / Chart 等)      │
│  Desktop │                                       │
│  only    │                                       │
│          │                                       │
└──────────┴───────────────────────────────────────┘
           ┌──────────────────────────────────────┐
           │ [首頁] [服事] [教友] [奉獻] [我的]   │  ← Bottom Tab Bar (Mobile only)
           └──────────────────────────────────────┘

導覽策略

• Desktop (≥ 1024px): 左側 Side Nav（Angular Material MatSidenav），可折疊
• Mobile (< 1024px): 底部 Tab Bar（最多 5 個主要分頁），Side Nav 改為漢堡選單

色彩主題（Admin / Portal）

使用 Angular Material Custom Theme，與 Tailwind Landing Page 共用 Design Token：

// _material-theme.scss
@use '@angular/material' as mat;

$rolac-primary: mat.define-palette(mat.$indigo-palette, 700);
$rolac-accent:  mat.define-palette(mat.$amber-palette, 600);
$rolac-warn:    mat.define-palette(mat.$red-palette);

$rolac-theme: mat.define-light-theme((
  color: (
    primary: $rolac-primary,
    accent:  $rolac-accent,
    warn:    $rolac-warn,
  ),
  typography: mat.define-typography-config(
    $font-family: 'Inter, sans-serif'
  ),
));

@include mat.all-component-themes($rolac-theme);

---

5. Kendo UI 元件對應清單

核心模組 → Kendo 元件 對應

模組	Kendo 元件	用途
教友管理	kendo-grid	教友列表（排序、篩選、分頁、匯出）
教友管理	kendo-upload	教友照片上傳
奉獻記錄	kendo-grid	奉獻列表（批次輸入、inline edit）
服事表	kendo-scheduler	排班日曆（月/週/日 視圖）
服事表	kendo-grid	服事同工列表
出席報表	kendo-chart (LineChart)	主日出席趨勢折線圖
奉獻報表	kendo-chart (BarChart)	月度奉獻長條圖
奉獻報表	kendo-chart (DonutChart)	奉獻類型比例
教友統計	kendo-chart (PieChart)	教友分佈（年齡/性別）
所有篩選	kendo-datepicker kendo-daterangepicker	日期範圍篩選
所有列表	kendo-dropdownlist	下拉選單
通知	kendo-notification	操作成功/失敗提示
Audit Log	kendo-grid	稽核記錄（大量資料、虛擬捲動）
報表匯出	Kendo Grid 內建 Excel/PDF 匯出	一鍵匯出

Kendo Grid 重點設定（教友列表範例）

// members-list.component.html
<kendo-grid
  [data]="gridData"
  [pageSize]="20"
  [pageable]="{ buttonCount: 5 }"
  [sortable]="true"
  [filterable]="'menu'"
  [reorderable]="true"
  [resizable]="true"
  (excelExport)="onExcelExport($event)">

  <ng-template kendoGridToolbarTemplate>
    <button kendoGridExcelCommand>
      {{ 'common.exportExcel' | translate }}
    </button>
    <button kendoGridPDFCommand>
      {{ 'common.exportPDF' | translate }}
    </button>
  </ng-template>

  <kendo-grid-column field="displayName"
    [title]="'member.name' | translate" [width]="180">
  </kendo-grid-column>
  <kendo-grid-column field="email"
    [title]="'member.email' | translate" [width]="220">
  </kendo-grid-column>
  <!-- ... -->

  <kendo-grid-excel fileName="members.xlsx"></kendo-grid-excel>
  <kendo-grid-pdf fileName="members.pdf"></kendo-grid-pdf>
</kendo-grid>

Kendo Scheduler（服事排班）

// service-roster.component.html
<kendo-scheduler
  [kendoSchedulerBinding]="events"
  [selectedDate]="selectedDate"
  [views]="['month', 'week', 'day']"
  (slotClick)="onSlotClick($event)"
  (eventClick)="onEventClick($event)">

  <kendo-scheduler-month-view></kendo-scheduler-month-view>
  <kendo-scheduler-week-view></kendo-scheduler-week-view>
  <kendo-scheduler-day-view></kendo-scheduler-day-view>
</kendo-scheduler>

---

6. Angular Material 使用範圍

Angular Material 負責基礎 UI 骨架，Kendo UI 負責複雜資料元件。

Angular Material 元件	用途
MatToolbar	頂部 Header
MatSidenav / MatDrawer	側邊導覽（Desktop）
MatTabGroup	Portal 底部分頁（Mobile）
MatCard	Dashboard 統計卡片、表單卡片
MatDialog	確認對話框、新增/編輯 Modal
MatFormField + MatInput	所有一般表單欄位
MatSelect	小型下拉（非大量資料）
MatButton / MatIconButton	所有按鈕
MatSnackBar	輕量操作回饋（儲存成功等）
MatProgressSpinner	載入中動畫
MatBadge	通知數量角標
MatChip	標籤（教友分類、服事類型）
MatIcon	系統圖示（搭配 Material Icons）
MatDivider	分隔線

---

7. 設計系統 (Design Tokens)

共用 Token 確保 Landing Page 與 Admin 視覺一致：

// styles/_tokens.scss

// ── 品牌主色 ──
$color-primary-600: #3B3F8C;   // 深藍靛（主色）
$color-primary-400: #6366F1;   // 亮藍靛（Hover）
$color-accent-500:  #D97706;   // 金黃（強調色）
$color-accent-300:  #FCD34D;   // 淺金（Hover）

// ── 語意色 ──
$color-success: #16A34A;
$color-warning: #D97706;
$color-error:   #DC2626;
$color-info:    #2563EB;

// ── 中性色 ──
$color-gray-50:  #F9FAFB;
$color-gray-100: #F3F4F6;
$color-gray-700: #374151;
$color-gray-900: #111827;

// ── 字型 ──
$font-display: 'Playfair Display', Georgia, serif;   // Landing Page 標題
$font-body:    'Inter', -apple-system, sans-serif;   // 全域內文

// ── 間距 ──
$spacing-unit: 8px;

// ── 圓角 ──
$radius-sm: 4px;
$radius-md: 8px;
$radius-lg: 16px;
$radius-full: 9999px;

實際品牌色在開始前與教會確認（教會 Logo 的主色）。

---

8. Responsive / Mobile 規範

Breakpoints

名稱	寬度	描述
xs	< 480px	小螢幕手機
sm	480–767px	一般手機
md	768–1023px	平板
lg	≥ 1024px	桌機

各頁面 Mobile 適配規則

元件	Desktop	Mobile
導覽	左側 Sidenav（固定展開）	Bottom Tab Bar + 漢堡
Kendo Grid	全欄顯示	隱藏次要欄，固定姓名欄
Kendo Scheduler	月 / 週 視圖	僅「Day / Agenda」視圖
表單	雙欄排版	單欄，全寬輸入框
Chart	正常尺寸	可橫向捲動容器
Dialog	置中 Modal	底部 Sheet（全寬滑上）

Capacitor App 專屬考量

// 偵測是否在原生 App 中執行
import { Capacitor } from '@capacitor/core';

const isNativeApp = Capacitor.isNativePlatform();

// 在 App 中隱藏 Landing Page 導覽
// 在 App 中使用原生 Back Button 處理 Android

---

9. Kendo UI 授權注意事項

Kendo UI for Angular 是商業授權產品（Progress/Telerik）。

方案	費用	適用
Developer License	~$999/開發者/年	標準商業授權
Kendo UI 30-day Trial	免費	開發評估用
DevCraft Complete	~$1,999/年	含全套 Telerik 產品

Nonprofit 折扣

• Progress/Telerik 沒有標準 Nonprofit 免費方案
• 但可以直接寄信至 sales@telerik.com 說明是 501(c)(3) 教會，詢問 Nonprofit Discount，有時可獲 40–60% 折扣
• 建議在 Phase 0 確認授權再開始使用

替代方案（若 Kendo 費用過高）

替代品	費用	Grid	Chart	Scheduler
AG Grid Community	免費	✅ 強大	❌	❌
ngx-charts	免費	❌	✅	❌
FullCalendar	免費/付費	❌	❌	✅
PrimeNG	免費 (MIT)	✅	✅	✅ 基本

PrimeNG 是最接近的免費替代品，如授權談不攏可考慮改用。