API 參考

API 參考文件

從 CLAUDE.md 分離，完整 API 端點清單。AI 開發時可按需讀取。

---

API 規範

• Base URL：/api
• 命名風格：kebab-case，例：/api/hr/grade-distribution
• HTTP 方法：GET 查詢、POST 新增/動作、PUT 修改、DELETE 刪除
• 統一回應格式：

{
  "success": true,
  "data": { },
  "message": "操作成功"
}

API 總覽（175+ 支）

Controller	路徑前綴	端點數	說明
AuthController	/api/auth	5	登入、改密碼、忘記密碼、OTP驗證、重設密碼
HrController	/api/hr	120+	HR 全流程管理（含職別一致性檢查、記錄轉移）
ReviewController	/api/review	33	主管考核作業
NotificationController	/api/hr/notifications	9	通知範本與發送管理
BugReportController	/api/bug-reports	6	Bug 回報 CRUD + 截圖上傳刪除
AnnouncementController	/api/announcements、/api/hr/announcements	6	登入頁最新消息 + HR CRUD + login-meta
TaglineController	/api/taglines、/api/hr/taglines	5	登入 Hero + 今日要事標語 + HR CRUD

主要 API 端點

方法	路徑	說明
POST	/api/auth/login	登入
POST	/api/auth/change-password	修改密碼
POST	/api/auth/forgot-password	忘記密碼（發送 OTP）
POST	/api/hr/import	匯入員工名單 Excel
GET/POST	/api/hr/projects	年度專案管理
POST	/api/hr/projects/{id}/settle	執行年度結算
GET	/api/hr/projects/{id}/settlement-stats	年度結算統計
GET/POST/PUT/DELETE	/api/hr/virtual-departments	虛擬部門 CRUD
GET	/api/hr/periods/{id}/grade-distribution	等第配額
PUT	/api/hr/participants/{id}/grade	HR 強制調整等第
POST	/api/hr/participants/{id}/return	退回上一關
GET	/api/hr/periods/{id}/export	匯出 Excel 報表
GET	/api/hr/dashboard/*	儀表板各項數據
GET	/api/review/my-list	取得待評核名單
GET	/api/review/participants/{id}	取得考核表單
POST	/api/review/participants/{id}/submit	提交評分
POST	/api/review/participants/{id}/return	退回上一關
POST	/api/review/participants/{id}/save-draft	儲存草稿
POST	/api/review/participants/batch-submit	批次提交
GET	/api/hr/periods/{id}/start-notification-recipients	考核開始通知收件人
POST	/api/hr/periods/{id}/send-start-notification	發送考核開始通知
GET	/api/hr/periods/{id}/dept-report-recipients	部門考核報告收件人
POST	/api/hr/periods/{id}/send-dept-report	發送部門考核結果報告
POST	/api/hr/projects/{id}/interview-notify	發送面談通知給審核主管（附面談表 PDF）
POST	/api/hr/interviews/{id}/upload	上傳面談紀錄檔案
GET	/api/hr/interviews/{id}/pdf/{type}	下載面談表/追蹤表 PDF（type: interview/tracking）
DELETE	/api/hr/projects/{projectId}?password=	刪除專案（需 HR 管理員密碼，進行中不可刪）
POST	/api/hr/migrate-records	跨專案考核記錄轉移（含 dry-run 預覽）
GET	/api/hr/periods/{id}/protection-map	人員管理保護狀態查詢（週期/專案鎖定、部門確認）
POST	/api/hr/participants/{id}/annual-narrative-check	通過年度等第檢查站
DELETE	/api/hr/participants/{id}/annual-narrative-check	撤銷年度等第檢查站
PUT	/api/hr/participants/{id}/adjust-period-score	週期調分（等第審核用）
PUT	/api/hr/participants/{id}/adjust-score	年度調分（年度結算用）
GET	/api/hr/projects/{projectId}/annual-detail/{employeeId}	年度考核總覽（整合年中+年終+獎懲+調分）
GET	/api/hr/dashboard/flagged	異常標記列表
POST	/api/hr/participants/{id}/clear-flag	清除異常標記
POST	/api/hr/periods/{periodId}/recalc-ceilings	重新計算等第天花板
GET	/api/hr/projects/{projectId}/writeback-status	104 回寫狀態（專案層，回傳 interviewCandidates[] 含面談逐人狀態）
GET	/api/hr/interviews/{id}/scanned	預覽/下載面談掃描檔（JWT auth，blob）
GET	/api/hr/periods/{periodId}/writeback-status	104 回寫 per-dept 狀態（週期層，新版）
POST	/api/hr/periods/{periodId}/writeback-104	執行單部門 104 回寫（body: {virtualDeptName, hrPassword}）
POST	/api/hr/periods/{periodId}/close	週期結案（全部門 Success 後，body: {hrPassword}）
POST	/api/hr/periods/{periodId}/sync-104-leave	同步 104 假勤資料
POST	/api/hr/projects/{projectId}/sync-104-disciplinary	同步 104 獎懲資料
GET	/api/hr/job-level-mismatch	職別一致性檢查
POST	/api/hr/fix-job-level-mismatch	修正職別不一致
PUT	/api/hr/participants/{id}/dept-head	設定部門主管
PUT	/api/hr/participants/batch-dept-head	批次設定部門主管
GET	/api/hr/periods/{periodId}/cross-company-vdepts	跨公司虛擬部門查詢（HR 限定）
GET	/api/review/periods/{periodId}/cross-company-vdepts	跨公司虛擬部門查詢（主管版鏡像）
GET	/api/review/periods/{periodId}/override-logs?type=GradeReview|Settlement&forRole=hr|reviewer	超額說明歷程（按部門累積，支援退回重送）
GET	/api/hr/periods/{periodId}/rating-ratio-report?password=	評等比例一覽表 Excel 匯出（年中/年終，需 HR 管理員密碼）
GET	/api/hr/projects/{projectId}/rating-ratio-report?password=	評等比例一覽表 Excel 匯出（年度總結，需 HR 管理員密碼）

公告系統 API（AnnouncementController）

方法	路徑	Auth	說明
GET	/api/announcements/public	免登入	登入頁最新消息（依 IsPinned/PublishAt 排序，Take 30）
GET	/api/announcements/login-meta	免登入	登入頁 session chip（進行中週期 + 剩餘天數）+ 使用手冊 URL（取 SystemSetting Login:ManualUrl，預設 fallback /manuals/PAM_一般考核主管操作手冊.pdf）
GET	/api/hr/announcements	HR/Admin	HR 列表（含未上架）
POST	/api/hr/announcements	HR/Admin	新增
PUT	/api/hr/announcements/{id}	HR/Admin	編輯
DELETE	/api/hr/announcements/{id}	HR/Admin	刪除

標語系統 API（TaglineController）

方法	路徑	Auth	說明
GET	/api/taglines/public?category=login|today	免登入	回 IsActive + 依 SortOrder 排序（登入 Hero / 今日要事 tagline 輪播用）
GET	/api/hr/taglines?category=	HR/Admin	HR 列表（含未啟用，可依 category 篩選）
POST	/api/hr/taglines	HR/Admin	新增（需 Line1/Line2；Line3 僅 login 分類使用）
PUT	/api/hr/taglines/{id}	HR/Admin	編輯
DELETE	/api/hr/taglines/{id}	HR/Admin	刪除

部門行政（Coordinator）API（CoordinatorController）

方法	路徑	Auth	說明
GET	/api/coordinator/my-depts?periodId=	Coordinator/HR/Admin	我綁定的虛擬部門清單 + 進度摘要（total/completed/inProgress/forceFlag）
GET	/api/coordinator/dashboard-kpis?periodId=	Coordinator/HR/Admin	KPI 儀表板（截止日倒數 + 整體完成率 + 逾期主管 + 退件未重送 + 從未開始）
GET	/api/coordinator/periods/{periodId}/dept-participants?dept=	Coordinator/HR/Admin	部門所有考核案件（僅進度，無分數）
GET	/api/coordinator/periods/{periodId}/reviewers-progress?dept=	Coordinator/HR/Admin	各主管進度彙總
GET	/api/coordinator/periods/{periodId}/stage-progress?dept=	Coordinator/HR/Admin	關卡×主管×待處理員工明細（pendingEmployees 含 isReturned 標記）

HR 人員管理擴充 API（相關）

方法	路徑	Auth	說明
GET	/api/hr/coordinators?periodId=	HR/Admin	HR 後台行政綁定清單
POST	/api/hr/coordinators	HR/Admin	新增行政綁定（自動建 SystemUser）
PUT	/api/hr/coordinators/{id}	HR/Admin	更新綁定部門列表
DELETE	/api/hr/coordinators/{id}	HR/Admin	解除綁定

---

最後更新：2026/04/22 晚間（新增 Coordinator API 5 + 104 回寫 per-dept API 3，總覽端點數 ~185）