mindxassociates/独立咨询预约套件

独立咨询预约套件 —— 面向独立执业的初始咨询预约系统

⚠️ 先读这个 —— HIPAA前提条件（在构建任何东西之前）

此系统只有在签署了商业伙伴协议（BAA）的Google Workspace账户内运行时才能支持HIPAA合规性。在满足以下所有条件之前，请勿构建、部署或将真实客户数据放入其中：

1. 您拥有Google Workspace（Business Starter、Standard、Plus或同等覆盖版本），并托管在您执业机构的独立域名上 —— 而不是个人免费Gmail账户（@gmail.com）。个人账户无法签署BAA，且绝不可持有此系统或其数据。
2. Google Workspace的BAA已签署。 在Google管理控制台中（管理 → 账户 → 法律/“商业伙伴修正案”——确切的菜单名称会随时间变化），查看并接受Google Workspace / Cloud Identity的BAA，并记录签署日期。签署由Workspace管理员一次性点击完成；如果找不到该选项，请先解决此问题 —— 不要在假设已覆盖的情况下继续。
3. 所有内容都存在于该Workspace账户中。 Apps Script项目、预约电子表格、接收咨询的日历以及发送确认的邮箱都必须属于同一个Workspace用户（您自己）。不要在任何部分使用个人Google账户，也不要将预约指向个人日历 —— 个人账户不在BAA保护范围内。
4. 账户强化已启用： 已为该账户强制执行两步验证（通行密钥/高级保护更好），密码管理器中存有强唯一密码，且恢复选项由您控制。

软件无法“获得HIPAA认证”，此套件本身也不能使执业机构完全符合HIPAA要求。它基于支持HIPAA的防护措施构建（数据最小化、哈希过期的管理链接、通用日历事件、数据保留清理、审计日志——参见references/security-and-hipaa.md），并运行在愿意签署BAA的供应商（Google）上。合规性还需要您自己的风险分析、政策、培训以及隐私实践通知。如果以上任何前提条件缺失，代理的首要任务是帮助执业者解决该问题 —— 而不是构建应用。

目的

为独立临床医生提供群组实践中使用的预约系统，但没有群组相关的复杂机制：

• 部分A —— 公开预约应用。 一个公开网页（嵌入在执业机构的网站上），潜在客户可在其中回答简短的适配性检查（州、支付方式、咨询对象、语言），仅看到真正空闲的时段 —— 您声明的咨询小时数减去真实日历的繁忙时间、休假和现有预约 —— 并预订免费初始咨询（默认15分钟；可配置）。客户会收到一封包含.ics文件和私密改期/取消链接的确认邮件；您会收到一份简洁的通知。提醒（约24小时前）和咨询后跟进由定时器触发。
• 部分B —— 所有者控制台（一个应用，三种视图）。 一个仅您使用的、受PIN保护的应用，将群组实践中分散在三个应用的功能合并为一个：
  • 我的咨询 —— 即将到来/过去/已取消的咨询，点击查看完整详情，将过去的咨询标记为缺席。
  • 可用性 —— 设置每周咨询小时数（允许分时段拆分）、特定日期时间、休假、是否接受新客户以及预约设置（每位客户一次咨询的频率上限、最短通知时间、缓冲区、时段增量）；查看已解决的可用性和接下来7天的空闲时段，与预约页面计算的方式完全相同。
  • 设置与工具 —— 无需接触代码即可编辑每封邮件模板和预约规则，查看预约统计和审计跟踪，导出审计/预约CSV（绝不导出管理令牌）。

参考实现：两个Google Apps Script网络应用，由一个电子表格和您自己的Google Calendar支持。无第三方预约服务，无分析工具，无跟踪器。

独立版有意识地删除了什么（群组 → 独立）

• 没有“连接您的日历”应用。 在群组实践中，该应用存在的唯一原因是：每个服务提供者以“自己”的身份登录，在“对事件进行更改”权限下与执业机构的主账户共享他们的日历，并将日历ID注册回预约系统。独立执业者本身就是脚本所有者和日历所有者 —— 预约应用已经以您的身份运行，对您的日历拥有所有者访问权限。没有任何事情需要共享或注册。设置只需：在配置标签页中输入您的日历ID（主日历的ID就是您的电子邮件地址；或者在同一Workspace账户中创建一个专用的“初始咨询”日历并使用其ID），然后运行内置的checkSetup()并确认它报告accessRole=owner和freebusy=OK。
• 没有服务提供者名册工作簿和名册同步。 一位临床医生 = 配置中的一行，包含姓名、资质、持证州、网络、语言、服务年龄段、滑动费率标志、个人简介链接、时区、日历ID。无需同步作业，无需向他人传递提供者ID。
• 没有提供者匹配/路由引擎。 群组版向导将客户路由到正确的临床医生。独立版向导仅检查与您本身的匹配性：错误的州、您不接受的面板、不服务的年龄段、或需要滑动费率但未启用 → 显示清晰的“不匹配”消息及您的联系邮箱，绝不会死胡同。
• 没有多提供者相关功能： 没有共享名册中的每个提供者PIN（一个所有者PIN，哈希后存在配置标签页中），没有“代他人编辑”，没有提供者过滤器，没有执业范围的休假（您的休假就是您的休假）。

