企業報告 × 後台改善提案

兩件事，想跟後台工程一起從根本解決

名單改成「每年一份、不再覆寫」，數字才會年年對得上；報告站改用專屬金鑰接後台，不再靠個人通行證每月手動換。

企業報告團隊整理，2026-11-11。頁面不含任何個人資料；人數皆為統計總數。

影響報告正確性

一、員工名單每年上傳＝一個事件

現在全公司只有一份名單，每次上傳就覆寫。結果同一家、同一年，後台兩個畫面跟成果報告給出三個不同的人數，去年的部門與職級分布也會被今年的人事異動改掉。

建議：每次上傳存成一份「年度名冊」快照，施測紀錄綁定當年名冊。

影響報告穩定性

二、報告站正式接上後台 API

報告站現在用一位管理者的個人登入通行證去讀後台，30 天到期就要人工換，下次到期是 11/19。正式的 SSO 串接，我方已做完，但卡在後台這邊還有參數與端點沒到位。

建議：給報告站一把專屬、唯讀、可撤銷的服務金鑰，取代個人通行證。

一張圖看懂差異

企業 A｜2025 成果報告（已交付）
131 人
報告出版當下的快照，以此為準
企業 A｜2025 後台儀表板
139 人
看「施測當時屬於哪家公司」，含之後離職者
企業 A｜2025 後台施測管理
76 人
只看「目前名單上還在職」的人

三個數字都不是程式算錯，而是「名單只有一份、會被覆寫」造成的口徑不同。名單年度化之後，這三個數字應該收斂成一個。

一、員工名單：從「一份年年改」變成「每年一份」

每次上傳名單都存成當年的名冊快照，舊年度的人數、部門、職級從此不會再被改動。

現況：上傳名單時後台做了什麼

依後台 dev 分支的員工匯入程式（2026-10-26 版）整理。

用 Email 比對
是不是既有員工
→
既有員工
直接覆寫部門、職級
→
新的 Email
新增一筆員工
→
這次名單沒出現的人
全部標成離職

已經有「年度紀錄」的雛形，但不夠用

  • 後台有一張 employee_yearly_log，上傳後會記下「這家公司、這一年、有哪些在職員工」。
  • 只記「誰、哪一年」，沒有存當時的部門、職級。
  • 每家每年只記第一次上傳；同年再傳修正版，這張表不會更新。
  • 儀表板的部門與職級分布，讀的仍是員工主檔的「今天的值」。

造成的實際問題

  • 同一家、同一年，施測管理 76、儀表板 139、成果報告 131，三個畫面三個數字。
  • 員工調部門、升職後，去年的部門與職級交叉分析也會跟著變。
  • 員工離職或轉到集團其他公司後，會從施測管理的舊年度消失。
  • 報告團隊無法回答「某一年當時的母數是多少」，只能以紙本成果報告為準。

建議做法：每次上傳＝一個「年度名冊」

新增｜名冊批次
每次上傳都留一筆紀錄，不覆蓋舊的
記錄公司、年度、上傳時間、上傳者、檔名、筆數、狀態（草稿／生效／作廢）。同一年可以重傳，新的一批生效，舊的一批改成作廢但保留，事後查得到。
新增｜名冊成員
把上傳當下的部門、職級等欄位一起凍結
每一批名冊存一份當下的成員明細（員工、部門、職級與其他人口學欄位）。之後員工主檔怎麼改，都不影響這份快照。
調整｜施測紀錄
施測時順手記下「屬於哪一批名冊」
統計某年時，母數＝當年生效名冊的人數，分布＝名冊成員當時的部門與職級。儀表板、施測管理都改用同一個口徑。
保留｜員工主檔
主檔繼續存「現在的值」
登入、寄信、帳號管理照舊用主檔，不影響現有功能；只有「年度統計」改看名冊快照。

過渡與驗收

