mindxassociates/solo-consult-booking-kit

Solo Consult Booking Kit — Sistema de Reserva de Consultas Iniciales para una Práctica Individual

⚠️ Lea esto primero — el requisito previo de HIPAA (antes de construir cualquier cosa)

Este sistema solo es compatible con HIPAA si se ejecuta dentro de una cuenta de Google Workspace con un Acuerdo de Asociado Comercial (BAA) firmado. No construya, implemente ni ponga datos reales de clientes hasta que se cumplan TODAS las siguientes condiciones:

1. Usted tiene Google Workspace (Business Starter, Standard, Plus o una edición cubierta equivalente) en su propio dominio de práctica — no una cuenta personal gratuita de Gmail (@gmail.com). Una cuenta personal no tiene BAA disponible para firmar y nunca debe contener este sistema ni sus datos.
2. El BAA de Google Workspace está firmado. En la consola de administración de Google (Admin → Cuenta → Legal / "Business Associate Amendment" — el nombre exacto del menú cambia con el tiempo), revise y acepte el BAA para Google Workspace / Cloud Identity, y conserve un registro de la fecha. La firma es un solo clic de un administrador de Workspace; si no puede encontrarlo, deténgase y resuélvalo primero — no continúe asumiendo que está cubierto.
3. Todo reside en esa cuenta de Workspace. Los proyectos de Apps Script, la hoja de cálculo de reservas, el calendario que recibe las consultas y el buzón que envía las confirmaciones deben pertenecer al mismo usuario de Workspace (usted). No ejecute ninguna parte de esto en una cuenta personal de Google y no dirija las reservas a un calendario personal — una cuenta personal está fuera del BAA.
4. El fortalecimiento de la cuenta está activado: Verificación en dos pasos aplicada para la cuenta (las claves de acceso / Protección Avanzada son mejores), una contraseña única y segura en un gestor de contraseñas, y opciones de recuperación que usted controla.

El software no puede estar "certificado HIPAA", y este kit no hace que una práctica cumpla con HIPAA por sí solo. Está construido con salvaguardas compatibles con HIPAA (minimización de datos, enlaces de gestión con hash que caducan, eventos de calendario genéricos, barrido de retención, registro de auditoría — consulte references/security-and-hipaa.md), y se ejecuta en un proveedor (Google) que firmará un BAA. El cumplimiento también requiere su propio análisis de riesgos, políticas, capacitación y un Aviso de Prácticas de Privacidad. Si falta alguno de los requisitos previos anteriores, el primer trabajo del agente es ayudar al propietario a solucionarlo, no construir las aplicaciones.

Propósito

Brindar a un clínico individual el sistema de reservas que utiliza una práctica grupal, sin la maquinaria grupal:

• Parte A — Aplicación de reserva pública. Una página web pública (incrustada en el sitio web de la práctica) donde un posible cliente responde una breve verificación de idoneidad (estado, pago, para quién es la consulta, idioma), ve solo los espacios realmente disponibles — sus horas de consulta declaradas menos las horas ocupadas de su calendario real, días libres y reservas existentes — y reserva una consulta inicial gratuita (15 minutos por defecto; configurable). El cliente recibe un correo electrónico de confirmación con un archivo .ics y un enlace privado de reprogramación/cancelación; usted recibe una notificación mínima. Los recordatorios (~24h antes) y los seguimientos posteriores a la consulta se ejecutan con un temporizador.
• Parte B — Consola del propietario (una aplicación, tres vistas). Una aplicación privada, protegida por PIN, que solo usted usa, que fusiona lo que una práctica grupal divide en tres aplicaciones:
  • Mis consultas — consultas próximas / pasadas / canceladas, detalles completos al hacer clic, marcar una consulta pasada como inasistencia.
  • Disponibilidad — establecer horas semanales de consulta (se permiten días divididos), horas específicas por fecha, días libres, aceptar nuevos clientes activado/desactivado y configuraciones de reserva (un límite de frecuencia de consulta, aviso mínimo, buffers, incremento de espacios); ver su disponibilidad resuelta y los próximos 7 días de espacios abiertos exactamente como los calcula la página de reserva.
  • Configuración y herramientas — editar cada plantilla de correo electrónico y regla de reserva sin tocar el código, ver estadísticas de reservas y el registro de auditoría, exportar auditoría / reservas CSV (nunca los tokens de gestión).

