Phase 3 上線 — 比價發包（邀廠商報價 + 得標通知）（2026-04-21）

嘿 理事長，

前陣子聊完「廠商可以先上平台被看見」的想法後，我把比價發包整套做出來了。已經上線，你方便時可以試試（要 5-10 分鐘就能摸完）。

你之前講的「發包流程要分比價（上傳報價單）跟招標（要招標文件）」——這一輪先把比價做完，正是你說的輕量版流程：通話 → 現場勘查 → 廠商提報價。招標（防水、外牆那種重大工程）等之後有實際案子時再補上。

一、你可以測的新功能（約 10 分鐘）

第 1 步：先發起一筆比價（管委會帳號）

1. 登入 https://harmonyhub.cc
2. 側邊欄「社區管理」→ 「比價發包」（今天新加的）
3. 點右上「發起比價」→ 填：
   • 工程標題（例：B棟三樓走廊天花板維修）
   • 工程範圍（20 字以上的說明）
   • 預算上限（選填）
   • 截止日期（至少明天以後）
   • 挑廠商：
     • 從廠商名錄挑：分類/區域篩選，勾選 1-5 家
     • 或外部邀請：手動加 Line 群裡認識的師傅，填姓名 + email（電話選填）
   • 送出 → 系統自動寄邀請信給每一家

第 2 步：請三家廠商各提一份報價

4. 內部廠商（已註冊三和雲）：登入 /dashboard/vendors（廠商專區）→ 「邀請中的比價」tab → 點進去填總金額、工期、保固、備註，選填上傳報價單 PDF
5. 外部廠商（沒帳號）：收到信 → 點裡面「前往報價」連結（一次性，10 天過期）→ 不需註冊就能填表單送出（金額、工期、保固；外部不能上傳附件）
6. 你收到郵件的連結請勿轉寄，系統會把轉寄過去的人擋在外面

第 3 步：比較三家並選定得標者

7. 回到 /dashboard/quotes/{id} 比價詳情頁
8. 上面有比較表格：金額 / 工期 / 保固 可點欄名排序（預設金額升序）
9. 選定按鈕旁會跳 modal，填 10 字以上的得標理由（只給你和稽核看，不會寄給廠商）
10. 確認後系統在背後做的事：
    • 得標廠商收信：「您已得標」+ 你的 email 作為後續聯絡人
    • 落選廠商收信：「感謝報價，本次未選定」+ 附上他自己提交的摘要 + 「詳情請洽承辦人：{你的名字} / {你的 email}」
    • 得標理由不會寄給任何廠商（只進 DB + 稽核紀錄）

第 4 步：試試取消流程（如果用不到可跳過）

11. 另開一筆比價 → 到詳情頁按「取消比價」→ 跳 modal，填 10 字以上說明
12. 所有被邀請的廠商（不管有沒有報過價）都會收到「比價已取消」+ 你寫的說明

順便測：廠商名片上傳修好了

13. 到 /vendors 頁面點「上傳名片」
14. 支援拖拉上傳了
15. 如果 AI 抓到的電話或 email 跟系統裡既有廠商撞號，會顯示：
    • 「更新既有廠商」（把新資料套到舊那筆）
    • 「新增為新廠商」（確認是不同家，強制建立）
    • 「取消」
16. 不會再像以前一樣直接擋你，一直說「已存在」

二、設計與安全重點（技術面摘要）

• 外部邀請連結是一次性：每家師傅一個獨立 token，提交過就失效，系統也不會存原始 token（只存雜湊）
• 落選廠商看不到得標者身份或金額：信件只告訴他「選了別人」+ 他自己報的摘要 + 你的聯絡方式
• 得標理由不會外洩：只進 DB award_reason 欄位 + 稽核紀錄的字數統計（不是原文）。要讓廠商知道為什麼沒中，請直接打電話或回信
• 同時兩個管委點「選定」：第一個會成功，第二個會跳「此比價已被其他管理員處理」（狀態機保護）
• 廠商報價中途撤回：你來選時如果那筆已 WITHDRAWN，會跳「所選報價已撤回或狀態變更」，不會意外把撤回的當得標
• 比價總邀請上限 10 家（避免濫發）
• 所有寫入都進稽核紀錄：發起、加邀請、選定、取消、廠商送出報價都有，但 meta 欄位絕不存 email、電話、金額、理由原文——只存「改了哪些欄位 / 件數 / 是否外部邀請 / 有沒有電話」這類 marker