舊資料怎麼處理

  • 2025 年以前：不回補，一律以已交付的成果報告為準。
  • 2026 年：用今年最後一次上傳的名單，建立第一份生效名冊。
  • 現有 employee_yearly_log 可以當第一版名冊的來源，或由新表取代。

做完怎麼確認

  • 同一家、同一年，儀表板與施測管理的人數一致。
  • 明年上傳新名單後，今年的人數、部門、職級分布一格都不變。
  • 後台畫面能看到每一批名冊的上傳紀錄，並選擇年度查詢。

二、報告站接後台：從「個人通行證」換成「專屬金鑰」

報告站是系統自動去抓數字，不是真人登入，適合用一把專門給它的唯讀金鑰，不必綁任何人的帳號。

現況：兩條路

路線怎麼運作目前狀態問題
舊路：個人通行證管理者登入後台後取得的登入憑證（JWT，一種有期限的數位通行證），交給報告站代為讀取儀表板 API。運作中30 天到期，要人工換；下一次到期 11/19。綁定個人帳號，人員異動就斷。過期時報告會退回靜態數字（另有備份快照兜底）。
新路：SSO＋代打層SSO（單一登入）由後台發給報告站一組身分參數；報告站伺服器端代為呼叫 /webapi/sso/dashboard/*，金鑰不進瀏覽器。卡住我方已完成；後台這邊尚缺參數與端點（見下方）。
我方已完成
  • 伺服器端代打層（Cloudflare Pages Functions）
  • 只允許指定端點的白名單
  • 新舊路線一鍵切換開關
  • 回呼網址（callback URL）已提供給後台登記
  • 交接文件已提供（8/14、8/19）
等後台提供
  • 三個 SSO 參數：登入服務網址、用戶端代號、用戶端密鑰
  • SSO 儀表板端點：8/14 實測回 404（找不到）
  • 兩份規格文件對儀表板權限名稱說法互相矛盾，需裁示以哪份為準
  • 雙方責任表仍有 5 項未勾
  • 以上都要部署到正式站，報告站才能真正使用

建議做法

建議主案
發一把「報告站專用」的服務金鑰
伺服器對伺服器的唯讀金鑰（例如 OAuth 的 client credentials 模式）：只能讀儀表板統計、可以限定公司範圍、可隨時撤銷、到期自動換發或期限拉長。不綁任何人的帳號，也不需要真人登入。金鑰只放在報告站伺服器的環境變數，不進程式碼、不進瀏覽器。
替代方案
照原規劃把 SSO 走完
若後台政策只開放 SSO，就請補齊三個參數、上線儀表板端點並裁示權限名稱。我方已準備好，收到參數約一個工作天內可完成串接與測試。
過渡期
11/19 前先避免斷線
新方案上線前，請協助延長現有通行證期限，或先提供一把較長效的唯讀憑證，避免每月人工更換與到期時報告退回靜態數字。

請後台工程回覆

以下六題回覆後，報告團隊就能排定時程；不確定的地方歡迎直接約時間討論。

名單年度化的方向是否可行？大約需要多少工期？

新增「名冊批次」與「名冊成員」、施測紀錄綁定名冊；或有更好的做法也請建議。

同一年重傳名單時，要以哪一批為準？

建議：最新一批生效、舊批改作廢但保留紀錄。也需要確認誰有權限「生效」一批名冊。

儀表板與施測管理，能否改成同一個年度口徑？

都以「當年生效名冊＋施測當時所屬名冊」計算，讓兩個畫面的人數一致。

報告站接後台，能否發一把專用的唯讀服務金鑰？

若可以，請告知申請方式、權限範圍、期限與撤銷方式。若只能走 SSO，請跳到第 5 題。

若走 SSO：三個參數、儀表板端點、權限名稱何時能到位？

包含正式站的上線時間，以及兩份規格文件以哪一份為準。

11/19 通行證到期前，能否先提供過渡方案？

延長期限或提供較長效的唯讀憑證，避免報告中斷。

本頁為內部溝通用，不含個人資料、金鑰或密碼。技術細節可另附交接文件。