# SpectOcular Google Workflow Backend — Admin-Only Pilot

Use only the Google Workspace account:

`admin@spectocularhealth.com`

This account is under the SpectOcular Workspace BAA and has MFA/2-Step Verification enabled. Do not deploy from a consumer Gmail account.

## What this backend does

- Creates the root Drive folder: `SpectOcular Pilot Database`.
- Creates restricted folders:
  - `00_Master_Database_RESTRICTED`
  - `01_Sites`
  - `02_Retina_IQ_Reports`
  - `03_Monthly_Invoices`
  - `04_Audit_Exports`
  - `05_Templates`
  - `99_Admin`
- Creates the master spreadsheet: `SpectOcular_Master_Database_RESTRICTED_MFA_REQUIRED`.
- Tracks sequential subject IDs by site, e.g. `01-00001`.
- Stores the patient ↔ subject linkage in `Patient_Linkage_RESTRICTED_MFA_REQUIRED`.
- Creates subject folders and subfolders for signed consents, labs, records, imaging ZIPs, Retina IQ reports, invoices, and audit logs.
- Uploads files from the web portal to the correct subject folder.
- Saves OD / eyecare professional agreement submissions to `Eyecare_Professional_Agreements`, including signature date and signature image file links.
- Tracks Retina IQ billable images and creates monthly site invoice/offset PDFs.
- Sends invoice emails from/through `admin@spectocularhealth.com` and keeps notifications inside the Workspace environment.

## Deployment steps

1. Sign into Google as `admin@spectocularhealth.com`.
2. Confirm MFA/2-Step Verification is enabled.
3. Go to Google Drive and confirm you are in the SpectOcular Workspace, not personal Gmail.
4. Go to Apps Script and create a new project named `SpectOcular Pilot Workflow Backend`.
5. Paste `Code.gs` into the Apps Script editor.
6. Paste `appsscript.json` into the manifest file.
7. Save the project.
8. Run `setupSpectOcularGoogleWorkflow()` once.
9. Approve the requested permissions from `admin@spectocularhealth.com`.
10. Copy the returned values:
    - `rootFolderUrl`
    - `masterDatabaseUrl`
    - `portalToken`
11. Deploy as Web App:
    - Execute as: **Me / admin@spectocularhealth.com**
    - Who has access: for the pilot, use the most restrictive option that still works for the website; if you must use "anyone with the link," rely on the shared portal token and keep the URL off public pages.
12. Copy the Web App URL.
13. In the SpectOcular secure workflow page, paste:
    - Google Apps Script Web App URL
    - Portal Token
14. Create a test subject, upload a test PDF, and generate a test invoice.

## Security notes

- The master linkage file must remain restricted to `admin@spectocularhealth.com` and approved SpectOcular research/admin staff only.
- Do not give OD/site users direct access to the master spreadsheet.
- Do not use public Drive links for PHI.
- Do not forward PHI to consumer Gmail.
- Keep patient names and DOBs out of monthly invoices; invoices use de-identified clinic IDs and dates of scan.
- Google is the pilot workflow. Azure/custom authenticated backend should replace this for national scale.

## Retina IQ imaging ZIP upload support

This Code.gs includes the `uploadRetinaIQImaging` web-app action. It allows the Request Retina IQ page to upload a `.zip` imaging export into the SpectOcular Google Drive workflow after a Retina IQ request is submitted. Redeploy the Web App as a new version after replacing Code.gs.

## Retina IQ consent/release upload update

This version adds the `uploadRetinaIQConsentPacket` backend action. It lets the Request Retina IQ page generate a signed SpectOcular Patient Services Consent + Medical Release PDF and save it into the same Retina IQ request folder as the imaging ZIP.

Expected Drive location:

`SpectOcular Pilot Database / 02_Retina_IQ_Reports / Retina_IQ_Requests / Site XX / [Request ID + Clinic ID] / Signed_Consent_and_Medical_Release`

The upload is also logged in the `Document_Uploads` tab as `Retina IQ Patient Consent and Medical Release` and in the `Audit_Log` tab.


## Partner agreement submission support

This Code.gs includes the `saveAgreementInfo` web-app action. It lets the Eyecare Professional Agreement page save OD signup/agreement information to the master Google Sheet tab `Eyecare_Professional_Agreements`. The action also creates or updates a site record in the `Sites` tab and stores signature PNG files under:

`SpectOcular Pilot Database / 99_Admin / Eyecare_Professional_Agreements / Site XX - Practice`

After replacing Code.gs, run `setupSpectOcularGoogleWorkflow()` once so the new tab is created, then redeploy the Web App as a new version.

## Monthly attestation backend action

This Code.gs includes the `saveMonthlyAttestation` web-app action. It lets the Monthly Attestation page save OD monthly attestation records to the master Google Sheet tab `Monthly_Attestations`. It also creates a PDF copy in Google Drive and can email that PDF to `admin@spectocularhealth.com` when the `Email Completed PDF to Admin` button is used.

After replacing Code.gs, run `setupSpectOcularGoogleWorkflow()` once so the new `Monthly_Attestations` tab is created, then redeploy the Web App as a new version.