三、v4 進度更新

還沒做，排在後面

四、需要你回我的幾件事

• 外部廠商沒辦法上傳附件（報價明細 PDF）——MVP 階段為了簡化 token 授權沒做。你覺得急嗎？現在他們要附明細只能用 email 寄給承辦人
• 得標信沒附「建議回覆期限」（例如「請於 X 日內回簽」）——要不要加？還是你喜歡每次自己打電話跟得標廠商對時間？
• 比價列表沒有全文搜尋——目前只按狀態分頁，數量多了以後要不要搜尋
• 如果你試下來覺得哪個地方很卡，寫任何形式的 feedback 給我，Line 訊息、語音都可以——連 UI 用詞、按鈕位置都可以吐槽

（以下是前面幾輪 Phase 2c / 2b / 2a / 1b 的交接內容）

Phase 2c 上線 — 裝修登記（含保證金匯款通知）（2026-04-20）

嘿 理事長，

今天再上一輪——裝修登記做完了。你之前說想要「住戶送申請、我核准後系統自動通知要匯多少保證金到哪個帳戶」這件事，整套流程都通了。還有幾個小巧思，順便交給你。

一、你可以測的新功能（約 10 分鐘）

第 0 步：先設定社區的存匯帳戶（只要做一次）

1. 用你的管委會帳號登入 https://harmonyhub.cc/login
2. 側邊欄「社區管理」→ 「社區設定」（這個今天新加的）
3. 填三欄：銀行名稱（例：國泰世華 建國分行）、帳號（只允許數字／空白／連字號）、戶名（例：朝代金站社區管理委員會）
4. 按「儲存」→ 顯示「已儲存」
5. 提醒：沒填這三欄就無法核准任何裝修申請，系統會擋你

第 1 步：住戶送一筆裝修申請

6. 換一個 Google 帳號（住戶）登入
7. 側邊欄「社區管理」→ 「裝修登記」
8. 點右上「新增裝修申請」→ 填：
   • 單位（例：A棟 5F-2）
   • 裝修類型：室內裝修 / 水電工程 / 隔間變更 / 外牆施作 / 其他
   • 施工說明（20 字以上即可）
   • 承包商 / 電話（選填）
   • 起迄日期
   • 保證金金額（0 ~ 1,000,000 NT$）
   • 附件：PDF 或圖片，最多 10 個（平面圖、報價單）
9. 送出 → 列表會出現「待審核」標籤

第 2 步：你核准那筆申請

10. 回到你的管委會帳號 → /dashboard/renovation
11. 上面會有一個「待審核」區塊列著這筆申請，點進去
12. 看完申請資料、附件，按**「核准」**
13. 系統在背後做的事：
    • 記錄核准時間、審核人
    • 寄 email 給住戶，信裡顯示：單位、施工期間、應繳保證金、銀行名稱、帳戶末 4 碼
    • 完整帳號只會出現在住戶登入後的申請詳細頁（信件裡絕對不會出現）
    • 稽核紀錄也不會寫入帳號原文，只會記錄「誰核准了哪一筆」

第 3 步：住戶收信後登入確認

14. 住戶收到標題「【三和雲】您的裝修申請已核准 — A棟 5F-2」的信
15. 信件末 4 碼只能看到 ******7890 這種樣子
16. 點信件裡的「前往申請頁面」→ 必須登入（中繼的 middleware 會擋）
17. 登入後在申請詳細頁會看到「保證金匯款帳戶」面板：
    • 銀行名稱、完整帳號、戶名
    • 每個欄位右邊有「複製」按鈕，方便住戶直接貼到網銀

