usher-manage-stack/AGENTS.md

公益組織會員管理系統 --- 技術規格說明書

Version 1.0

1. 系統概述

本系統為公益組織打造，用於管理會員資料、會費繳納、會籍期限及後續財務簽核流程。 系統目標包含：

• 會員可自助查詢：
  • 會籍期限
  • 繳費紀錄
  • 個人資料
• 協會內部可管理：
  • 會員資料
  • 會費紀錄
  • 財務文件簽核流程（會計 → 出納 → 理事長）
• 高度無障礙支援（WCAG 2.1 AA）

2. 系統架構

2.1 技術選型（後端）

• Laravel 10+
• PHP 8.2+
• MySQL 8+
• Laravel Queue（Redis 或 DB）
• Google Workspace SMTP

2.2 前端架構

• Phase 1：Blade + Tailwind + Alpine.js
• Phase 2：必要頁面用 Inertia.js + Vue 3
• 無障礙 HTML-first 原則

3. 功能規格

3.1 會員端

• 登入（Email + 密碼）
• 查看會員資料
• 查看繳費紀錄
• 修改密碼
• 忘記密碼

3.2 後台

• 會員管理（新增/編輯/匯入）
• 帳號啟用連結寄送
• 會費管理
• 到期提醒
• RBAC 角色管理

3.3 財務簽核（第二階段）

• 財務文件申請
• 出納 → 會計 → 理事長簽核流程
• Audit Log

4. 資料庫 Schema（摘要）

• members
• users
• roles / permissions（spatie/laravel-permission）
• membership_payments
• finance_documents
• audit_logs

5. 註冊與啟用流程

既有會員

• 匯入資料 → 寄啟用連結 → 設密碼

新申請會員

• 前台表單 → pending → 管理員審核 → 寄啟用連結

6. 寄信規格

• 使用 Google Workspace SMTP
• App Password 模式
• Laravel Mailable + queue

7. 無障礙規格

• HTML 語意化
• 所有表單必須有 label
• aria-live
• 表格必須使用 table/th/thead/tbody
• Email 為純文字友好格式

8. 安全性

• bcrypt/argon2 密碼
• 身分證 encrypted + hash
• Rate limiting
• Audit Log 必須覆蓋所有敏感操作

9. 部署建議

• Linux VPS
• Nginx + PHP-FPM
• MySQL/MariaDB
• Redis（optional）
• Daily backup
• HTTPS（Let's Encrypt）

10. Roadmap

Phase 1

• 會員登入、資料檢視、繳費紀錄
• 後台會員管理與匯入
• 寄信與啟用流程

Phase 2

• RBAC
• 到期提醒
• Audit Log

Phase 3

• 財務簽核流程與附件
• Vue + Inertia 強化互動頁面