Implementación de referencia: dos aplicaciones web de Google Apps Script respaldadas por una hoja de cálculo y su propio Calendario de Google. Sin servicio de reserva de terceros, sin análisis, sin rastreadores.

Lo que la edición individual elimina deliberadamente (grupal → individual)

• Sin aplicación "Conecta tu calendario". En una práctica grupal, esa aplicación existe por una razón: cada proveedor, iniciando sesión como sí mismo, comparte su calendario con la cuenta central de la práctica con permisos de "Hacer cambios en eventos" y registra el ID del calendario de vuelta en el sistema de reservas. Un propietario individual es el propietario del script y el propietario del calendario — la aplicación de reserva ya se ejecuta como usted, con acceso de propietario a su calendario. No hay nada que compartir y nada que registrar. La configuración es solo: coloque el ID de su calendario en la pestaña Config (el ID de su calendario principal es simplemente su dirección de correo electrónico; o cree un calendario dedicado "Consultas iniciales" en la misma cuenta de Workspace y use su ID), luego ejecute la función integrada checkSetup() y confirme que informa accessRole=owner y freebusy=OK.
• Sin libro de trabajo de lista de proveedores ni sincronización de lista. Un clínico = una fila de Config con nombre, credenciales, estados con licencia, paneles, idiomas, edades atendidas, indicador de escala móvil, enlace de biografía, zona horaria, ID de calendario. Sin trabajo de sincronización, sin IDs de proveedores entregados a nadie más.
• Sin motor de coincidencia/enrutamiento de proveedores. El asistente grupal dirige a un cliente al clínico adecuado. El asistente individual solo verifica la idoneidad contra usted: estado incorrecto, un panel que no acepta, un grupo de edad al que no atiende, o sin escala móvil cuando se requiere → un mensaje claro de no idoneidad con su correo electrónico de contacto, nunca un callejón sin salida.
• Sin nada multiproveedor: sin PINs por proveedor en una lista compartida (un PIN de propietario, con hash, en la pestaña Config), sin "editar en nombre de", sin filtro de proveedor, sin tiempo libre para toda la práctica (su tiempo libre es solo su tiempo libre).

Entregando esto a su agente (para el colega que recibe este kit)

Este kit es independiente de la plataforma: es Markdown plano (el formato abierto de Habilidades de Agente) y funciona con cualquier agente de IA capaz — un agente que carga habilidades, un agente de codificación con un espacio de trabajo, o un agente solo de chat con los archivos subidos. README.md en esta carpeta tiene las instrucciones por plataforma y PROMPT.md tiene una instrucción inicial de copiar y pegar; cualquiera de las dos rutas termina en el mismo lugar:

1. Confirme que se cumple el requisito previo de HIPAA al principio (Workspace + BAA firmado + fortalecimiento). Si no es así, hágalo primero.
2. Responda la entrevista de configuración a continuación — el agente debe preguntar una vez, antes de construir.
3. Permita que el agente construya y pruebe ambas aplicaciones, ejecute la lista de verificación de prueba en references/test-checklist.md con reservas de prueba, y solo entonces intercambie sus enlaces públicos a la nueva página de reserva.

Mantenga su antiguo enlace de reserva (si existe) activo como respaldo hasta que la lista de verificación de prueba pase de extremo a extremo.

Instrucciones para el agente que construye esto (cualquier plataforma)

