平台維運與管理
角色權限管理、社區上線流程、環境設定與日常維護。
角色與權限
| 角色 | 說明 | 需要社區 | 主要權限 |
|---|---|---|---|
| ADMIN | 系統管理員 | 否 | 全部功能、營運後台、角色管理、文件還原 |
| OPS | 營運教練 | 否 | 營運後台、跨社區案件、知識庫、文件還原 |
| COMMUNITY_ADMIN | 社區管理員 | 是 | 案件管理、邀請碼、名冊上傳、公告、文件庫、裝修審核、工程媒合、廠商審核 |
| COMMITTEE | 管委會委員 | 是 | 案件查看與參與、爭議諮詢、文件索取共同簽核 |
| RESIDENT | 住戶（預設） | 是 | 案件查看、公告瀏覽、文件庫瀏覽與索取、裝修申請、AI 爭議諮詢、補助查詢 |
| VENDOR | 廠商 | 否 | 廠商專區、投標管理、公司資料、比價報名 |
| CONSULTANT | 顧問 | 否 | 諮詢專區、回覆諮詢問題 |
角色指派方式
- RESIDENT → 新帳號預設角色
- COMMUNITY_ADMIN → 建立社區時自動升級；之後在營運後台「管理成員」用 Email 指派（見下方「代社區管理成員」）
- COMMITTEE → 同上，或由該社區的社區管理員在「社區成員」頁調整
- VENDOR → 建立廠商資料時自動指派（非 ADMIN 帳號）
- 其他角色 → 需由 ADMIN 透過資料庫或 API 手動調整
社區上線流程
社區上線採審核制，管理員需確認社區的合法性後才核准啟用。以下是標準流程：
社區自助申請（推薦）
- 1分享 社區管理員指南 給目標社區的主委或總幹事
- 2對方使用 Google/LINE 登入 → 選擇「申請建立社區」→ 填寫社區名稱地址與申請路線
- 3對方上傳驗證文件（已報備路線：組織報備證書、管委會核備函、職務委員當選公告）
- 4平台管理員於 /ops/communities 審核申請 → 核准後社區啟用
- 5社區管理員帳號升級為 COMMUNITY_ADMIN，邀請碼解鎖，自行邀請住戶
管理員協助上線
- 1請社區聯絡人先使用 Google/LINE 登入一次（建立帳號）
- 2協助確認文件備齊後，在 Neon 資料庫中將社區狀態改為 APPROVED 並將帳號角色改為 COMMUNITY_ADMIN
- 3使用 onboarding API 建立社區並關聯帳號
- 4通知社區管理員可以開始使用
環境與部署
| 項目 | 說明 |
|---|---|
| 前端 + API | 自架 AWS EC2 主機（nginx + systemd，部署後重啟服務） |
| 資料庫 | 自架 PostgreSQL 18（AWS 內網，不對外開放） |
| 檔案儲存 | AWS S3 私有儲存桶（附件、名片圖片；一律經平台網址讀取，不公開） |
| AI 模型 | Gemini 2.5 Flash（主要）/ Gemma4 via OpenRouter（備援） |
| 認證 | NextAuth v5（Google + LINE OAuth） |
| 網域 | harmonyhub.cc |
重要環境變數
AUTH_SECRET — NextAuth 加密金鑰
AUTH_GOOGLE_ID / AUTH_GOOGLE_SECRET — Google OAuth
AUTH_LINE_ID / AUTH_LINE_SECRET — LINE OAuth
DATABASE_URL — PostgreSQL 連線字串
DIRECT_URL — 資料庫直連（跑 migration 用，目前與 DATABASE_URL 相同）
AWS_REGION / S3_UPLOAD_BUCKET — 檔案儲存的區域與儲存桶（主機用 IAM 角色取得權限，不必另外放金鑰）
GOOGLE_GENERATIVE_AI_API_KEY — Gemini API
OPENROUTER_API_KEY — OpenRouter 備援 API
CRON_SECRET — 定時任務認證 token
RESEND_API_KEY — Resend Email 服務 API Key（Phase 2b+）
HMAC_SECRET — 文件下載限時連結簽名金鑰（Phase 2b+）
NEXT_PUBLIC_APP_URL — 公開網域（Phase 2b+）
社區申請審核
每筆社區申請都需要人工審核，確認文件合法有效後才核准啟用。
審核步驟
- 1前往 /ops/communities，在「待審申請」分頁查看所有待處理申請
- 2點開申請，核閱申請人資訊（姓名、Email、社區名稱地址）以及三份驗證文件： 組織報備證書、管委會核備函、職務委員當選公告
- 3確認文件齊全且內容相符後，點選 「核准」：
- 社區狀態變更為「已核准」，正式啟用
- 申請人帳號升級為社區管理員
- 邀請碼功能解鎖，可開始邀請住戶
若文件不符或有疑義
點選「駁回」，填寫繁體中文駁回原因（例如：缺少管委會核備函、文件日期已逾期）。 申請人在 /pending 頁面即可看到原因，修正後可重新送件。
代社區管理成員與邀請碼
社區自己的管理員處理不了的事（指派第一位社區管理員、換人、邀請碼外流、讓被移除的住戶回來）， 由平台管理員在營運後台處理，不必先加入那個社區。
找到社區
- 1左側選單「營運後台」→ 「社區管理」（/ops/communities）
- 2每個社區一張卡片，寫著成員數、目前的邀請碼和已用次數，並有 「撤銷並重發」 和 「管理成員」 兩個按鈕
指派社區管理員
- 1卡片上點 「管理成員」，進入該社區的成員管理頁（/ops/communities/[id]/members）
- 2在「指派成員角色」輸入對方的 Email，選 「社區管理員」，按 「指派」。 對方必須已經有帳號（請他先用 Google 或 LINE 登入一次），但不必先加入社區
- 3成功會顯示「已指派 ○○ 為 社區管理員」，對方出現在下方成員清單。他重新登入後（或約 5 分鐘內）就會看到所有權人名冊、社區成員等管理功能
- 4已經在清單上的成員，直接用他那一列的下拉選單改成社區管理員、管委會委員或住戶
| 畫面上的訊息 | 原因 |
|---|---|
| 找不到使用者 | 這個 Email 還沒有註冊，請對方先登入一次 |
| 無法在此變更平台管理員的社區角色 | 對方是平台管理員或營運人員，本來就能進每個社區 |
讓被管委會移除的住戶回來
被移除的帳號用邀請碼也回不去。在成員管理頁用他的 Email 指派一次 「住戶」 就解除了； 他要再走一次住戶驗證（選門牌、輸入所有權人姓名），才會重新連回門牌。
邀請碼外流或找不到
- 1在社區卡片上按 「撤銷並重發」，再按 「確定」
- 2卡片立刻顯示新的 8 碼邀請碼（5 年、最多 999 人）。舊碼馬上失效，已加入的住戶不受影響
- 3把新碼交給該社區的管委會重新公告
代社區查看或匯入所有權人名冊
- 1卡片上點 「管理成員」，在成員管理頁上方點 「所有權人名冊」（/ops/communities/[id]/registry）
- 2這一頁跟社區管理員看到的名冊頁一樣：匯入 Excel 或 CSV、搜尋、逐戶新增、修改、刪除（步驟見社區管理員指南），只是社區取自網址，不必先加入那個社區
- 3只有平台管理員和營運人員進得去；社區管理員只能管自己社區的名冊
營運後台還不能做的事
- 從營運後台移除成員：移除請由社區管理員在「社區成員」頁操作
無報備 / 不確定申請處理
申請人選擇「尚未組織報備」或「不確定報備狀態」時，申請進入詢問待處理狀態，需要平台主動協助。
- 1在 /ops/communities「待審申請」中找到詢問待處理狀態的申請，記錄申請人聯絡方式
- 2向市府（各縣市地政局或相關機關）查詢該社區是否已有組織報備紀錄
- 3主動聯繫申請人，說明查詢結果，並提供以下協助：
- 若已報備但申請人不知道：協助取得核備文件，引導走「有組織報備」路線重新申請
- 若確實尚未報備：指引申請人依《公寓大廈管理條例》完成管委會成立與組織報備程序
審核原則
此類申請應等申請人補齊三份正式驗證文件後，再核准啟用社區。 切勿在文件不完整的情況下核准，以確保平台社區資料的可信度。
文件還原
平台所有社區文件採軟刪除機制：刪除只是隱藏，並不會永久移除。 任何誤刪的文件都可以透過營運後台還原。
還原步驟
- 1前往 /ops/deleted-documents，查看所有已軟刪除的文件清單
- 2每筆記錄顯示：文件名稱、所屬社區、刪除者姓名、刪除時間
- 3找到需要還原的文件，點選「還原」
- 4文件重新出現在對應社區的文件庫，社區管理員即可查看
- 所有刪除與還原操作均寫入稽核日誌（AuditLog），包含操作者與時間戳記
- 無論保全公司更換或人員異動，歷史文件均可追溯還原
注意事項
還原操作僅限 ADMIN 與 OPS 角色執行。 如社區管理員反映文件遺失，請先至 /ops/deleted-documents 確認是否為軟刪除，再決定是否還原。
文件索取審核與兼職總幹事共簽
住戶提交文件索取申請後，管理員核准即觸發 7 天 HMAC 限時下載連結 Email。 但若核准者角色為 兼職總幹事，系統會先要求管委會委員共同簽核，才會發送下載連結。
一般核准流程（COMMUNITY_ADMIN）
- 1在 /dashboard/documents 的「索取申請」分頁查看待處理申請
- 2確認申請人身分與索取理由後，點選「核准」
- 3系統立即發送 HMAC 簽名限時連結至申請人 Email（有效期 7 天）
兼職總幹事共簽流程
- 1兼職總幹事核准後，系統不立即發送 Email，改為通知管委會委員進行共同簽核
- 2管委會委員登入後在「待共簽」清單中確認
- 3委員確認後，系統才觸發下載連結 Email 發送給申請人
相關環境變數
RESEND_API_KEY — 發送 Email 用（Resend 服務）
HMAC_SECRET — 產生限時下載連結簽名金鑰
Phase 2b / 2c / 3 新增環境變數
以下環境變數在 Phase 2b 之後新增，要設定在正式主機的環境變數檔（systemd EnvironmentFile）裡：
RESEND_API_KEY — Resend Email 服務 API Key（文件索取 / 裝修核准 / 比價通知）
HMAC_SECRET — 文件下載限時連結 HMAC 簽名金鑰（至少 32 字元）
NEXT_PUBLIC_APP_URL — 公開網域（用於產生 Email 中的連結，例：https://harmonyhub.cc）
注意
HMAC_SECRET 遺失或更換後，所有舊的文件下載連結將立即失效。更換前請通知使用者重新申請。
常用資料庫操作
透過 Neon Console 或 Prisma Studio 執行。生產環境分支：br-billowing-base-a1vvsqum
變更使用者角色
UPDATE app_user SET role = 'COMMUNITY_ADMIN' WHERE email = 'user@example.com';查看所有社區
SELECT id, name, address, created_at FROM community ORDER BY created_at DESC;查看社區成員
SELECT u.name, u.email, u.role, c.name AS community
FROM app_user u
LEFT JOIN community c ON u.community_id = c.id
WHERE u.community_id IS NOT NULL
ORDER BY c.name, u.role;Schema 變更（新增欄位）
-- 1. 修改 prisma/schema.prisma
-- 2. 本地: npx prisma db push
-- 3. Neon: 透過 MCP 或 Console 執行 ALTER TABLE
-- 4. npx prisma generate系統管理常見問題
Prisma migration 失敗怎麼辦？
prisma migrate dev 會因為 manual/ 目錄而失敗。改用 prisma db push（開發）或直接在 Neon 執行 ALTER TABLE SQL（生產）。
如何新增 ADMIN 帳號？
請使用者先以 Google/LINE 登入建立帳號，再透過資料庫 UPDATE app_user SET role = 'ADMIN' WHERE email = '...' 調整角色。
部署失敗怎麼辦？
先看 pnpm build:standalone 的輸出，常見原因是 TypeScript 錯誤、少了環境變數、或 Prisma generate 沒跑。build 過了但網站起不來，就用 journalctl -u harmonyhub 看服務紀錄。
AI 功能無回應？
檢查 GOOGLE_GENERATIVE_AI_API_KEY 是否有效。如主要 provider 失敗，系統會自動嘗試 OpenRouter 備援（需 OPENROUTER_API_KEY）。
94580 知識同步沒有執行？
先確認主機上的 CRON_SECRET 有設定，再用 systemctl list-timers 看 harmonyhub-sync-knowledge.timer 有沒有排到。Cron endpoint 是 GET /api/cron/sync-knowledge/，要帶 Bearer token，網址結尾的斜線不能省略。