使用指南 (User Guide)
歡迎來到 瑞成工程專案管理系統（Rui-Cheng PMS） 開發者文件。本指南涵蓋開發、測試、部署與擴充瑞成 PMS 所需的一切。
瑞成 PMS 是結構技師事務所（瑞成土木）內部使用的工程專案管理工具。 終端使用者操作手冊與領域規則（六大分類、三層權限、燈號預警）請見另一個獨立發佈的 user-docs 使用手冊站。
快速導覽
| 區塊 | 說明 |
|---|---|
| 快速開始 Getting Started | clone → 設定 → 跑起來 |
| 架構與 API Guide | Route Handlers、Server Actions、RBAC 守衛模式 |
| 測試 Testing | Vitest 單元 + Playwright e2e、覆蓋率門檻 |
| 部署 Deployment | Zeabur 部署、環境變數 |
| 變更紀錄 Changelog | 版本歷史 |
AI 開發流程（Claude Code）
本專案以 Claude Code + Athena agent 團隊進行開發。以下指南說明 spec→implement→qa→commit 的開發迴圈，與瑞成 PMS 的產品功能無關，僅供維護本 repo 的工程師參考：
| 指南 | 說明 |
|---|---|
| Quick Start (Guide) | 逐步首次執行 |
| First Epic Walkthrough | 完整 epic pipeline 示範 |
| Deploy Guide | 上線部署檢核 |
| Fork Security Setup | fork 後的 secret 輪替 |
| Memory System | agent 記憶分層機制 |
| AI Agent Team | 12 個 agent 角色與呼叫 |
| Custom Agents | 撰寫你自己的 Claude Code agent |
| Autopilot Mode | 信心分數閘控的自動執行 |
技術棧
| 層級 | 技術 |
|---|---|
| 框架 | Next.js 16 App Router |
| UI | React 19 + TypeScript + Tailwind v4 + shadcn/ui（Rei-Chen 品牌藍） |
| 登入 | Auth.js v5（Credentials，工牌編號登入 R00001，JWT 無狀態 session） |
| 資料庫 | Drizzle ORM + PostgreSQL 15 |
| 權限 | 三層 RBAC：管理員 admin／行政 operator／一般 staff（10 旗標權限矩陣，伺服器端 re-read live role） |
| 領域引擎 | components/rc/（六大分類、業主工作日燈號、母子追加案、稽核 rcLog） |
| 測試 | Vitest + Playwright（db-free 層 ≥80% 覆蓋率門檻） |
| 部署 | Zeabur（單一服務，next-app/） |
| AI 開發 | Claude Code + Athena agent 團隊 |
不在本系統範圍內（產品已明確排除，請勿加回）：金流／訂閱（Stripe／ECPay）、OAuth／2FA、LINE 整合、Email 通知、檔案上傳（NAS 僅貼連結）。