将此套件交给您的代理（针对收到此套件的同事）

此套件是平台中立的：它是纯Markdown格式（开放代理技能格式），可与任何有能力的AI代理配合使用 —— 可加载技能的代理、带有工作区的编码代理、或仅可聊天但上传了文件的代理。此文件夹中的README.md包含各平台的使用说明，PROMPT.md包含可复制粘贴的起始提示；两种方式最终都会到达同一处：

1. 确认顶部的HIPAA前提条件已满足（Workspace + 已签署BAA + 账户强化）。如未满足，请先处理该问题。
2. 回答下面的设置访谈 —— 代理应在构建前一次性询问完毕。
3. 让代理构建并测试两个应用，使用references/test-checklist.md中的测试清单进行测试预约，然后才将公开链接切换到新的预约页面。

在测试清单完全通过之前，保留旧预约链接（如有）作为备用。

给构建此套件的代理的说明（任何平台）

• 请根据这些文件工作，而不是依赖对类似系统的记忆。 在编写代码之前，请阅读此文件及所有参考资料。如果参考资料与所有者的实时指令冲突，以所有者指令为准，并且变更需记录在案。
• 您的交付物是文件 + 已验证的步骤，无论您使用什么工具。 将每个项目生成为可直接粘贴的文件（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将放入配置中。（建议：使用专用日历 —— 咨询事件在视觉上保持独立，并且您可以共享该日历的空闲/忙碌状态，而不暴露主日历的内容。无论哪种方式，应用只会读取空闲/忙碌状态并写入通用咨询事件。）
• 匹配档案（驱动向导的支付/资格选项 —— 从配置生成，绝不在页面中硬编码）： 您持证的州；您接受的保险网络、员工援助计划和基金（确切的面向客户名称）；自费与滑动费率（是/否，以及您公开使用的任何最低费用措辞）；您提供治疗所用的语言；您服务的对象（成人/青少年/儿童/情侣/家庭）；是否接待位于美国以外的客户（如果是：咨询仍然免费，但后续治疗仅限自费/滑动费率 —— 向导会相应地限制支付选项）。
• 预约规则（参考系统的默认值 —— 确认或更改）： 咨询时长15分钟；预约窗口14天；最短通知时间12小时；时段网格每30分钟；繁忙事件前后缓冲区10分钟；改期/取消截止时间4小时；提醒时间24小时前；咨询后跟进时间：咨询结束后5分钟；每位客户邮箱/电话仅一个活跃预约（重复预约防护开启）。
• 初始可用性： 您最初的每周咨询小时数 + 时区，以便页面第一天就有实际时段。（之后您将在控制台中维护这些信息。）
• 邮件措辞： 确认、提醒和跟进模板（令牌如{ClientFirstName}、{EventDateTime}、{ProviderName}）；跟进邮件指向的调查/后续步骤链接；发件人姓名/地址（您的地址，或您账户上的“发件别名”，如[email protected] —— 别名需要额外一个OAuth作用域，请参见部署参考）。
• 品牌： 您公开页面的网站风格（字体、文本颜色、按钮/链接强调色、边角样式）。公开页面使用扁平网站风格 —— 无门户玻璃/极光效果，无Google品牌，无原生浏览器对话框。
• 语言： 仅英文，还是双语？参考系统支持第二语言（一组翻译的问题集，邮件以客户预约时使用的语言发送）。仅当您实际服务使用该语言的客户时才添加。
• 隐私声明： 预约表单中客户必须确认的简短隐私措辞（收集了什么数据、该邮箱不用于紧急情况监控、美国危机热线988 / 911）。每次预约都会存储确认时间戳 + 声明版本。当措辞更改时，更新版本字符串。

整体结构（一段话）

两个应用都以您的身份（USER_DEPLOYING）在您的Workspace账户内运行。预约应用是公开且匿名的：访问者永远不会看到电子表格或任何日历详情 —— 可用性仅通过空闲/忙碌计算得出。在脚本锁保护下进行的预约（防止两个访问者占用同一时段）会在预约标签页写入一行，在您的日历上创建一个通用标题的事件（“初始咨询 —— ”，描述内容最少，无客户参与者），并向客户发送邮件（确认 + .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. 上线： 将预约应用嵌入您网站的预约页面，切换公开链接，保留旧链接作为备用，直到您成功接收一次真实预约。

给代理的硬性规则（这些都是昂贵的教训）

• 作用域： 当代码调用SpreadsheetApp.openById时，声明完整的https://www.googleapis.com/auth/spreadsheets作用域 —— 只读作用域会导致每次此类调用抛出异常。如果应用同时使用GmailApp和MailApp发送邮件，请同时声明****gmail.send和script.send_mail（仅gmail.send不涵盖MailApp，并且失败会被try/catch吞掉 —— 邮件静默地永不发送）。通过GmailApp使用发件别名发送还需要gmail.settings.basic。日历功能需要在清单中启用日历高级服务（v3）。
• 部署： 首次部署后，始终将现有部署升级到新版本。切勿创建新部署 —— 新URL会破坏每个嵌入和链接，旧URL继续提供旧代码。读取已部署的内容/验证提供的标记...

原文截断，但核心内容已翻译。