mindxassociates/solo-consult-booking-kit

Solo Consult Booking Kit — 獨立執業的初始諮詢預約系統

⚠️ 請先閱讀此項 — HIPAA 必要條件（在開始建構任何東西之前）

只有當此系統運行在已簽署商業夥伴協議（BAA）的 Google Workspace 帳戶中時，才能支援 HIPAA 規範。在符合以下所有條件之前，請勿建構、部署或將真實客戶資料放入其中：

1. 你擁有 Google Workspace（Business Starter、Standard、Plus 或同等級別的涵蓋版本），且使用你診所自己的網域 — 不是 免費的個人 Gmail 帳戶（@gmail.com）。個人帳戶無法簽署 BAA，且絕不應存放此系統或其資料。
2. Google Workspace BAA 已簽署。 在 Google Admin 控制台（管理員 → 帳戶 → 法律 / "Business Associate Amendment" — 確切選單名稱會隨時間改變）中，審閱並接受 Google Workspace / Cloud Identity 的 BAA，並記錄簽署日期。簽署是 Workspace 管理員的一次性點擊動作；如果你找不到該選項，請先停止並解決此問題 — 不要假設它已涵蓋而繼續進行。
3. 所有內容都位於該 Workspace 帳戶中。 Apps Script 專案、預約試算表、接收諮詢的行事曆，以及發送確認郵件的信箱，都必須屬於同一個 Workspace 使用者（你）。請勿在個人 Google 帳戶上執行任何部分，也不要將預約指向個人行事曆 — 個人帳戶不在 BAA 的涵蓋範圍內。
4. 帳戶強化已開啟： 已為該帳戶啟用兩步驟驗證（通行密鑰 / 進階保護更好），在密碼管理器中設定強大且唯一的密碼，以及由你控制的可復原選項。

軟體無法「獲得 HIPAA 認證」，此套件本身也無法使診所符合 HIPAA 規範。它採用支援 HIPAA 的保護措施（資料最小化、雜湊處理的過期管理連結、通用行事曆事件、資料保留清除、稽核日誌 — 請參閱 references/security-and-hipaa.md），並運行在會簽署 BAA 的供應商（Google）上。合規性還需要你自己的風險分析、政策、培訓以及隱私權保護慣例通知。如果以上任何必要條件缺失，AI 代理的首要工作是協助診所 owner 解決這些問題 — 而不是建構應用程式。

目的

為獨立執業的臨床醫師提供團體診所所使用的預約系統，而無需團體機制的負擔：

• A 部分 — 公開預約應用程式。 一個公開網頁（嵌入在診所網站上），潛在客戶在此回答簡短的合適性檢查（州別、付款方式、諮詢對象、語言），只會看到真正開放的時段 — 你所宣告的諮詢時段減去你真實行事曆的忙碌時間、休假時間和現有的預約 — 並預約免費的初始諮詢（預設 15 分鐘；可設定）。客戶會收到一封包含 .ics 檔案和私人重新安排/取消連結的確認郵件；你會收到最簡要的通知。提醒（約 24 小時前）和諮詢後跟進則由計時器觸發。
• B 部分 — 診所擁有者控制台（一個應用程式，三種檢視）。 一個私人的、需輸入 PIN 碼的應用程式，只有你能使用，它合併了團體診所分散在三種應用程式中的功能：
  • 我的諮詢 — 即將到來/過去/已取消的諮詢，點擊可查看詳細資訊，將過去的諮詢標記為未出席。
  • 可用時間 — 設定每週諮詢時段（允許分段設定日期）、特定日期工時、休假時間、接受新客戶的開關，以及預約設定（單一諮詢頻率上限、最低通知時間、緩衝時間、時段增量）；查看你的已解決可用時間，以及未來 7 天內預約頁面所計算出的確切開放時段。
  • 設定與工具 — 無需修改程式碼即可編輯所有郵件模板和預約規則，查看預約統計資料和稽核軌跡，匯出稽核/預約 CSV（絕不包含管理權杖）。

參考實作：兩個 Google Apps Script 網頁應用程式，由一個試算表和你的 Google 日曆支援。無第三方預約服務、無分析工具、無追蹤器。

此獨立版本刻意移除的內容（團體 → 獨立）

