# Enterprise API guide for the mobile team

Where to find what you need to build an Enterprise screen. The rules that differ for
Enterprise are in [mobile-contract.md](mobile-contract.md). To get a server to test against,
see [demo-server.md](demo-server.md). What's built on mobile, and what's still to build, is in
`docs/ENTERPRISE_SPRINT_PLAN.md` in `hostelcare-mobile`.

## The rules that matter

1. **Sign in with `supportsEnterprise: true`.** Without it, an Enterprise account gets
   `403 ENTERPRISE_APP_UPDATE_REQUIRED`.
2. **Decide from `features` and `perms`, not from the role.** Both come with the signed-in
   user. A custom role can hold any set of permissions. An Enterprise feature never counts as
   on unless the server lists it.
3. **Expect `403 FEATURE_OFF`** from any route whose module the tenant doesn't have. Treat it
   as a bug in the screen's gate, not as something to show the user.
4. **Never show money.** Blocked routes and blanked fields are listed in [mobile-contract.md](mobile-contract.md).
5. **Other tenant kinds must not change.** They never receive the Enterprise fields, so every
   new field is optional in your models.
6. **Health data doesn't stay on the phone.** Never cache `/api/medical`, `/api/special-needs`
   or `/api/emergency`, or staff lists carrying a masked Aadhaar. Every read of a medical record
   has to reach the server, because the server logs it.

## Where each request is defined

The web client is the reference. For the exact parameters of any call, read:

| What | Where |
|---|---|
| Every call and its arguments | `hostelcare-frontend/src/lib/api.ts` |
| Response types | `hostelcare-frontend/src/types.ts` |
| How a screen uses them | `hostelcare-frontend/src/features/<name>/` |
| Permission and validation on the server | `hostelcare-backend/src/modules/<name>/*.routes.ts` and `*.schemas.ts` |

`test/web_parity_test.dart` in the mobile repo lists every web call that mobile doesn't have
yet, tagged by phase.

## Enterprise modules

Each base path answers `403 FEATURE_OFF` unless `features` lists its key.

| Base path | Feature key | What it is |
|---|---|---|
| `/api/inbox` | `inbox` | Notification inbox and bell |
| `/api/attachments` | `attachments` | Files on requests and records |
| `/api/reports` | `reports` | Reports on screen and as downloads |
| `/api/departments` | `employeeRecords` | Departments and employee records |
| `/api/leave` | `leavePolicy` | Leave: applying, approvals, balances, calendar |
| `/api/roster` | `shiftRoster` | Shift roster |
| `/api/discipline` | `discipline` | Discipline records |
| `/api/feedback` | `feedback` | Monthly feedback |
| `/api/parcels` | `parcels` | Parcels at the desk |
| `/api/emergency-contacts` | `emergencyContacts` | An employee's emergency contacts |
| `/api/lost-found` | `lostFound` | Lost and found |
| `/api/cleaning` | `cleaning` | Housekeeping tasks and checks |
| `/api/inventory`, `/api/vendors`, `/api/asset-tags` | `roomInventory` | Room inventory and work orders |
| `/api/laundry` | `laundry` | Laundry orders |
| `/api/compliance` | `compliance` | Statutory compliance items and actions |
| `/api/staff-attendance` | `staffAttendance` | Staff punches, duties, board |
| `/api/energy` | `energy` | Meter readings and alerts |
| `/api/outings` | `quickOutings` | Outing requests, approvals, curfew |
| `/api/broadcasts` | `noticeTargeting` | Targeted notices |
| `/api/transport` | `busLog` | Buses and trips |
| `/api/events` | `events` | Events and attendance |
| `/api/emergency` | `emergency` | Raising an emergency, headcount, all-clear |
| `/api/canteen` | `canteen` | Canteen meals, diet menus, ratings |
| `/api/medical` | `medical` | Health records, sealed at rest, reads logged |
| `/api/special-needs` | `specialNeeds` | Special needs and assistance |
| `/api/leadership` | `leadership` | Leadership overview |
| `/api/integrations` | `hrFeeds` | HR feeds from other systems, for machines, not the app |

## Roles and what they land on

| Who | On the app |
|---|---|
| Employee | Home, requests, mess, leave and the rest behind a More tab |
| Guard | Scan and gate tabs, raising an emergency |
| Housekeeping, electricians and other field staff | My tasks, attendance, compliance actions |
| Plant approvers | Leave approvals |
| Hostel admin and wardens | The staff shell, with money hidden |
| Medical, leadership and other desk staff | Phase 3. Until then they land on Settings, and their screens are on the web |

## Test logins

From the seed, all at `@demo.example`, using the password given to `DEMO_PASSWORD`:
`employee1`, `admin`, `security.a`, `housekeeper1`, `electrician`, `plant.assembly`,
`housekeeping`, `ohc`, `leadership`, `ehs`. The seed prints the full list.

To check that hostels are untouched, test the same screens with a hostel login on a separate
test database. The seed creates only the Enterprise tenant.

## Scripts worth knowing

| Command | What it proves |
|---|---|
| `npm run test:no-leak` | Every Enterprise route stays off for hostels, PGs and dormitories |
| `node scripts/compare-shapes.mjs before.json after.json` | Nothing a live client reads has changed between two builds |
| `flutter test test/web_parity_test.dart` | Every web call is either on mobile or tagged by phase |
