# Patient CRM module

## Included
- Organization-scoped CRM contact records for prospects, patients and partners, with optional links to registered patients.
- Interaction timeline for calls, emails, SMS and in-person contacts (manual logging).
- Follow-up tasks with due dates, priorities, assignees and completion state.
- Communication preference history by purpose and channel; withdrawal recorded as a new event.
- Draft campaigns, not automatically sent.
- CRM dashboard with contacts, prospects, overdue tasks and open follow-ups.
- Administrative/reception roles only. Clinical notes are not exposed in CRM.

## Setup
Run `php artisan migrate` after pulling the feature. Access the **Patient CRM** navigation item.

## Outstanding work before describing this as full production CRM
- Email/SMS delivery provider integration with explicit consent evaluation at send time, suppression lists, opt-out endpoints and delivery tracking.
- Automatic contact sync from patient registrations and visit lifecycle, duplicate resolution and deduplication.
- Staff-specific ownership filtering, granular permissions and organization policies.
- Pipeline and referral attribution, automated appointment reminders, feedback/satisfaction surveys, complaints and service cases.
- Retention, export/delete processes and privacy impact review.
- Real database, authorization, browser and security testing.

Do not send patient marketing messages from these draft records without independently verifying applicable law, consent and delivery-provider agreements.

## Event-triggered patient emails

Two transactional emails are now queued within the same database transaction as their triggering event:
- `appointment_booked`: after a receptionist books an appointment.
- `visit_completed`: after the physician completes the clinical encounter.

Each delivery has a unique (organization, appointment, event) key to avoid duplicate event records. Recipient email is captured when queued. The email includes no clinical details, links or meeting tokens.

Configure Laravel `MAIL_MAILER`, `MAIL_HOST`, `MAIL_PORT`, `MAIL_USERNAME`, `MAIL_PASSWORD`, `MAIL_FROM_ADDRESS`, and `MAIL_FROM_NAME` for an authenticated SMTP provider. Use SPF, DKIM and DMARC on the sending domain. Test using a non-production mailbox first.

Run `php artisan hms:send-patient-notifications` to send pending notifications. The command is scheduled every minute, requiring a running Laravel scheduler (`php artisan schedule:work` or system cron `schedule:run`). Failed deliveries retry up to three times. Confirm provider delivery and bounced-message handling separately.

The transport refuses the Laravel `log` mailer to avoid falsely reporting actual delivery. **Do not enable real sending until verified**: transactional notice legal basis, secure sender configuration, patient email ownership, delivery retry policy, and production scheduler operation. Automatic reminders, cancellations, reschedules and results notifications are not yet wired.

## Further notification events
Appointment reminders are queued hourly for visits approximately 24 hours ahead. Reception can cancel or reschedule scheduled appointments. The treating physician can release recorded laboratory results; the patient email contains no test values. SMTP and scheduler configuration remain necessary. Notification events are currently unique per appointment, so repeated rescheduling and multiple laboratory orders require additional handling before production use. Runtime tests have not been executed.