• 無「連接你的行事曆」應用程式。 在團體診所中，該應用程式的存在只有一個原因：每個提供者以自己的身份登入，將他們的行事曆以「對事件進行變更」的權限與診所的中央帳戶分享，並將行事曆 ID 註冊回預約系統。獨立執業的擁有者就是腳本擁有者和行事曆擁有者 — 預約應用程式已經以你的身份執行，並對你的行事曆擁有擁有者權限。沒有什麼需要分享，也沒有什麼需要註冊。設定只是：在「設定」分頁中輸入你的行事曆 ID（你主要行事曆的 ID 就是你的電子郵件地址；或者在同一個 Workspace 帳戶中建立一個專用的「初始諮詢」行事曆並使用其 ID），然後執行內建的 checkSetup() 並確認它回報 accessRole=owner 和 freebusy=OK。
• 無提供者名冊工作表和提供者名冊同步。 一位臨床醫師 = 一個設定列，包含姓名、證照、執業州別、保險網路、語言、服務年齡層、浮動費用標誌、個人簡介連結、時區、行事曆 ID。無同步工作，無提供者 ID 提供給任何人。
• 無提供者配對/路由引擎。 團體診所的精靈會將客戶導向正確的臨床醫師。獨立診所的精靈只檢查與你的合適性：錯誤的州別、你不接受的保險網路、你不服務的年齡層，或在需要時沒有浮動費用 → 會顯示明確的不合適訊息並附上你的聯絡電子郵件，絕不會讓客戶無路可走。
• 無任何多人提供者功能： 無共用名冊中的個別提供者 PIN 碼（一個擁有者 PIN 碼，經過雜湊處理，位於設定分頁）、無「代表編輯」功能、無提供者篩選器、無診所範圍的休假（你的休假就是你自己的休假）。

將此交給你的 AI 代理（給收到此套件的同事）

此套件是平台無關的：它是純 Markdown（開放式 AI Agent Skills 格式），可與任何有能力的 AI 代理搭配使用 — 無論是能載入技能的代理、有工作區的編碼代理，還是僅能聊天但已上傳檔案的代理。此資料夾中的 README.md 包含各平台的指示，而 PROMPT.md 包含可複製貼上的初始提示；無論哪條路徑，最終都會到達同一個地方：

1. 確認頂部的 HIPAA 必要條件已滿足（Workspace + 已簽署的 BAA + 帳戶強化）。如果尚未滿足，請先處理。
2. 回答下方的設定訪談 — 代理應該在建構前詢問一次，並記錄下來。
3. 讓代理建構並測試這兩個應用程式，使用 references/test-checklist.md 中的測試清單進行測試預約，然後才將你的公開連結切換到新的預約頁面。

在測試清單通過端到端驗證之前，請保留你舊的預約連結（如果有的話）作為備用。

給正在建構此系統的 AI 代理的指示（任何平台皆適用）

• 根據這些檔案工作，而非根據對類似系統的記憶。 在編寫程式碼之前，請閱讀此檔案和所有參考資料。當參考資料與擁有者的即時指示衝突時，以擁有者的指示為準，並將變更記錄下來。
• 你的交付成果是檔案 + 驗證過的步驟，無論使用何種工具。 將每個專案產生為可直接貼上的檔案（Code.gs、Index.html、Manage.html（如適用）、appsscript.json）。如果你能直接存取擁有者的 Google 帳戶或 Apps Script API/部署路徑，你可以進行部署 — 但只有在獲得擁有者同意後，並且你仍然要從服務結果進行驗證。如果你沒有該存取權限（大多數聊天代理都沒有），請交出檔案並逐步引導擁有者按照 references/setup-and-deploy.md 中的步驟操作：Google 登入、範圍授權和部署動作都必須由擁有者執行，無法執行這些動作的代理應明確說明，而不是暗示它已部署了某些東西。
• 以生產環境會使用的形式進行測試。 建立一個本機測試環境，模擬試算表/行事曆層，並以正式用戶端會傳送的確切參數格式呼叫每個伺服器函數。每次程式碼變更後都要執行測試，而不僅僅是最後才做。
• 絕不要求依賴供應商特定的功能。 此處的所有內容都是 Google Apps Script + Sheets + Calendar + Gmail 加上 Markdown。如果你的平台提供了便利功能（如部署整合、檔案工具），請使用它，但建構過程不能依賴它 — 同一個套件必須能在下一個擁有者的不同代理上運作。

設定訪談（收集一次，記錄下來，絕不猜測）

