證照上傳與 admin 撮合名稱顯示
兩項回報問題的技術分析

問題 2admin 撮合 UI 顯示資料庫 ID 而非診所／醫師名稱

回報症狀：撮合記錄頁的「診所彙總」與「醫師」欄位顯示 6a55f496d145549b341c1f60 這類 24 碼 ObjectId，難以辨識是誰。

結論

名稱顯示功能（計畫 29）已於 2026-07-19 由 commit 435b448 實作完成，並隨同一次 push 部署至 production。但目前的實作在自助註冊的帳號上會全面 fallback 回 ID——因為那些帳號的名稱欄位根本是空的或無意義。

三條獨立證據：回報畫面並非現行版本

1. 現行程式碼在結構上不可能印出完整 24 碼 ID apps/web/app/(admin)/admin/match-records/match-records-client.tsx:50

   function shortId(id: string): string {
     return id.length > 6 ? `…${id.slice(-6)}` : id;
   }

   畫面渲染的是「名稱（或替代文字）＋ …41c1f60 尾 6 碼 ＋ 複製按鈕」。完整 ID 只存在於 title 屬性與剪貼簿，永遠不會成為可見內文。回報畫面顯示完整 24 碼、無替代文字、無複製鈕，因此不是這版程式碼的輸出。

2. Production 執行的是包含此修正的版本

   對 https://yijingmatch.com/ 取得的 HTML 中 <title> 為「醫境媒合平台」，即品牌變更 commit c75eacd。該 commit 與名稱 enrich 的 435b448 屬同一次 push，且時序在其之後——因此 enrich 必然已一併上線。

3. Production 資料庫目前沒有任何撮合記錄

   TODO.md 與 16.上線前檢查表-簽核.md 均記載：2026-07-17 冒煙測試後資料已清除，dcm_prod 僅剩 admin 帳號 1 筆。而回報畫面顯示「撮合記錄 3 筆」與三列醫師資料——現行 production 無法產生該畫面。

名稱是怎麼被查出來的（現行實作）

服務層以批次 $in 查詢回填顯示名稱，屬 additive 欄位，不改變既有回應結構：

• STEP 1 · 進入點admin 呼叫 list／create／update 三條路徑其中之一libs/match-record/src/lib/match-record.service.ts:296, 312, 409
• STEP 2 · 統一 enrichenrichMatchRecordViews() 併行查兩張表match-record.service.ts:222–235
• STEP 3 · 查名稱lookupDoctorNames() 查 DoctorProfile.fullName；lookupClinicNames() 查 Clinic.name，皆帶 deletedAt: null 過濾match-record.service.ts:188–220
• STEP 4 · 前端顯示有名稱顯示名稱，否則顯示替代文字＋短 ID＋複製鈕match-records-client.tsx:146, 269

透過 gitnexus 的 call-graph 確認，enrichMatchRecordViews 的呼叫端確實涵蓋 listMatchRecords、createMatchRecordsForJobPost、updateMatchRecord 三者；診所彙總另走 lookupClinicNames（:456）。四條路徑全數接上，沒有遺漏——包含最初審查時擔心的「按更新後名稱消失」問題已被涵蓋。

真正的問題：名稱欄位在自助註冊時根本沒有被填入

這是本次分析最重要的發現。註冊流程建立角色殼時：

const profile = await DoctorProfileModel.create({ accountId });
//                                              ↑ 完全沒有 fullName

const displayName = email.split('@')[0];   // ← email 帳號前綴
const clinic = await ClinicModel.create({ accountId, name: displayName });

因此在真實使用情境下：

問題 1無法上傳醫師證照照片

回報症狀：找不到／無法使用證照照片上傳功能。

根因：已確認

15.上線部署整備runbook.md:128
「OBJECT_STORAGE_* 未設的環境（如本機 dev 預設）證照簽章上傳（F1-10）
  回 503，其餘功能不受影響。」

503 的觸發條件（唯一路徑）

整條判斷鏈非常明確，沒有其他分支會產生這個訊息：

• 1本機 .env 的 OBJECT_STORAGE_* 為空.env.example:34–38（預設即空白）
• 2createS3SignedUploadProviderFromEnv() 檢查 BUCKET／ACCESS_KEY／SECRET_KEY／REGION，任一為空即回傳 nulllibs/doctor/src/lib/s3-signed-upload.ts:145–152
• 3route 收到 null → 回 503 SERVICE_UNAVAILABLE「物件儲存尚未配置」app/api/doctor-profiles/me/license-upload-url/route.ts:43–53
• 4前端把 503 對映為「證照上傳服務尚未開通，請稍後再試，或聯繫客服。」profile-form.tsx:114–120

