# TEPL DHMS — release candidate 1 (Sprint 7)

Branch `tata-demo` in both repos. It goes to the **TEPL demo / staging server
only** — never to the live servers, and never through the `deploy` branch.
Live hostels, PGs and dormitories are untouched: every TEPL module sits behind
the employee-hostel switches (`EMPLOYEE_SUITE`), and the API changes only add.

## What is in it

All 25 BRD items, built as real modules (Sprints 0–7):

| Sprint | Modules |
|---|---|
| 0 | Employee hostel kind, assignments, attachments, inbox, anonymous complaints, Excel reports and schedules, PWA manifest |
| 1 | Employee records and departments, leave policy (hostel → plant approval), shift roster and adherence |
| 2 | Discipline, grievance desk, monthly feedback, parcels, emergency contacts, lost and found |
| 3 | Cleaning rota, room inventory and work orders, laundry desk, staff attendance, BMS energy readings |
| 4 | Energy KPIs and alerts, quick outings and curfew, targeted notices and WhatsApp broadcasts, bus log, visitor reports |
| 5 | Events, emergency alerts and headcount, emergency team and drills, canteen meals and diets, canteen and ZoTag feeds |
| 6 | Leadership dashboard, sealed medical records (OHC only), special needs, roster and plant-leave feeds |
| 7 | Statutory compliance, laundry provider feed, pre-VAPT hardening |

## Deploying it

```bash
# backend
npm ci --include=dev           # the build needs TypeScript and Prisma, even on a production server
npx prisma migrate deploy      # adds 20261203… to 20261211… (all additive)
npm run build                  # makes dist/, which is not in git; the server and the seed both run from it
DEMO_PASSWORD='choose-one' npm run seed:enterprise-demo -- --reset   # demo data, if wanted

# frontend
npm ci && npm run build        # VITE_API_BASE_URL pointing at this backend
```

### Environment (backend `.env`)

| Variable | For | Notes |
|---|---|---|
| `NODE_ENV` | everything | `staging` for the VAPT server, `production` for go-live. Both refuse `AUTH_OTP_ECHO` and `CRM_TEST_CLOCK` at boot. |
| `MEDICAL_ENCRYPTION_KEY` | medical records, KYC ID numbers, and staff PAN, Aadhaar, UAN, PF and ESIC numbers | **Set before any real record goes in** (32+ random characters) and never change it — records sealed with one key do not open with another. Without it the server warns at boot and derives a key from `JWT_REFRESH_SECRET`. Keep a copy offline. |
| `SMS_PROVIDER`, `SMS_WEBHOOK_URL`, `SMS_WEBHOOK_TOKEN` | emergency SMS | `log` until TEPL picks a gateway. |
| `WHATSAPP_PROVIDER`, `WHATSAPP_TEMPLATE_EMERGENCY` | broadcasts, emergency | `log` keeps WhatsApp off the network. |
| `WHATSAPP_VERIFY_TOKEN`, `WHATSAPP_APP_SECRET` | WhatsApp receipts | Only with the Meta webhook. |

AUTH_OTP_ECHO and CRM_TEST_CLOCK must not be set on this server.

### After deploy

1. Sign in as the owner; check **Medical records → Who can open records** is
   only the OHC login(s).
2. Issue the machine keys (owner only): TEPL HR feed, BMS, ZoTag, laundry
   provider — Biometric → Add device, or each module's own screen. Hand each
   serial and key to its system owner; the key is shown once.
3. Compliance → **Load the standard list** for each block, then fill in the
   certificates' numbers and dates; give each an owner.
4. Run the checks below.

## Checks before handing it over

| Check | Result on 3 Nov 2026 |
|---|---|
| `npm run typecheck`, `npm run build` (both repos) | pass |
| `npm run test:isolation` | 22 / 22 |
| `npm run audit:permissions` | 2461 / 0 |
| `npm run smoke` — every TEPL section | pass. Outside TEPL, two known test problems come from master: the dormitory booking checks fail after 14:00 IST (time-dependent), and 12 student-import and trial-journey checks fail because their sheet rows predate master's complete-record rule |
| Browser check of each sprint's screens, desktop and 375 px | done per sprint |

## Known limits

- Matrix ID cards, TEPL's roster and HR APIs, the BMS API and the laundry
  firm's system: our endpoints and simulators are ready; the real systems are
  connected when TEPL opens them.
- SMS needs a gateway (`SMS_PROVIDER=webhook`).
- Staff are not tied to blocks, so a guard's emergency alert goes to the whole
  hostel; block filters are views, not a security boundary.
- Mobile: the web portal is the phone app (PWA, no offline cache).

## Security changes in this release (pre-VAPT review)

- Machine-feed keys (HR, BMS, asset tags, laundry) are issued and rotated only
  by the owner (MANAGE_STAFF). Uploading plant-approved leave needs the plant's
  approval right (APPROVE_PLANT_LEAVE).
- Each terminal sends only its own punch type (a canteen key cannot post gate
  swipes).
- Device calls: 120 a minute per serial; 10 wrong keys lock a serial for
  15 minutes; machine batches are read only after the key checks out; other
  large uploads need credentials before their body is read.
- BMS pull: public https only, checked on the address actually connected to
  (no DNS rebinding, IPv4-in-IPv6, CGNAT or reserved ranges); size-capped; the
  far end's reply is never echoed back.
- Medical access: nobody can grant it to themselves; the owner cannot reset an
  OHC login's password; OHC staff and the owner are told when a login gains it;
  the owner sees who holds it. Sealed values are bound to the tenant and
  employee (AES-GCM additional data, full-length tag); one damaged value no
  longer breaks a record. Appointment reminders carry the time only.
- Scheduled reports pause when the person who set them up can no longer run
  the report.
- WhatsApp broadcasts: at most 5 an hour per account.
- Anonymous feedback comments carry only their month.
- IDs named by the client (vendors, rooms, store blocks) are checked against
  the account before they are written.

See `docs/enterprise/vapt-scope.md` for the testers' brief.