• 必要條件： Workspace 網域、將擁有所有內容的帳戶（例如 [email protected]）、已簽署的 BAA（日期）、已啟用兩步驟驗證。
• 診所： 診所名稱、你的姓名 + 證照（以客戶看到的格式）、診所聯絡電子郵件、通知電子郵件（可以是同一個）、網站 URL、隱私權政策 URL。
• 行事曆： 主要行事曆，或是同一個帳戶中的專用諮詢行事曆？其 ID 會放入設定中。（建議：專用行事曆 — 諮詢事件在視覺上保持分離，你可以分享該行事曆的空閒/忙碌狀態，而不會暴露你主要行事曆的內容。無論哪種方式，應用程式只會讀取空閒/忙碌狀態並寫入通用諮詢事件。）
• 合適性設定檔（驅動精靈的付款/資格選項 — 由設定產生，絕不硬編碼在頁面中）： 你取得執照的州別；你接受的保險網路、員工協助方案（EAP）和基金（確切的客戶端名稱）；自費和浮動費用（是/否，以及你公開使用的任何費用下限措辭）；你提供治療服務的語言；你服務的對象（成人 / 青少年 / 兒童 / 伴侶 / 家庭）；你是否會見位於美國以外的客戶（如果是：諮詢仍然免費，但後續治療僅限自費/浮動費用 — 精靈會相應地限制付款選項）。
• 預約規則（來自參考系統的預設值 — 確認或更改）： 諮詢長度 15 分鐘；預約窗口 14 天；最低通知時間 12 小時；時段間隔每 30 分鐘；忙碌事件前後的緩衝時間 10 分鐘；重新安排/取消截止時間 4 小時；提醒時間 24 小時前；諮詢後跟進時間在諮詢結束後 5 分鐘；每個客戶電子郵件/電話僅能有一個有效諮詢（開啟重複保護）。
• 要填入的可用時間： 你初始的每週諮詢時段 + 時區，這樣頁面在第一天就有實際的時段。（之後你會在控制台中維護這些設定。）
• 郵件措辭： 確認、提醒和跟進模板（使用 {ClientFirstName}、{EventDateTime}、{ProviderName} 等代碼）；跟進郵件所指的調查/後續步驟連結；寄件者名稱/地址（你的地址，或你帳戶上的「以...寄送」別名，例如 [email protected] — 別名需要額外一個 OAuth 範圍，請參閱部署參考）。
• 品牌形象： 你網站的公開頁面外觀（字型、文字顏色、按鈕/連結的強調色、邊角樣式）。公開頁面使用扁平網站風格 — 無入口網站玻璃/極光效果、無 Google 品牌標示、無原生瀏覽器對話方塊。
• 語言： 僅英文，還是雙語？參考系統支援第二種完整語言（一組翻譯過的題目，以客戶預約時使用的語言寄送郵件）。只有在你確實服務使用該語言的客戶時才加入。
• 隱私權通知： 客戶必須確認的簡短預約表格隱私權措辭（收集了哪些資料、電子郵件不用於監控緊急情況、美國的危機專線 988 / 911）。每次預約都會儲存確認時間戳記 + 通知版本。每當措辭更改時，更新版本字串。

各部分如何整合（一段話）

這兩個應用程式都以你的身份（USER_DEPLOYING）在你的 Workspace 帳戶中執行。預約應用程式是公開且匿名的：訪客永遠不會看到試算表或任何行事曆細節 — 可用時間僅從空閒/忙碌狀態計算。預約在腳本鎖定下進行，確保兩位訪客不會預約到同一個時段，它會在「預約」分頁中寫入一列，在你的行事曆上建立一個通用標題的事件（「初始諮詢 — <預約ID>」，最小描述，無客戶參與者），並寄送郵件給客戶（確認信 + .ics 檔案 + 私人管理連結，權杖僅以 SHA-256 雜湊值儲存）和給你（最小化的三類資訊，主旨不含客戶姓名）。一個 5 分鐘的計時器會傳送提醒和跟進郵件，並執行資料保留清除。控制台受 PIN 碼保護，讀取/寫入同一個工作簿，並且是唯一可以檢視完整預約詳細資訊的地方。完整的資料模型和優先級規則：references/architecture.md。

建構順序（請勿重新排序）

1. 工作簿 + 預約應用程式 根據 references/booking-app-spec.md 和 references/setup-and-deploy.md（建立試算表，執行 setupSheet()、checkSetup()、setupTriggers()，然後部署）。
2. 控制台應用程式 根據 references/console-app-spec.md（PIN 碼門禁、我的諮詢、可用時間、設定與工具）對應同一個工作簿。
3. 測試 使用 references/test-checklist.md — 真實的端到端測試預約、重複預約嘗試、透過郵件連結重新安排/取消、不合適的路徑、手動觸發提醒/跟進。
4. 上線： 將預約應用程式嵌入你網站的預約頁面，切換公開連結，保留舊連結作為備用，直到你順利接收到一個真實的預約。

給 AI 代理的嚴格規則（這些是昂貴的教訓）

• 範圍： 每當程式碼呼叫 SpreadsheetApp.openById 時，請宣告完整的 https://www.googleapis.com/auth/spreadsheets 範圍 — 唯讀範圍會導致每次此類呼叫都拋出錯誤。如果應用程式同時使用 GmailApp 和 MailApp 發送郵件，請宣告兩者 gmail.send 和 script.send_mail（僅 gmail.send 不涵蓋 MailApp，且錯誤會被 try/catch 吞沒 — 郵件會靜默地從未發送）。透過 GmailApp 從「以...寄送」別名發送還需要 gmail.settings.basic。行事曆功能需要在 manifest 中啟用 Calendar Advanced Service (v3)。
• 部署： 在首次部署之後，請務必將現有部署升級到新版本。切勿建立新的部署 — 新的 URL 會破壞所有嵌入和連結，且舊 URL 會繼續提供舊的程式碼。讀取部署的內容回來 / 驗證服務的 Markdown...