第 4 步：駁回流程也踩一下

18. 住戶再開一筆新申請（例如明知有問題的）
19. 你點詳細頁的「駁回」→ 跳一個文字框要你寫理由，至少 10 字（不寫夠系統會擋）
20. 送出 → 住戶回到詳細頁會看到紅色「駁回理由」區塊

二、設計與安全重點（技術面摘要）

• 完整帳號不會流出信件：email 裡只有末 4 碼 + 銀行名稱，完整帳號只在登入後的詳細頁顯示給申請人、管理員、委員看
• 同一個帳號連點核准兩下只會成功一次，第二次會顯示「已被其他管理員處理」（避免兩個管委同時核准）
• email 寄送失敗不會讓申請倒退：申請還是 APPROVED 狀態，但「已寄出時間」不會填，之後有補寄 API 可以重來（這版沒有 UI 按鈕，如果你遇到這情況 LINE 我）
• 附件有 MIME 白名單（PDF / PNG / JPEG / WebP）+ 只接受我們系統上傳的連結，貼外部 URL 會被擋
• 列表頁不會洩漏附件連結：列表 API 只回傳附件數量，完整連結只在詳細頁（申請人或委員才能開）
• 所有變動都有稽核紀錄（送申請、核准、駁回、設定帳戶都會記，但都不會把帳號或駁回理由原文寫進去）
• 核准 + 稽核紀錄包在同一個 DB transaction：如果中途崩了，兩個都不會寫（不會發生「申請已核准但沒有紀錄」）

三、v4 進度更新

還沒做，排在後面

四、需要你回我的幾件事

• 核准信的欄位順序（單位／施工期間／應繳保證金／銀行／末 4 碼／連結）順嗎？要不要加什麼？
• 駁回理由 10 字會不會太多？我設成最少 10 字是怕管委懶得寫讓住戶看不懂
• 「社區設定」頁面目前只有「存匯帳戶」一個區塊，未來像管理辦法版號、通知信件署名這類的也可以丟這裡，你想先排哪個？

（以下是前幾輪 Phase 1b / 2a / 2b 的交接內容）

Phase 1b 上線 — 所有權人名冊 + 住戶自助驗證（2026-04-19）

嘿 理事長，

Phase 1b 今天也上線了。你之前想做的**「所有權人名冊 Excel 上傳 + 住戶掃 QR 自助驗證」**現在都能用了。請找時間踩踩看，踩到雷立刻 LINE 我。

一、你可以測的新功能（約 15 分鐘）

前置：用 cd27001347 登入上傳名冊

1. 到 https://harmonyhub.cc/login，用 cd27001347@gmail.com 登入
2. 側邊欄「社區管理」→「所有權人名冊」
3. 把你整理好的 朝代金站 所有權人 Excel 拖到上傳區
   • 欄位系統會自動對應（編號、所有權人、地址，棟別選填）
   • 如果沒對到我們也會彈出下拉讓你手動挑
   • 預覽前 10 筆，確認沒問題後點「確認匯入」
4. 匯入完成會顯示「新增 N 筆，更新 0 筆」
5. 下方可以搜尋地址或姓名確認資料有進去
6. 若名冊有更新，上傳同一份修正過的檔案就會自動覆蓋（以編號為準），不會整個砍掉重來

你上次貼的 Excel 如果欄名跟我們預設不一樣，第一次上傳會看到對應下拉選單；挑好之後同樣的檔案格式下次會自動對應。

接著：用另一個 Google 帳號走住戶自助驗證

這次做完總算把那個「沒下一步」的洞補起來：

7. 用新的 Google 帳號登入 https://harmonyhub.cc
8. 方法一：從你上傳名冊後產生的社區 QR（在「社區申請」通過信或「系統管理 → 待審申請」核准後的卡片）掃碼進入
   • 或方法二：/onboarding → 點「我是住戶」→ 貼上 8 碼邀請碼