• Trabaje a partir de estos archivos, no de la memoria de sistemas similares. Lea este archivo y cada referencia antes de escribir código. Cuando una referencia y la instrucción en vivo del propietario entren en conflicto, la instrucción del propietario prevalece y el cambio se registra.
• Su entregable son archivos + pasos verificados, sean cuales sean sus herramientas. Produzca cada proyecto como archivos listos para pegar (Code.gs, Index.html, Manage.html cuando corresponda, appsscript.json). Si tiene acceso directo a la cuenta de Google del propietario o a una ruta de API/implementación de Apps Script, puede implementar — pero solo con la autorización del propietario, y aún así verifica desde el resultado servido. Si no tiene ese acceso (la mayoría de los agentes de chat no lo tienen), entregue los archivos y guíe al propietario a través de references/setup-and-deploy.md clic por clic: el inicio de sesión de Google, la autorización de alcances y las acciones de implementación son responsabilidad del propietario, y un agente que no puede hacerlas debe decirlo claramente en lugar de implicar que implementó algo.
• Pruebe en las formas que usa la producción. Construya un arnés local que simule la capa de hoja de cálculo/calendario y llame a cada función del servidor con las formas de argumento exactas que envía el cliente implementado. Ejecútelo después de cada cambio de código, no solo al final.
• Nunca requiera una característica específica del proveedor. Todo aquí es Google Apps Script + Hojas de cálculo + Calendario + Gmail más Markdown. Si su plataforma ofrece una conveniencia (una integración de implementación, una herramienta de archivos), úsela, pero la construcción no debe depender de ella — el mismo kit tiene que funcionar para el próximo propietario en un agente diferente.

Entrevista de configuración (recopilar una vez, escribir, nunca adivinar)

• Requisito previo: dominio de Workspace, la cuenta que será propietaria de todo (p. ej., [email protected]), BAA firmado (fecha), Verificación en dos pasos activada.
• Práctica: nombre de la práctica, su nombre + credenciales como los clientes deben verlos, correo electrónico de contacto de la práctica, correo electrónico de notificación (puede ser el mismo), URL del sitio web, URL de la política de privacidad.
• Calendario: calendario principal, o un calendario de consultas dedicado en la misma cuenta. Su ID va en Config. (Recomendado: calendario dedicado — los eventos de consulta se mantienen visualmente separados, y puede compartir la disponibilidad de ese calendario sin exponer el contenido de su calendario principal. De cualquier manera, la aplicación solo lee disponibilidad y escribe eventos de consulta genéricos).
• Perfil de idoneidad (impulsa las opciones de pago/elegibilidad del asistente — generado desde Config, nunca codificado en la página): estados en los que tiene licencia; paneles de seguros, EAP y fondos que acepta (nombres exactos para el cliente); pago particular y escala móvil (sí/no, y cualquier redacción de piso que use públicamente); idiomas en los que ofrece terapia; a quién atiende (adultos / adolescentes / niños / parejas / familias); si ve clientes ubicados fuera de los EE. UU. (si sí: las consultas siguen siendo gratuitas, pero la terapia continua es solo pago particular/escala móvil — el asistente restringe las opciones de pago en consecuencia).
• Reglas de reserva (valores predeterminados del sistema de referencia — confirme o cambie): duración de la consulta 15 min; ventana de reserva 14 días; aviso mínimo 12 horas; cuadrícula de espacios cada 30 minutos; buffer de 10 minutos alrededor de eventos ocupados; límite de reprogramación/cancelación 4 horas; recordatorio 24h antes; seguimiento posterior a la consulta 5 minutos después de que finalice la consulta; una consulta activa por correo electrónico/teléfono del cliente (protección contra duplicados activada).
• Disponibilidad inicial: sus horas semanales de consulta iniciales + zona horaria, para que la página tenga espacios reales desde el primer día. (Las mantendrá en la Consola después).
• Redacción de correo electrónico: plantillas de confirmación, recordatorio y seguimiento (tokens como {ClientFirstName}, {EventDateTime}, {ProviderName}); el enlace de encuesta / próximos pasos al que apunta el correo de seguimiento; el nombre/dirección del remitente (su dirección, o un alias de envío en su cuenta como [email protected] — los alias necesitan un alcance OAuth adicional, consulte la referencia de implementación).
• Marca: el aspecto de su sitio web para la página pública (fuentes, color de texto, color de acento para botones/enlaces, estilo de esquina). La página pública usa un estilo de sitio web plano — sin portal de vidrio/aurora, sin marca de Google, sin diálogos nativos del navegador.
• Idioma(s): solo inglés, o bilingüe? El sistema de referencia admite un segundo idioma completo (un conjunto de preguntas traducidas, correos electrónicos en el idioma en que el cliente reservó). Agréguelo solo si realmente atiende clientes en ese idioma.
• Aviso de privacidad: la redacción de privacidad del formulario de reserva que los clientes deben aceptar (qué se recopila, que el correo electrónico no se monitorea para emergencias, línea de crisis 988 / 911 en EE. UU.). Cada reserva almacena la marca de tiempo de reconocimiento + versión del aviso. Aumente la cadena de versión cada vez que cambie la redacción.

