# HR Portal v2.0 開發指南 本文件提供 HR Portal 專案的開發規範、最佳實踐和常見操作指南。 --- ## 📋 目錄 1. [環境設置](#環境設置) 2. [開發流程](#開發流程) 3. [代碼規範](#代碼規範) 4. [API 開發指南](#api-開發指南) 5. [資料庫操作](#資料庫操作) 6. [測試指南](#測試指南) 7. [常見問題](#常見問題) --- ## 環境設置 ### 前置需求 - Python 3.11+ - Node.js 20+ - Docker 24+ - PostgreSQL 16+ (或使用 Docker) - Git ### 後端環境設置 ```bash # 1. 克隆專案 cd W:\DevOps-Workspace\3.Develop\4.HR_Portal # 2. 創建 Python 虛擬環境 cd backend python -m venv venv # 3. 啟動虛擬環境 # Windows: venv\Scripts\activate # Linux/Mac: source venv/bin/activate # 4. 安裝依賴 pip install -r requirements.txt # 5. 配置環境變數 cp .env.example .env # 編輯 .env 填入實際值 # 6. 啟動資料庫 (Docker) cd ../database docker-compose up -d cd ../backend # 7. 啟動開發伺服器 uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 ``` ### 資料庫初始化 ```bash # 方式 1: SQLAlchemy 自動創建 (開發環境) # 啟動 FastAPI 時會自動創建表格 # 方式 2: 手動執行 SQL (生產環境推薦) cd database docker exec -i hr-portal-db-test psql -U hr_admin -d hr_portal < schema.sql # 測試資料庫 docker exec -i hr-portal-db-test psql -U hr_admin -d hr_portal < test_schema.sql ``` ### 前端環境設置 (待創建) ```bash # 待前端專案建立後補充 ``` --- ## 開發流程 ### 1. 創建新功能 #### Step 1: 規劃 1. 閱讀相關設計文件 (`2.專案設計區/4.HR_Portal/`) 2. 確認需求和業務規則 3. 設計 API 端點和資料結構 #### Step 2: 資料庫 1. 更新 Schema (如需要) 2. 創建 SQLAlchemy Model 3. 測試 Model 關聯 #### Step 3: 資料驗證 1. 創建 Pydantic Schemas 2. 定義 Create/Update/Response Schemas 3. 添加驗證規則和範例 #### Step 4: API 開發 1. 創建 API 路由文件 2. 實作端點邏輯 3. 添加錯誤處理 4. 測試 API #### Step 5: 文檔 1. 更新 API 文檔 2. 添加使用範例 3. 更新 PROGRESS.md ### 2. Git 工作流程 ```bash # 1. 創建功能分支 git checkout -b feature/your-feature-name # 2. 開發和提交 git add . git commit -m "feat: add your feature description" # 3. 推送到遠端 git push origin feature/your-feature-name # 4. 創建 Pull Request # 在 GitHub/Gitea 上創建 PR # 5. Code Review 後合併 git checkout main git merge feature/your-feature-name git push origin main ``` ### 3. Commit 訊息規範 遵循 [Conventional Commits](https://www.conventionalcommits.org/): ``` ():