9. 進入驗證精靈，只有三個畫面：
   1. 從下拉選單找到你的門牌（搜尋框可打地址或戶號）
   2. 輸入名冊上的所有權人姓名（系統會比對）
   3. 選身份（所有權人／配偶／直系親屬／親友／契約承租人／租客）＋ 用途（住家／工作室／辦公／住辦／其他）
10. 送出 → 自動跳 /dashboard，你就是這個社區的認證住戶了
11. 下次同一個帳號再掃同一個 QR 會直接看到「您已完成驗證」

故意踩雷測試

• 姓名輸入不對：系統會擋住，同時顯示你（主委 email）讓住戶聯絡
• 同一個帳號想再驗一次：系統會擋住，告訴他「已完成認證」
• 名冊有一列姓名空白：上傳時會列出第 N 列缺什麼，請你在原始檔案修完再傳

二、這個版本的安全和細節（技術面摘要）

• 姓名比對做部分比對，但至少 2 個字才算——避免「王」這樣單字匹配到任何姓王的名冊
• 比對成功後產生一個有時效的簽章（10 分鐘），送出時會重驗邀請碼還有效、名額沒爆掉，才真的把你加進社區
• 邀請碼的使用計數會自動累加，如果你日後想限制用次數可以改 maxUses（目前是 999）
• 同一小時內同一個帳號最多 10 次失敗比對，超過就必須找你確認
• 所有的變動都有稽核紀錄（誰上傳名冊、誰驗證成功、哪個身份），之後要追責很方便

三、已更新的 v4 進度

| 社區文件庫「只能看不能下載＋申請寄信」（兼職總幹事需管委會加簽）| ✅ 2b |

還沒做，排在後面

四、Phase 2a：公告管理也上線了（2026-04-19）

你之前說想要「公告可以丟 PDF/圖片，讓住戶點擊展開閱覽」跟「新增公告要選公告人的身分」——這兩個都做好了。

測試步驟（約 5 分鐘）

1. 進 https://harmonyhub.cc/dashboard/announcements — 原本的假資料都清掉了，從空白開始。
2. 點「新增公告」，跳出表單：
   • 公告人身分 下拉選單：主任委員／副主任委員／管理委員／監察委員／總幹事／兼職總幹事／管理員／社區幹事／物業管理／保全，最後有「其他」可以自訂
   • 標題、內容、類型（一般／緊急／活動）、到期日（選填）、置頂
   • 附件：可以傳 PDF 或圖片，最大 10 MB
3. 發佈後，清單會顯示：類型標籤、置頂圖示、標題、內容前 2 行、發佈者身份＋姓名、附件 pill。
4. 點進去看詳細頁：
   • PDF 附件會直接在頁面內嵌開啟（iframe 原生 PDF 瀏覽器）
   • 圖片附件會直接以大圖顯示
   • 如果是行動裝置上 PDF 跑不出來，下面會有「請點此開啟」的 fallback link
5. 你自己發的公告可以編輯或下架；住戶進來只能看不能動。

幾個設計重點

• 公告人身分是顯示用的（你自己選），不強制綁定你註冊時填的職位——你要說自己是主委就主委，大家看得到誰在上面寫東西，不能賴皮 😎
• 下架是軟刪除（把到期日設成當下）——後台資料還在，住戶就看不到了
• 只有「作者本人」或「系統管理員」可以編輯／下架；其他委員看得到但不能改別人的公告
• 附件只接受從我們系統上傳的 URL（Vercel Blob），防止有人貼外部惡意連結
• PDF iframe 有 sandbox，就算附件被調包也不會執行 JS

需要確認的

• 公告人身分下拉選單夠用嗎？要不要加／移除某些選項？
• PDF 直接 iframe 顯示你覺得夠清楚嗎？要不要加個放大鏡／翻頁按鈕？
• 置頂功能有用嗎，還是你不介意公告都按時間排？