Cómo encaja todo (un párrafo)

Ambas aplicaciones se ejecutan como usted (USER_DEPLOYING) dentro de su cuenta de Workspace. La aplicación de Reserva es pública y anónima: los visitantes nunca ven la hoja de cálculo ni ningún detalle del calendario — la disponibilidad se calcula solo a partir de la disponibilidad. Una reserva, hecha bajo un bloqueo de script para que dos visitantes no puedan tomar el mismo espacio, escribe una fila en la pestaña Citas, crea un evento con título genérico ("Consulta inicial — ", descripción mínima, sin asistente cliente) en su calendario, y envía un correo electrónico al cliente (confirmación + .ics + enlace de gestión privado, token almacenado solo como un hash SHA-256) y a usted (mínimo de triaje, sin nombre del cliente en el asunto). Un temporizador de 5 minutos envía recordatorios y seguimientos y ejecuta la limpieza de retención. La Consola está protegida por PIN, lee/escribe el mismo libro de trabajo y es el único lugar donde se ven los detalles completos de la reserva. Modelo de datos completo y reglas de precedencia: references/architecture.md.

Orden de construcción (no reordenar)

1. Libro de trabajo + Aplicación de reserva según references/booking-app-spec.md y references/setup-and-deploy.md (cree la hoja, ejecute setupSheet(), checkSetup(), setupTriggers(), implemente).
2. Aplicación de consola según references/console-app-spec.md (protección PIN, Mis consultas, Disponibilidad, Configuración y herramientas) contra el mismo libro de trabajo.
3. Prueba con references/test-checklist.md — reserva de prueba real de extremo a extremo, intento de doble reserva, reprogramación/cancelación a través del enlace enviado por correo electrónico, ruta de no idoneidad, recordatorio/seguimiento manual.
4. Puesta en producción: incruste la aplicación de Reserva en la página de reserva de su sitio web, intercambie enlaces públicos, mantenga el enlace antiguo como respaldo hasta que haya tomado una reserva real correctamente.

Reglas estrictas para el agente (estas son las lecciones costosas)

• Alcances: declare el alcance completo https://www.googleapis.com/auth/spreadsheets cuando el código llame a SpreadsheetApp.openById — el alcance de solo lectura hace que cada llamada de este tipo falle. Si la aplicación envía correo con ambos GmailApp y MailApp, declare ambos gmail.send y script.send_mail (gmail.send solo no cubre MailApp, y los fallos se tragan por try/catch — el correo silenciosamente nunca se envía). Enviar desde un alias de envío a través de GmailApp también necesita gmail.settings.basic. Las características del Calendario necesitan el Servicio Avanzado de Calendario (v3) habilitado en el manifiesto.
• Implementaciones: después de la primera implementación, siempre incremente la implementación existente a una Nueva versión. Nunca cree una nueva implementación — una nueva URL rompe cada incrustación y enlace, y la URL antigua sigue sirviendo código antiguo. Lea el contenido implementado de vuelta / verifique el marcado servido para confirmar que la versión correcta está activa.