完整實作鏈路

上傳時實際發生什麼事

採用「presigned URL 直傳」設計——檔案不經過平台伺服器，由瀏覽器直接 PUT 到 R2，平台只負責簽發一把限時鑰匙：

• STEP 1醫師在 /profile 的證照列選擇檔案doctor-profile-form.tsx:708–718
• STEP 2前端先擋一次 MIME 型別，非 PDF／JPG／PNG 直接顯示錯誤、不送出profile-form.tsx:104–107
• STEP 3POST /api/doctor-profiles/me/license-upload-url，帶 contentTypeprofile-form.tsx:109
• STEP 4後端產生物件 key：licenses/{accountId}/{uuid}——以帳號命名空間化，防跨人覆寫與列舉license-upload.service.ts:34
• STEP 5回傳 presigned PUT URL（預設 300 秒有效、固定 content-type、上限 10 MB）signed-upload.ts:30, 33
• STEP 6瀏覽器直接 PUT 檔案至 R2；成功後把物件 key 回填至該證照列的 documentRefprofile-form.tsx:128–137

如何讓測試人員在本機真的測到上傳

只要補上 5 個環境變數，本機就能完整跑通上傳流程。但這裡有一個不可妥協的安全前提：

測試人員本機 .env 需補的 5 個鍵（名稱須與 config.ts:45–49 完全一致）：

OBJECT_STORAGE_ENDPOINT=https://<account_id>.r2.cloudflarestorage.com
OBJECT_STORAGE_BUCKET=dcm-license-docs-dev
OBJECT_STORAGE_ACCESS_KEY=<dev scoped token 的 access key>
OBJECT_STORAGE_SECRET_KEY=<dev scoped token 的 secret>
OBJECT_STORAGE_REGION=auto

補上後重啟 dev server，「服務尚未開通」即會消失。若不想開發環境接雲端，另一個選項是接受本機無法測上傳，把這項驗證留在正式環境進行。

其他可能的上傳失敗路徑（供日後排查參考）

本次事件與以下無關，但正式環境上線後若有真實使用者回報「傳不上去」，可依此對照：

建議真正需要處理的事項

把「已完成」與「實際仍有缺口」分開，避免把已完工的東西重做一遍。

延伸能不能在正式站開通註冊來測試？

關鍵不在「旗標開多久」，而在「誰會註冊」。這條軸線一分開，答案就清楚了。

為什麼「長期對外開放」不行——最核心的一個理由

16 表階段 2 共 8 個 🔒 阻斷項，目前已過 1 項（2-14 Email 驗證，2026-07-17）、尚有 7 項未過：

• 2-1／2-2／2-3：三份法遵文件律師定稿 ← 正等律師回覆，是唯一長桿
• 2-9：Atlas M0 → Flex（M0 完全沒有備份，存真實個資的前提）
• 2-10：Vercel Hobby → Pro（商業／對外用途的條款要求）
• 2-13：註冊限流啟用（防濫用）
• 2-15：機密輪替（DB 密碼／AUTH_SECRET／ADMIN_PASSWORD）

建議作法：用 seed script，完全不必開旗標

你想測的兩件事（證照上傳、admin 名稱顯示）需要的是「帳號存在」，不是「註冊開放」。正式站相對本機唯一多出來的東西，就是設定好的 R2——帳號怎麼來的無所謂。

專案已有 pnpm seed:admin（libs/auth/src/seed/seed-admin.cli.ts）可作為範本，擴充成建立 doctor／clinic 測試帳號的腳本即可。好處是零對外曝光窗口、可重複執行，日後每次要驗正式環境都能用。

附錄查證方法與證據基準

本次分析採雙知識圖譜交叉查詢，再回讀真實檔案驗證——圖譜只用於定位，所有結論皆以實際檔案內容與 git 實況為準。

• graphify（文件／架構圖譜）：定位到 license-upload.service.ts、signed-upload.ts、計畫 26 批次 3（M-06）等節點
• gitnexus（程式碼 call-graph）：確認 enrichMatchRecordViews 的三個呼叫端與兩個被呼叫端，證明四條路徑全接上。註：該索引的全文檢索索引缺失，關鍵字查詢降級，故僅採用精確 symbol 查詢結果
• 真實檔案驗證：本報告引用的每一處 檔案:行號 均經實際讀取確認
• git 實況：HEAD 736db3c ＝ origin/main，工作區乾淨
• production 實況：直接對 yijingmatch.com 取 HTML 確認部署版本