五、Phase 2b：社區文件庫也上線了（2026-04-19）

你之前想要「社區規約、管理辦法、申請表格讓住戶能看但不能下載，需要就提出申請寄 email，而且兼職總幹事要管委會加簽才能寄」—— 全部做好了。

測試步驟（約 10 分鐘）

管理員端（登入管理員帳號）：

1. 進 https://harmonyhub.cc/dashboard/documents
2. 點「新增文件」：
   • 輸入標題、分類（自由輸入，例：社區規約／停車場管理辦法／申請表格）、選填說明
   • 上傳 PDF 或圖片（最大 10 MB）
   • 按「上傳文件」
3. 上傳後自動按分類歸類，同一分類會聚成一組

住戶端（用另一個帳號登入為住戶）：

4. 同個頁面，住戶也能看到所有文件但沒有上傳按鈕
5. 點任何文件 → 進到詳細頁：
   • PDF：直接在頁面內嵌開啟（沙箱 iframe，沒有下載按鈕）
   • 圖片：直接顯示
6. 需要文件副本就按「索取文件」，可選填原因送出
7. 按鈕狀態會變成「索取中」

回到管理員端：

8. 頁面上方會出現**「待處理索取」**區塊
9. 按「核准並寄出」→ 系統寄 email 給住戶，信裡有 7 天有效的下載連結
10. 點連結自動下載檔案

兼職總幹事加簽機制

這是 2b 最特別的地方：

11. 如果上面那個管理員是兼職總幹事（communityTitle = "兼職總幹事"），步驟 9 會變成「建議核准（送管委會加簽）」，不會直接寄出
12. 索取狀態變成「待管委會加簽」
13. 這時候主委（或任何管委：副主委 / 管理委員 / 監察委員）登入 → 看到「由 兼職總幹事・XXX 建議核准」 → 按「同意並寄出」→ email 才真的寄出

非兼職的總幹事（社區全職僱員）不需要加簽，可以直接「核准並寄出」。

試試駁回

14. 住戶索取後，管理員按「駁回」（需填寫至少 10 字的理由）
15. 住戶回到文件頁會看到「索取未通過」＋ 駁回理由，可以「重新索取」

安全設計摘要

• 檔案只接受從我們系統上傳的（Vercel Blob 域名白名單），不能貼外部惡意連結
• PDF iframe 有 sandbox，就算被調包也不會執行 JS
• 下載連結是 HMAC 簽章的 7 天權杖，過期自動 410
• 兩個管理員同時按核准，系統保證只有一個真的寄出（updateMany status guard）
• 住戶雙擊「索取文件」也不會送出兩筆（DB 層 partial unique index）
• 每次「索取 / 建議 / 核准 / 駁回 / 寄出 / 下載」都有稽核紀錄

已知限制（MVP 層次）

• PDF iframe 能右鍵「另存新檔」—— 我們設計上是「阻力不是防線」，如果住戶真的想保留檔案，寄信是正式管道
• 如果文件上架後又被封存，而此時已經有核准中的索取，那個索取的下載連結會顯示「文件已下架 410」——這個可以等真實案例出現再決定要不要自動駁回

想聽你踩完之後怎麼說

• 分類自動聚合（按你輸入的分類名稱）夠用嗎？還是你想要固定的下拉選單？
• 「索取」這個字眼你覺得 OK，還是想要改成「申請副本」「索閱」之類？
• 駁回需要 10 字理由會不會太多？

六、踩完後有什麼想法

• 名冊欄位對應邏輯好不好用？實際你的 Excel 能自動對應嗎？
• 住戶第一次用會不會卡在某一步？我比較擔心的是「搜尋門牌」那個下拉
• 要不要我們馬上排 Phase 2（公告附檔 / 文件庫 / 裝修登記）？還是先跑一段時間看看這兩輪在社區的實際使用？

隨時 LINE 我，不用客套。

Jason ＆ Claude 🫡