平台維運與管理
角色權限管理、社區上線流程、環境設定與日常維護。
角色與權限
| 角色 | 說明 | 需要社區 | 主要權限 |
|---|---|---|---|
| ADMIN | 系統管理員 | 否 | 全部功能、營運後台、角色管理、文件還原 |
| OPS | 營運教練 | 否 | 營運後台、跨社區案件、知識庫、文件還原 |
| COMMUNITY_ADMIN | 社區管理員 | 是 | 案件管理、邀請碼、名冊上傳、公告、文件庫、裝修審核、比價發包、廠商審核 |
| COMMITTEE | 管委會委員 | 是 | 案件查看與參與、爭議諮詢、文件索取共同簽核 |
| RESIDENT | 住戶（預設） | 是 | 案件查看、公告瀏覽、文件庫瀏覽與索取、裝修申請、AI 爭議諮詢、補助查詢 |
| VENDOR | 廠商 | 否 | 廠商專區、投標管理、公司資料、比價報名 |
| CONSULTANT | 顧問 | 否 | 諮詢專區、回覆諮詢問題 |
角色指派方式
- RESIDENT → 新帳號預設角色
- COMMUNITY_ADMIN → 建立社區時自動升級
- 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 | Vercel（自動部署，push to main 觸發） |
| 資料庫 | Neon Serverless PostgreSQL |
| 檔案儲存 | Vercel Blob（附件、名片圖片） |
| 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 — Neon 連線字串（pooler）
DIRECT_URL — Neon 直連（migrations 用）
BLOB_READ_WRITE_TOKEN — Vercel Blob 存取
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向市府（各縣市地政局或相關機關）查詢該社區是否已有組織報備紀錄
- 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 之後新增，需在 Vercel 生產環境設定：
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 = '...' 調整角色。
Vercel 部署失敗怎麼辦？
檢查 Vercel dashboard 的 build log。常見原因：TypeScript 錯誤、缺少環境變數、Prisma generate 未執行。
AI 功能無回應？
檢查 GOOGLE_GENERATIVE_AI_API_KEY 是否有效。如主要 provider 失敗，系統會自動嘗試 OpenRouter 備援（需 OPENROUTER_API_KEY）。
94580 知識同步沒有執行？
檢查 CRON_SECRET 環境變數是否已在 Vercel 設定。Cron endpoint: POST /api/cron/sync-knowledge，需 Bearer token。