---
date: 2026-10-18
repo: D:\main\VBMS
target: backend/src (Express 5 + mysql2)
evidence-basis: static code analysis (no server executed)
---

# Backend API Endpoint Inventory (QA Discovery)

All paths, methods, middleware chains, permissions and table references below were read directly
from source (`app.js`, `src/routes/*.js`, `src/middleware/*.js`, `src/cron/*.js`). Line numbers
are cited so every row can be re-verified. Where a handler's purpose came from its source comment,
the comment content is paraphrased only.

---

## Section 1 — Mount Table (app.js)

| Mount (prefix) | Router file | Route file lines | app.js line |
|---|---|---|---|
| `/api/auth` | routes/authRoutes.js | 8 endpoints | app.js:107 |
| `/api/preferences` | routes/preferenceRoutes.js | 2 | app.js:108 |
| `/api/integrations` | routes/integrationRoutes.js | 2 | app.js:109 |
| `/api/companies` | routes/companyRoutes.js | 5 | app.js:110 |
| `/api/states` | routes/stateRoutes.js | 5 | app.js:111 |
| `/api/locations` | routes/locationRoutes.js | 5 | app.js:112 |
| `/api/customers` | routes/customerRoutes.js | 24 | app.js:113 |
| `/api/service-types` | routes/serviceTypeRoutes.js | 5 | app.js:114 |
| `/api/materials` | routes/materialRoutes.js | 10 | app.js:115 |
| `/api/material-types` | routes/materialTypeRoutes.js | 3 | app.js:116 |
| `/api/members` | routes/memberRoutes.js | 21 | app.js:117 |
| `/api/holidays` | routes/holidayRoutes.js | 20 | app.js:118 |
| `/api/jobs` | routes/jobRoutes.js | 35 | app.js:119 |
| `/api/attendance` | routes/attendanceRoutes.js | 15 | app.js:120 |
| `/api/reviews` | routes/reviewRoutes.js | 13 | app.js:121 |
| `/api/mis` | routes/misRoutes.js | 5 | app.js:122 |
| `/api/notifications` | routes/notificationRoutes.js | 6 | app.js:123 |
| `/api/audit` | routes/auditRoutes.js | 2 | app.js:124 |
| `/api/users` | routes/userMgmtRoutes.js | 20 | app.js:125 |
| `/api/settings` | routes/settingsRoutes.js | 2 | app.js:126 |
| `/api/profile` | routes/profileRoutes.js | 10 | app.js:127 |
| `/api/search` | routes/searchRoutes.js | 1 | app.js:128 |
| `/api/dashboard` | routes/dashboardRoutes.js | 1 | app.js:129 |
| `/api/mail-formats` | routes/mailFormatRoutes.js | 5 | app.js:130 |
| `/api/feedback` | routes/feedbackRoutes.js | 18 | app.js:131 |
| **(NOT MOUNTED)** | routes/assetRoutes.js | 4 | **no import, no `app.use` — see GLOB/ASSET** |

- 25 routers mounted, 26 route files present. **`assetRoutes.js` is orphaned** (no reference to
  it anywhere in `backend/src`; verified by search for `assetRoutes`).
- No `router.use(...)` / `router.all(...)` calls exist anywhere in `src/routes` (verified) —
  every route carries its middleware inline on the definition line.
- Mounted API route handlers: **243**. Orphaned (unmounted): 4. App-level routes: 5.
  Total defined HTTP routes: **252** (248 actually reachable).

---

## Section 2 — Global / Non-Route Endpoints (app.js)

| ID | Method | Path | Auth | Purpose | Location |
|---|---|---|---|---|---|
| GLB-01 | GET | `/api/health` | Public | Liveness JSON `{status:"ok"}` | app.js:103 |
| GLB-02 | GET | `/api/downloads`, `/api/downloads/vbms.apk`, `/downloads`, `/downloads/vbms.apk` | Public | Branded APK download HTML page (`renderApkDownloadPage`) | app.js:94-99 |
| GLB-03 | GET | `/uploads/*` | **Public static** | Serves `backend/uploads/**` (photos, docs, police docs) | app.js:67 |
| GLB-04 | GET | `/api/uploads/*` | **Public static** | Same folder under `/api` for reverse-proxy hosts | app.js:73 |
| GLB-05 | GET | `/api/downloads/file/vbms.apk` | Public static | Raw APK bytes (Content-Disposition attachment) | app.js:78-100 |
| GLB-06 | GET | `/downloads/file/*` | Public static | Same, bare path | app.js:101 |
| GLB-07 | ANY | everything else | — | JSON 404 handler `{message:'Route not found'}` | app.js:147 |
| GLB-08 | ANY | error flow | — | Central error handler (Multer→413/400 mapping, `entity.too.large`→413, `entity.parse.failed`→400, DB `code` surfaced) | app.js:160-197 |
| GLB-09 | GET/HEAD | non-`/api` paths (prod only) | — | SPA fallback: serves `frontend/dist/index.html` when built SPA exists | app.js:135-144 |

Global middleware: `corsMiddleware` (app.js:37) → `express.json()` (app.js:38) → response
`/uploads/`→`/api/uploads/` URL rewriter around `res.json` (app.js:61-65) → static mounts → routes.

---

## Section 3 — Endpoint Register

Legend: **A** = auth (`reqAuth` = requireAuth, `Pub` = no auth). **P** = permission from
`requirePermission(...)`/`requireAnyPermission(...)`; `—` = none in middleware chain.
Upload = multer middleware present on the route.

### 3.1 Auth (`/api/auth`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| AUTH-01 | POST | /api/auth/login | Pub | — | Login (lockout via login_attempts/account_lockouts, issues JWT) | login_attempts, account_lockouts, users, roles, role_permissions, permissions, employee_scopes | — |
| AUTH-02 | GET | /api/auth/check-username/:username | Pub | — | Username availability | users | — |
| AUTH-03 | GET | /api/auth/me | reqAuth | — | Current session user + permissions/scopes | (session only) | — |
| AUTH-04 | POST | /api/auth/logout | reqAuth | — | Logout | — | — |
| AUTH-05 | POST | /api/auth/forgot-password | Pub | — | Password reset email (uniform response, anti-enumeration) | password_reset_tokens | — |
| AUTH-06 | GET | /api/auth/reset-password/:token | Pub | — | Reset-token status check | password_reset_tokens | — |
| AUTH-07 | POST | /api/auth/reset-password | Pub | — | Consume token, set new password | password_reset_tokens, users | — |
| AUTH-08 | POST | /api/auth/change-password | reqAuth | — | Change own password | users | — |

### 3.2 Preferences (`/api/preferences`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| PREF-01 | GET | /api/preferences | reqAuth | — | Get own preferences | user_preferences | — |
| PREF-02 | PUT | /api/preferences | reqAuth | — | Upsert own preferences | user_preferences | — |

### 3.3 Integrations (`/api/integrations`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| INT-01 | GET | /api/integrations/email | reqAuth | settings.view | SMTP config read (password masked `********`) | .env file + config | — |
| INT-02 | POST | /api/integrations/email | reqAuth | settings.edit (+in-handler super_admin/admin, integrationRoutes.js:79) | SMTP config write — **rewrites `.env` file on disk** (integrationRoutes.js:55-58) | .env file | — |

### 3.4 Companies (`/api/companies`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| CO-01 | GET | /api/companies | reqAuth | company.view | List companies (paginated) | companies | — |
| CO-02 | GET | /api/companies/:id | reqAuth | company.view | Company detail | companies | — |
| CO-03 | POST | /api/companies | reqAuth | company.create | Create company | companies | — |
| CO-04 | PUT | /api/companies/:id | reqAuth | company.edit | Update company | companies | — |
| CO-05 | DELETE | /api/companies/:id | reqAuth | company.delete | Soft delete (status→inactive) | companies | — |

### 3.5 States (`/api/states`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| ST-01 | GET | /api/states | reqAuth | state.view | List states | states, users | — |
| ST-02 | GET | /api/states/:id | reqAuth | state.view | State detail w/ locations | states, locations, users | — |
| ST-03 | POST | /api/states | reqAuth | state.create | Create state | states, users | — |
| ST-04 | PUT | /api/states/:id | reqAuth | state.edit | Update state | states, users | — |
| ST-05 | DELETE | /api/states/:id | reqAuth | state.delete | Soft delete | states | — |

### 3.6 Locations (`/api/locations`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| LOC-01 | GET | /api/locations | reqAuth | location.view | List locations | locations, states, users | — |
| LOC-02 | GET | /api/locations/:id | reqAuth | location.view | Location detail | locations, states, users | — |
| LOC-03 | POST | /api/locations | reqAuth | location.create | Create location (auto-creates state if state_id given) | locations, states, users | — |
| LOC-04 | PUT | /api/locations/:id | reqAuth | location.edit | Update location | locations, states, users | — |
| LOC-05 | DELETE | /api/locations/:id | reqAuth | location.delete | Soft delete | locations | — |

### 3.7 Customers (`/api/customers`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| CU-01 | GET | /api/customers | reqAuth | customer.view | List customers (paginated) | customers, branches, branch_locations, location_contacts, holiday_calendars, users | — |
| CU-02 | GET | /api/customers/:id | reqAuth | customer.view | Customer detail (contacts/branches/locations/states) | customers, customer_contacts, branches, branch_locations, locations, location_contacts, states, holiday_calendars, users | — |
| CU-03 | POST | /api/customers | reqAuth | customer.create | Create customer (+ contact person user) | customers, users | — |
| CU-04 | PUT | /api/customers/:id | reqAuth | customer.edit | Update customer | customers, users | — |
| CU-05 | DELETE | /api/customers/:id | reqAuth | customer.delete | Soft delete customer | customers | — |
| CU-06 | GET | /api/customers/:customerId/contacts | reqAuth | customer.view | List customer contacts | customer_contacts | — |
| CU-07 | POST | /api/customers/:customerId/contacts | reqAuth | customer.edit | Add contact (+user account, scopes) | customer_contacts, users, employee_scopes | — |
| CU-08 | PUT | /api/customers/:customerId/contacts | reqAuth | customer.edit | Bulk replace contacts | customer_contacts, users, employee_scopes | — |
| CU-09 | PUT | /api/customers/:customerId/contacts/:contactId | reqAuth | customer.edit | Update contact | customer_contacts, users, employee_scopes | — |
| CU-10 | DELETE | /api/customers/:customerId/contacts/:contactId | reqAuth | customer.edit | Delete contact | customer_contacts, users | — |
| CU-11 | GET | /api/customers/branches/all | reqAuth | customer.view | All branches across customers (Access Control UI) | branches, customers | — |
| CU-12 | GET | /api/customers/:customerId/branches | reqAuth | customer.view | List customer branches | branches | — |
| CU-13 | POST | /api/customers/:customerId/branches | reqAuth | customer.edit | Create branch | branches | — |
| CU-14 | PUT | /api/customers/:customerId/branches/:branchId | reqAuth | customer.edit | Update branch | branches | — |
| CU-15 | DELETE | /api/customers/:customerId/branches/:branchId | reqAuth | customer.edit | Delete branch | branches | — |
| CU-16 | GET | /api/customers/:customerId/branches/:branchId/locations | reqAuth | customer.view | List branch locations | branch_locations, locations, states | — |
| CU-17 | POST | /api/customers/:customerId/branches/:branchId/locations | reqAuth | customer.edit | Attach location to branch | branch_locations, locations, states | — |
| CU-18 | PUT | /api/customers/:customerId/branches/:branchId/locations/:locId | reqAuth | customer.edit | Update branch-location | branch_locations, locations, states | — |
| CU-19 | DELETE | /api/customers/:customerId/branches/:branchId/locations/:locId | reqAuth | customer.edit | Remove branch-location | branch_locations | — |
| CU-20 | GET | .../locations/:locId/contacts | reqAuth | customer.view | Location contacts | location_contacts | — |
| CU-21 | POST | .../locations/:locId/contacts | reqAuth | customer.edit | Add location contact (+user, scopes) | location_contacts, users, employee_scopes | — |
| CU-22 | PUT | .../locations/:locId/contacts | reqAuth | customer.edit | Bulk replace location contacts | location_contacts, users, employee_scopes | — |
| CU-23 | PUT | .../locations/:locId/contacts/:contactId | reqAuth | customer.edit | Update location contact | location_contacts, users, employee_scopes | — |
| CU-24 | DELETE | .../locations/:locId/contacts/:contactId | reqAuth | customer.edit | Delete location contact | location_contacts, users | — |

### 3.8 Service Types (`/api/service-types`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| SV-01 | GET | /api/service-types | reqAuth | job.view | List service types | service_types, users | — |
| SV-02 | GET | /api/service-types/:id | reqAuth | job.view | Service type detail | service_types, users | — |
| SV-03 | POST | /api/service-types | reqAuth | job.create | Create service type | service_types, users | — |
| SV-04 | PUT | /api/service-types/:id | reqAuth | job.edit | Update service type | service_types, users | — |
| SV-05 | DELETE | /api/service-types/:id | reqAuth | job.edit | Soft delete | service_types | — |

### 3.9 Materials (`/api/materials`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| MT-01 | GET | /api/materials/grouped | reqAuth | job.view | Materials grouped by order_no | materials, customers, branches, companies | — |
| MT-02 | GET | /api/materials/group/:orderKey | reqAuth | job.view | Items within one order group | materials (+ joins) | — |
| MT-03 | GET | /api/materials | reqAuth | job.view | Flat material list | materials | — |
| MT-04 | GET | /api/materials/by-customer/:customerId | reqAuth | job.view | Materials by customer (customer-scope helper applied) | materials | — |
| MT-05 | GET | /api/materials/:id | reqAuth | job.view | Material detail | materials | — |
| MT-06 | POST | /api/materials | reqAuth | job.create | Create material (single or batch) | materials | — |
| MT-07 | PUT | /api/materials/:id | reqAuth | job.edit | Update material | materials | — |
| MT-08 | DELETE | /api/materials/:id | reqAuth | job.edit | Soft delete | materials | — |
| MT-09 | DELETE | /api/materials | reqAuth | job.edit | Batch soft delete (ids in body) | materials | — |
| MT-10 | POST | /api/materials/:id/document | reqAuth | job.edit | Upload material document (10 MB, ext+mimetype filter) | materials | `docUpload.single('file')` (materialRoutes.js:435) |

### 3.10 Material Types (`/api/material-types`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| MTY-01 | GET | /api/material-types | reqAuth | job.view | List active material types | material_types | — |
| MTY-02 | POST | /api/material-types | reqAuth | job.create | Create material type | material_types | — |
| MTY-03 | DELETE | /api/material-types/:id | reqAuth | job.edit | Soft delete | material_types | — |

### 3.11 Members (`/api/members`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| MB-01 | GET | /api/members/all-documents | reqAuth | employee.view | All member documents (cross-member) | field_members, member_documents | — |
| MB-02 | GET | /api/members/all-member-locations | reqAuth | employee.view | All member locations (cross-member) | field_members, member_locations, locations | — |
| MB-03 | POST | /api/members/:memberId/police-doc | reqAuth | employee.edit | Upload police verification doc (5 MB) | member_police_docs | `upload.single('file')` (memberRoutes.js:85) |
| MB-04 | GET | /api/members/:memberId/police-docs | reqAuth | employee.view | List police docs | member_police_docs | — |
| MB-05 | DELETE | /api/members/:memberId/police-docs/:docId | reqAuth | employee.edit | Delete police doc (file removed from disk) | member_police_docs | — |
| MB-06 | GET | /api/members | reqAuth | employee.view | List field members | field_members, member_locations, branches, branch_locations, states, users | — |
| MB-07 | GET | /api/members/:id | reqAuth | employee.view | Member detail (locations, skills, docs, police docs) | field_members, member_locations, member_skills, member_documents, member_police_docs, service_types, locations, branches, states, users | — |
| MB-08 | POST | /api/members | reqAuth | employee.create | Create member (+user account) | field_members, users | — |
| MB-09 | PUT | /api/members/:id | reqAuth | employee.edit | Update member | field_members, users | — |
| MB-10 | DELETE | /api/members/:id | reqAuth | employee.edit | Soft delete (refused while serving jobs) | field_members, job_assignments, jobs | — |
| MB-11 | GET | /api/members/:memberId/locations | reqAuth | employee.view | Member locations | member_locations, locations | — |
| MB-12 | POST | /api/members/:memberId/locations | reqAuth | employee.edit | Assign member location | member_locations | — |
| MB-13 | DELETE | /api/members/:memberId/locations/:locationId | reqAuth | employee.edit | Unassign member location | member_locations | — |
| MB-14 | GET | /api/members/:memberId/skills | reqAuth | employee.view | Member skills | member_skills, service_types | — |
| MB-15 | POST | /api/members/:memberId/skills | reqAuth | employee.edit | Add skill | member_skills | — |
| MB-16 | DELETE | /api/members/:memberId/skills/:serviceTypeId | reqAuth | employee.edit | Remove skill | member_skills | — |
| MB-17 | GET | /api/members/:memberId/documents | reqAuth | employee.view | List member documents | member_documents | — |
| MB-18 | POST | /api/members/:memberId/documents | reqAuth | employee.edit | Upload member document (10 MB) | member_documents | `docsUpload.single('file')` (memberRoutes.js:590) |
| MB-19 | PUT | /api/members/:memberId/documents/:docId | reqAuth | employee.edit | Replace member document | member_documents | `docsUpload.single('file')` (memberRoutes.js:629) |
| MB-20 | DELETE | /api/members/:memberId/documents/:docId | reqAuth | employee.edit | Delete member document | member_documents | — |
| MB-21 | POST | /api/members/:memberId/photo | reqAuth | employee.edit | Upload member photo (5 MB) | field_members, users | `photoUpload.single('file')` (memberRoutes.js:712) |

### 3.12 Holidays (`/api/holidays`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| HD-01 | GET | /api/holidays | reqAuth | holiday.view | List calendars (with scoped customers/locations/states) | holiday_calendars, holidays, customers, locations, states | — |
| HD-02 | POST | /api/holidays | reqAuth | holiday.create | Create calendar | holiday_calendars | — |
| HD-03 | POST | /api/holidays/bulk | reqAuth | holiday.create | Page-level bulk add (dates/range + scope; 409 if year calendar missing) | holiday_calendars, holidays, customers | — |
| HD-04 | GET | /api/holidays/overrides | reqAuth | holiday.override | List working-day overrides | working_day_overrides, customers, locations, states, companies, users | — |
| HD-05 | POST | /api/holidays/overrides | reqAuth | holiday.override | Create override | working_day_overrides | — |
| HD-06 | PUT | /api/holidays/overrides/:id | reqAuth | holiday.override | Update override | working_day_overrides | — |
| HD-07 | DELETE | /api/holidays/overrides/:id | reqAuth | holiday.override | Delete override | working_day_overrides | — |
| HD-08 | POST | /api/holidays/resolve | reqAuth | **— (auth only, documented)** | Is a date a working day (delegates to workingDayService) | (via service) | — |
| HD-09 | GET | /api/holidays/availability | reqAuth | **— (auth only, documented)** | Working status for a date range (job forms) | holiday_calendars, holidays, overrides (via service) | — |
| HD-10 | GET | /api/holidays/:id | reqAuth | holiday.view | Calendar with holidays | holiday_calendars, holidays, customers, locations, states | — |
| HD-11 | PUT | /api/holidays/:id | reqAuth | holiday.edit | Update calendar | holiday_calendars | — |
| HD-12 | DELETE | /api/holidays/:id | reqAuth | holiday.delete | Delete calendar | holiday_calendars, holidays | — |
| HD-13 | POST | /api/holidays/:calendarId/holidays | reqAuth | holiday.create | Add holiday | holidays | — |
| HD-14 | POST | /api/holidays/:calendarId/holidays/bulk | reqAuth | holiday.create | Bulk add holidays | holidays | — |
| HD-15 | PUT | /api/holidays/:calendarId/holidays/:holidayId | reqAuth | holiday.edit | Update holiday | holidays | — |
| HD-16 | DELETE | /api/holidays/:calendarId/holidays/:holidayId | reqAuth | holiday.delete | Delete holiday | holidays | — |
| HD-17 | GET | /api/holidays/:calendarId/rules | reqAuth | holiday.view | List rules | holiday_rules | — |
| HD-18 | POST | /api/holidays/:calendarId/rules | reqAuth | holiday.create | Create rule | holiday_rules | — |
| HD-19 | PUT | /api/holidays/:calendarId/rules/:ruleId | reqAuth | holiday.edit | Update rule | holiday_rules | — |
| HD-20 | DELETE | /api/holidays/:calendarId/rules/:ruleId | reqAuth | holiday.delete | Delete rule | holiday_rules | — |

### 3.13 Jobs (`/api/jobs`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| JOB-01 | POST | /api/jobs/:id/daily-tasks/:taskId/photo | reqAuth | any(job.edit, attendance.edit) | Append one photo to a ticket (offline/legacy) | job_daily_tasks (photo arrays) | `taskPhotoUpload` (jobRoutes.js:408) |
| JOB-02 | POST | /api/jobs/:id/daily-tasks/:taskId/photos | reqAuth | any(job.edit, attendance.edit) | Append up to 20 photos to a ticket | job_daily_tasks | `taskPhotosUpload` (jobRoutes.js:420) |
| JOB-03 | GET | /api/jobs/sidebar-stats | reqAuth | job.view | Lightweight sidebar stats | jobs, job_daily_tasks | — |
| JOB-04 | GET | /api/jobs/daily-tasks | reqAuth | job.view | All tickets across jobs (filters, scope) | job_daily_tasks, jobs, customers, branches, locations, field_members, service_types | — |
| JOB-05 | GET | /api/jobs | reqAuth | job.view | List jobs (filters, pagination, scope) | jobs, customers, branches, locations, states, service_types, job_assignments, field_members | — |
| JOB-06 | GET | /api/jobs/members-by-location | reqAuth | any(job.view, job.edit) | Members eligible for a branch (strict branch_id mode) | field_members, member_locations, branch_locations, locations, job_assignments | — |
| JOB-07 | GET | /api/jobs/check-leave | reqAuth | job.view | Is member on leave for a date | leave_requests | — |
| JOB-08 | GET | /api/jobs/by-member/:memberId | reqAuth | job.view | Jobs assigned to member | jobs, job_assignments, customers, branches, service_types | — |
| JOB-09 | GET | /api/jobs/branch-locations | reqAuth | job.view | Branch locations for job form | branch_locations, locations, states | — |
| JOB-10 | GET | /api/jobs/:id | reqAuth | job.view | Full job detail (all related) | jobs, customers, branches, locations, states, service_types, job_assignments, field_members, job_checkins, job_checkouts, job_tracking, job_photos, job_checklists, job_feedback, job_reviews, job_daily_tasks, customer_contacts, users | — |
| JOB-11 | POST | /api/jobs | reqAuth | job.create | Create job (assignment + daily-task seeding) | jobs, job_assignments, job_daily_tasks, branch_locations, locations | — |
| JOB-12 | PUT | /api/jobs/:id | reqAuth | job.edit | Update job (cascades assignment/ticket edits) | jobs, job_assignments, job_daily_tasks, job_checkins, job_checkouts, job_tracking, job_photos, job_checklists, job_feedback, job_reviews, branch_locations, locations | — |
| JOB-13 | DELETE | /api/jobs/:id | reqAuth | job.cancel | Soft delete / cancel job (+notifications) | jobs, job_assignments, job_daily_tasks, job_checkins, job_checkouts, job_tracking, job_photos, job_checklists, job_feedback, job_reviews, job_reassignments, notifications | — |
| JOB-14 | POST | /api/jobs/:id/assign | reqAuth | job.edit | Assign member(s) (single/array) (+notification) | job_assignments, field_members, notifications | — |
| JOB-15 | POST | /api/jobs/:id/reassign | reqAuth | job.edit | Reassign member | job_assignments, job_reassignments | — |
| JOB-16 | POST | /api/jobs/:id/tracking | reqAuth | job.edit | Add tracking event | job_tracking | — |
| JOB-17 | POST | /api/jobs/:id/tracking/ping | reqAuth | any(job.edit, attendance.edit) | Mobile GPS ping; server recomputes geofence, derives transition | job_location_pings, job_checkins, job_daily_tasks | — |
| JOB-18 | GET | /api/jobs/:id/location-pings | reqAuth | job.view | Location trail for tracking map (≤2000 pts) | job_location_pings, jobs, field_members | — |
| JOB-19 | POST | /api/jobs/:id/checkin | reqAuth | job.edit | Job check-in | job_checkins, job_tracking, jobs | — |
| JOB-20 | POST | /api/jobs/:id/checkout | reqAuth | job.edit | Job check-out | job_checkouts, jobs | — |
| JOB-21 | POST | /api/jobs/:id/photos | reqAuth | job.edit | Add job photo record | job_photos | — |
| JOB-22 | POST | /api/jobs/:id/checklists | reqAuth | job.edit | Add checklist item | job_checklists | — |
| JOB-23 | PUT | /api/jobs/:id/checklists/:checklistId | reqAuth | job.edit | Update checklist item | job_checklists | — |
| JOB-24 | POST | /api/jobs/:id/submit | reqAuth | job.edit | Submit job for review (+notifications) | jobs, notifications, users | — |
| JOB-25 | POST | /api/jobs/auto-assign | reqAuth | job.edit | Auto-assign members (capacity/skills/leave/location) | jobs, job_assignments, field_members, employee_capacity, attendance, leave_requests, member_skills, member_locations | — |
| JOB-26 | GET | /api/jobs/:id/daily-tasks | reqAuth | job.view | Tickets for a job | job_daily_tasks, field_members | — |
| JOB-27 | POST | /api/jobs/:id/generate-daily-tasks | reqAuth | job.edit | Generate tickets over date range (skips holidays) | job_daily_tasks, jobs, job_assignments | — |
| JOB-28 | POST | /api/jobs/:id/daily-tasks/manual | reqAuth | job.edit | Create single manual ticket | job_daily_tasks, jobs | — |
| JOB-29 | PUT | /api/jobs/:id/daily-tasks/:taskId | reqAuth | job.edit | Update ticket (check-in/out, photos, status, reviewer) | job_daily_tasks, job_assignments, jobs | — |
| JOB-30 | DELETE | /api/jobs/:id/daily-tasks/:taskId | reqAuth | job.cancel | Delete ticket | job_daily_tasks, app_settings | — |
| JOB-31 | POST | /api/jobs/:id/daily-tasks/:taskId/checkin | reqAuth | any(job.edit, attendance.edit) | Ticket check-in with **server-side geofence rejection** | job_daily_tasks, job_checkins | — |
| JOB-32 | POST | /api/jobs/:id/daily-tasks/:taskId/checkout | reqAuth | any(job.edit, attendance.edit) | Ticket check-out (hours, remarks) | job_daily_tasks, job_checkouts | — |
| JOB-33 | POST | /api/jobs/ticket/:ticketId/redo | reqAuth | **in-handler `role === 'super_admin'` (jobRoutes.js:2160)** | Redo escalation: freeze ticket + spawn replacement, or return completed→VBMS review | job_daily_tasks, ticket_redo_history, field_members | — |
| JOB-34 | GET | /api/jobs/ticket/:ticketId/redo-history | reqAuth | job.view | Redo history for one ticket | ticket_redo_history, job_daily_tasks, field_members, users | — |
| JOB-35 | GET | /api/jobs/:jobId/redo-history | reqAuth | job.view | Redo history for a job | ticket_redo_history, job_daily_tasks, field_members, users | — |

### 3.14 Attendance (`/api/attendance`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| ATT-01 | GET | /api/attendance | reqAuth | attendance.view | List attendance (scope-filtered) | attendance, customers, field_members, users | — |
| ATT-02 | POST | /api/attendance/checkin | reqAuth | attendance.edit | Check-in (self defaults from token; lat/lng) | attendance | — |
| ATT-03 | POST | /api/attendance/checkout | reqAuth | attendance.edit | Check-out (same self defaults) | attendance | — |
| ATT-04 | PUT | /api/attendance/:id | reqAuth | attendance.edit | Update attendance record | attendance | — |
| ATT-05 | GET | /api/attendance/daily-summary | reqAuth | attendance.view | Daily summary | attendance, jobs, app_settings | — |
| ATT-06 | GET | /api/attendance/leaves | reqAuth | attendance.view | List leave requests | leave_requests, field_members, users | — |
| ATT-07 | POST | /api/attendance/leaves | reqAuth | attendance.edit | Apply for leave | leave_requests, field_members | — |
| ATT-08 | PUT | /api/attendance/leaves/:id | reqAuth | attendance.edit | Approve/reject/edit leave | leave_requests, attendance, field_members | — |
| ATT-09 | GET | /api/attendance/capacity | reqAuth | attendance.view | Member capacity for a date | employee_capacity, field_members, customers, locations | — |
| ATT-10 | POST | /api/attendance/capacity | reqAuth | attendance.edit | Set capacity | employee_capacity, jobs, job_daily_tasks, service_types | — |
| ATT-11 | GET | /api/attendance/daily-attendance | reqAuth | attendance.view | Task-based attendance view | job_daily_tasks, field_members | — |
| ATT-12 | POST | /api/attendance/refresh-attendance | reqAuth | attendance.edit | Recalculate attendance for a date | attendance, job_daily_tasks, field_members | — |
| ATT-13 | GET | /api/attendance/capacity-summary | reqAuth | attendance.view | Capacity by customer & service type | job_daily_tasks, jobs, customers, service_types, field_members | — |
| ATT-14 | GET | /api/attendance/cron-status | reqAuth | attendance.view | Cron status | attendance_config | — |
| ATT-15 | PUT | /api/attendance/cron-schedule | reqAuth | attendance.edit | Update cron schedule | attendance_config | — **UNREACHABLE, see R-01** |

### 3.15 Reviews (`/api/reviews`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| RV-01 | GET | /api/reviews/pending | reqAuth | any(review.vbms, review.cub) | Pending ticket queues | job_daily_tasks, jobs, job_reviews, customers, branches, service_types, field_members | — |
| RV-02 | GET | /api/reviews/job/:jobId | reqAuth | any(review.vbms, review.cub) | Job detail for review | jobs + related (as JOB-10) | — |
| RV-03 | GET | /api/reviews/ticket/:ticketId | reqAuth | any(review.vbms, review.cub) | Ticket detail + photos + review history | job_daily_tasks, job_reviews, job_feedback, jobs, customers, field_members | — |
| RV-04 | POST | /api/reviews/vbms/ticket/:ticketId/approve | reqAuth | review.vbms | VBMS sign-off of one ticket | job_daily_tasks, job_reviews, jobs, notifications, users | — |
| RV-05 | POST | /api/reviews/vbms/ticket/:ticketId/rework | reqAuth | review.vbms | VBMS rework: freeze + replacement ticket | job_daily_tasks, job_reviews, job_assignments, ticket_redo_history, notifications | — |
| RV-06 | POST | /api/reviews/cub/ticket/:ticketId/approve | reqAuth | review.cub | CUB final sign-off | job_daily_tasks, job_reviews, jobs, notifications, users | — |
| RV-07 | POST | /api/reviews/cub/ticket/:ticketId/comment | reqAuth | review.cub | Neutral comment (no status change) | job_daily_tasks, job_reviews, notifications, users | — |
| RV-08 | POST | /api/reviews/cub/ticket/:ticketId/feedback | reqAuth | review.cub | Feedback on ticket | job_feedback, job_reviews, job_daily_tasks | — |
| RV-09 | POST | /api/reviews/vbms/:jobId/approve | reqAuth | review.vbms | Job-level approve (legacy) | job_reviews, jobs, job_daily_tasks, notifications | — |
| RV-10 | POST | /api/reviews/vbms/:jobId/rework | reqAuth | review.vbms | Job-level rework (legacy) | job_reviews, jobs, job_daily_tasks, job_assignments, notifications | — |
| RV-11 | POST | /api/reviews/cub/:jobId/approve | reqAuth | review.cub | Job-level approve (legacy) | job_reviews, jobs, job_daily_tasks, notifications | — |
| RV-12 | POST | /api/reviews/cub/:jobId/feedback | reqAuth | review.cub | Job-level feedback (legacy) | job_feedback, job_reviews, jobs, job_daily_tasks | — |
| RV-13 | GET | /api/reviews/history/:jobId | reqAuth | any(review.vbms, review.cub) | Review history for a job | job_reviews, job_feedback, users | — |

### 3.16 MIS (`/api/mis`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| MIS-01 | GET | /api/mis/monthly | reqAuth | mis.view | Monthly MIS summary | salary_inputs, field_members | — |
| MIS-02 | POST | /api/mis/generate | reqAuth | mis.export | Generate monthly MIS aggregates | salary_inputs, attendance, field_members, jobs, job_assignments | — |
| MIS-03 | GET | /api/mis/salary | reqAuth | mis.view | Salary inputs | salary_inputs, field_members | — |
| MIS-04 | PUT | /api/mis/salary/:id | reqAuth | mis.export | Update salary input status | salary_inputs | — |
| MIS-05 | GET | /api/mis/members/:memberId/reviews | reqAuth | mis.view | Member feedback/reviews | feedback_requests, feedback_responses, field_members, jobs, customers, branches | — |

### 3.17 Notifications (`/api/notifications`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| NT-01 | GET | /api/notifications | reqAuth | notification.view | List own notifications | notifications, jobs | — |
| NT-02 | PUT | /api/notifications/:id/read | reqAuth | notification.manage | Mark read | notifications | — |
| NT-03 | PUT | /api/notifications/:id/unread | reqAuth | notification.manage | Mark unread | notifications | — |
| NT-04 | PUT | /api/notifications/read-all | reqAuth | notification.manage | Mark all read | notifications | — |
| NT-05 | GET | /api/notifications/unread-count | reqAuth | notification.view | Unread count | notifications | — |
| NT-06 | DELETE | /api/notifications/:id | reqAuth | notification.manage | Delete notification | notifications | — |

### 3.18 Audit (`/api/audit`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| AU-01 | GET | /api/audit | reqAuth | audit.view | List audit logs (paginated) | audit_logs, users | — |
| AU-02 | GET | /api/audit/:id | reqAuth | audit.view | Audit log detail | audit_logs, users | — |

### 3.19 Users (`/api/users`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| US-01 | GET | /api/users | reqAuth | user.view | List users (field_members, system roles, contact persons) | users, field_members, customer_contacts, location_contacts | — |
| US-02 | GET | /api/users/login-sessions | reqAuth | user.view | Admin view of all login sessions | user_sessions, user_devices, users | — |
| US-03 | DELETE | /api/users/login-sessions/:id | reqAuth | user.edit | Revoke a session | user_sessions | — |
| US-04 | GET | /api/users/:id | reqAuth | user.view | User detail (+scopes) | users, employee_scopes, customers, locations, states | — |
| US-05 | POST | /api/users | reqAuth | user.create | Create user | users | — |
| US-06 | PUT | /api/users/:id | reqAuth | user.edit | Update user | users, field_members | — |
| US-07 | DELETE | /api/users/:id | reqAuth | user.edit | Soft delete user | users | — |
| US-08 | GET | /api/users/scopes/all | reqAuth | user.view | All scopes (global) | employee_scopes, customers, branches, locations, states, users | — |
| US-09 | GET | /api/users/:userId/scopes | reqAuth | user.view | Scopes for a user | employee_scopes, customers, branches, locations, states | — |
| US-10 | POST | /api/users/scopes | reqAuth | user.edit | Add scope | employee_scopes | — |
| US-11 | PUT | /api/users/scopes/:scopeId | reqAuth | user.edit | Update scope | employee_scopes | — |
| US-12 | DELETE | /api/users/scopes/:scopeId | reqAuth | user.edit | Delete scope | employee_scopes, users | — |
| US-13 | GET | /api/users/roles/all | reqAuth | user.view | Roles with user counts | roles, role_permissions, users | — |
| US-14 | GET | /api/users/roles/:id | reqAuth | user.view | Role with users and permissions | roles, role_permissions, permissions, users | — |
| US-15 | POST | /api/users/roles | reqAuth | user.edit | Create custom role | roles, role_permissions | — |
| US-16 | PUT | /api/users/roles/:id | reqAuth | user.edit | Update role description/child_permissions | roles | — |
| US-17 | DELETE | /api/users/roles/:id | reqAuth | user.edit | Delete role | roles, role_permissions, users | — |
| US-18 | GET | /api/users/permissions/all | reqAuth | user.view | All available permissions | permissions | — |
| US-19 | GET | /api/users/roles/:id/permissions | reqAuth | user.view | Role permissions | permissions, role_permissions | — |
| US-20 | PUT | /api/users/roles/:id/permissions | reqAuth | user.edit | Replace role permissions (atomic) | role_permissions, permissions, roles | — |

### 3.20 Settings (`/api/settings`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| SET-01 | GET | /api/settings | reqAuth | settings.view | Get all settings | app_settings | — |
| SET-02 | PUT | /api/settings | reqAuth | settings.edit | Bulk upsert settings | app_settings | — |

### 3.21 Profile (`/api/profile`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| PF-01 | GET | /api/profile | reqAuth | — | Full own profile | users, field_members, employee_scopes, permissions, role_permissions, user_sessions, user_devices, login_attempts | — |
| PF-02 | PUT | /api/profile | reqAuth | — | Update own profile info | users, field_members | — |
| PF-03 | POST | /api/profile/photo | reqAuth | — | Upload own profile photo (5 MB) | users, field_members | `photoUpload.single('file')` (profileRoutes.js:286) |
| PF-04 | GET | /api/profile/sessions | reqAuth | — | Own sessions | user_sessions | — |
| PF-05 | DELETE | /api/profile/sessions/:id | reqAuth | — | Revoke one session | user_sessions | — |
| PF-06 | DELETE | /api/profile/sessions | reqAuth | — | Revoke all other sessions | user_sessions | — |
| PF-07 | GET | /api/profile/devices | reqAuth | — | Own devices | user_devices | — |
| PF-08 | GET | /api/profile/activity | reqAuth | — | Own activity log | audit_logs | — |
| PF-09 | POST | /api/profile/record-session | reqAuth | — | Record current session | user_sessions | — |
| PF-10 | DELETE | /api/profile/devices/:id | reqAuth | — | Remove a device | user_devices | — |

### 3.22 Search / Dashboard

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| SRCH-01 | GET | /api/search?q= | reqAuth | **— (no permission gate)** | Global search (locations, customers, members, jobs, services, materials) | locations, customers, field_members, jobs, service_types, materials, states | — |
| DASH-01 | GET | /api/dashboard/stats | reqAuth | **— (no permission gate)** | All dashboard metrics in one call (manual customer-scope mirroring) | jobs, job_daily_tasks, attendance, field_members, customers, locations, service_types, leave_requests, job_reviews, job_feedback, job_reassignments, ticket_redo_history, notifications, audit_logs, job_assignments, users | — |

### 3.23 Mail Formats (`/api/mail-formats`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| MF-01 | GET | /api/mail-formats | reqAuth | settings.view | List mail formats | mail_formats, users | — |
| MF-02 | GET | /api/mail-formats/:id | reqAuth | settings.view | Mail format detail | mail_formats, users | — |
| MF-03 | POST | /api/mail-formats | reqAuth | settings.edit | Create mail format | mail_formats, users | — |
| MF-04 | PUT | /api/mail-formats/:id | reqAuth | settings.edit | Update mail format | mail_formats, users | — |
| MF-05 | DELETE | /api/mail-formats/:id | reqAuth | settings.edit | Soft delete | mail_formats | — |

### 3.24 Feedback (`/api/feedback`)

| ID | Method | Path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| FB-01 | GET | /api/feedback/templates | reqAuth | feedback.view | List templates | feedback_templates | — |
| FB-02 | GET | /api/feedback/templates/active | **Pub** | **—** | Active templates (unauthenticated) | feedback_templates | — |
| FB-03 | GET | /api/feedback/templates/:id | reqAuth | feedback.view | Template detail | feedback_templates | — |
| FB-04 | POST | /api/feedback/templates | reqAuth | feedback.create | Create template | feedback_templates | — |
| FB-05 | PUT | /api/feedback/templates/:id | reqAuth | feedback.edit | Update template | feedback_templates | — |
| FB-06 | DELETE | /api/feedback/templates/:id | reqAuth | feedback.delete | Deactivate template | feedback_templates | — |
| FB-07 | GET | /api/feedback/templates/:id/requests | reqAuth | feedback.view | Requests for a template | feedback_requests, feedback_recipients | — |
| FB-08 | GET | /api/feedback/requests | reqAuth | feedback.view_responses | List feedback requests | feedback_requests, feedback_recipients, feedback_responses | — |
| FB-09 | GET | /api/feedback/requests/customer/:customerId | reqAuth | feedback.view_responses | Requests by customer | feedback_requests, feedback_recipients | — |
| FB-10 | GET | /api/feedback/requests/job/:jobId | reqAuth | feedback.view_responses | Requests by job | feedback_requests, feedback_recipients | — |
| FB-11 | POST | /api/feedback/requests | reqAuth | feedback.send | Send feedback request (tokens + email) | feedback_requests, feedback_recipients, feedback_templates, customers | — |
| FB-12 | DELETE | /api/feedback/requests/:id | reqAuth | feedback.delete | Delete request (cascades recipients/responses) | feedback_requests, feedback_recipients, feedback_responses | — |
| FB-13 | PUT | /api/feedback/recipients/:id/reactivate | reqAuth | feedback.edit | Reactivate used link token | feedback_recipients | — |
| FB-14 | GET | /api/feedback/public/:token | **Pub** | — | Public feedback form by secure token | feedback_requests, feedback_recipients, feedback_templates | — |
| FB-15 | POST | /api/feedback/public/:token/submit | **Pub** | — | Public form submission | feedback_responses, feedback_recipients, feedback_requests | — |
| FB-16 | GET | /api/feedback/responses/:requestId | reqAuth | feedback.view_responses | Responses for a request | feedback_responses, feedback_recipients | — |
| FB-17 | GET | /api/feedback/responses/:requestId/all | reqAuth | feedback.view_responses | All responses incl. per-recipient | feedback_responses, feedback_recipients | — |
| FB-18 | GET | /api/feedback/responses | reqAuth | feedback.view_responses | All responses (flat) | feedback_responses, feedback_requests, feedback_templates, customers | — |

### 3.25 Orphaned / Unmounted (`assetRoutes.js` — NOT reachable)

| ID | Method | Intended path | A | P | Purpose | Tables | Upload |
|---|---|---|---|---|---|---|---|
| ASSET-01 | GET | (none) | reqAuth | **—** | List assets | assets, customers, branches, users | — |
| ASSET-02 | POST | (none) | reqAuth | **—** | Create asset | assets, users | — |
| ASSET-03 | PUT | (none) | reqAuth | **—** | Update asset | assets, users | — |
| ASSET-04 | DELETE | (none) | reqAuth | **—** | Soft delete asset | assets | — |

---

## Section 4 — Per-Endpoint Detail (grouped by module)

Only non-obvious parameters/behaviour are repeated here; the register (Section 3) carries the
full method/path/permission/table matrix. Line numbers point at the `router.<method>` statement.

### Auth
- AUTH-01 `authRoutes.js:46` — body `{username|email, password}`; writes `login_attempts` on every
  try (`:95`, `:126`), locks via `account_lockouts` after repeated failures (`:101-108`), returns
  JWT + user + permissions/scopes/child_permissions.
- AUTH-02 `authRoutes.js:172` — `:username`, no auth → availability oracle (see R-06).
- AUTH-03 `authRoutes.js:189`, AUTH-04 `:194` — token-session only.
- AUTH-05 `authRoutes.js:199` — always same response body (anti-enumeration), invalidates prior
  tokens (`:219`), `crypto.randomBytes(32)` token (`:19`), 1 h expiry, SMTP send is non-blocking.
- AUTH-06 `authRoutes.js:275` — token validity probe; AUTH-07 `:309` — consumes token, writes
  `users.password` **and** `users.original_password` (`:352`); AUTH-08 `:365` — same columns for
  the signed-in user (`:402`).

### Preferences / Profile
- PREF-01/02 `preferenceRoutes.js:7/:23` — schema in `data/preferenceStore.js` (`user_preferences`).
- PF-01..PF-10 `profileRoutes.js:150/:226/:286/:318/:345/:366/:386/:404/:424/:456` — all
  auth-only; PF-09 records session rows (`user_sessions`), PF-07/10 manage `user_devices`.

### Integrations
- INT-01 `integrationRoutes.js:61` — returns SMTP host/port/user/from/resetUrl; `pass` always `********`.
- INT-02 `integrationRoutes.js:77` — second gate `['super_admin','admin']` (`:79`); writes env
  keys back to `.env`-style file with `fs.writeFileSync` (`:55-58`) and mutates live `config.smtp`.

### Companies / States / Locations / Service Types / Material Types / Mail Formats / Settings
- Pure CRUD; soft deletes flip `status`/`status='inactive'` (companyRoutes.js:92, mailFormatRoutes.js:120,
  materialTypeRoutes.js:40). All writes carry the matching `*.create/edit/delete` permission.

### Customers
- CU-01/02 `customerRoutes.js:29/:68` — nested hydration (contacts, branches, branch locations,
  location contacts, holiday calendars).
- CU-07..CU-10 `:214/:259/:336/:408` and CU-21..CU-24 `:586/:639/:724/:808` — contact endpoints
  also create/update/delete portal `users` and `employee_scopes` rows (login provisioning).
- CU-11 `:422` — registered after `GET /:id` but is a 2-segment path, so no shadowing.

### Materials
- MT-04 `materialRoutes.js:208` — server-built `where` array + `pushCustomerScope` (placeholder-safe).
- MT-09 `:413` — batch soft delete, ids from request body, gated on `job.edit`.
- MT-10 `:435` — 10 MB limit, extension **and** mimetype must both pass (materialRoutes.js:47-52).

### Members
- MB-01/02 `memberRoutes.js:52/:68` — cross-member dumps gated only on `employee.view`.
- MB-03 `:85` — file lands in `uploads/police_docs` with name `police_${Date.now()}${ext}` (`:36`) —
  no random suffix (see R-09).
- MB-18/19 `:590/:629` — `uploads/member_docs`, `doc_${Date.now()}` (`:565`); MB-21 `:712` —
  `uploads/profile_photos`, `photo_${Date.now()}` (`:699`).
- MB-10 `:438` — refuses deletion while the member still has job assignments.

### Holidays
- HD-03 `holidayRoutes.js:192` — multi-date/range bulk add; missing year calendar → 409, never
  auto-creates calendars (comment `:192-196`).
- HD-08 `:467` / HD-09 `:488` — auth-only by design (comment `:469-471`): scheduling users lack
  `holiday.override`.
- Route order is safe: literals (`/overrides`, `/resolve`, `/availability`) precede `/:id` (`:520`).

### Jobs
- JOB-01/02 `jobRoutes.js:408/:420` — multipart `photos` ≤20 files, 10 MB, image-only filter
  (`:231-239`); filenames randomised (`:227`).
- JOB-06 `:648` — strict `branch_id` eligibility = `member_locations` ∩ active `branch_locations`.
- JOB-17 `:1240` — client ping never trusted: server recomputes geofence distance, derives
  enter/exit transition events; purge by location cron.
- JOB-25 `:1535` — auto-assign algorithm reading capacity, attendance, leave, skills, locations.
- JOB-31 `:1997` — geofence radius from `app_settings 'geofence_meters'`; **out-of-fence check-in
  rejected before any write** (comment `:2000-2006`).
- JOB-33 `:2159` — `requireAuth` only; in-handler `req.user?.role !== 'super_admin'` → 403
  (`:2160-2162`); transactional redo (`conn.beginTransaction`), completed tickets are routed back
  to `waiting_vbms_review` instead of frozen (`:2184-2193`).
- JOB-34/35 `:2259/:2281` — redo history reads.

### Attendance
- ATT-02/03 `attendanceRoutes.js:99/:137` — self defaults from `req.user.member_id` + today; the
  web may pass `member_id`/`date` explicitly; accepts `location_lat/lng` or `latitude/longitude`.
- ATT-12 `:541` — recalculates a date from tickets (same stored procedure used by cron).
- ATT-14 `:704` — reads `attendance_config`; ATT-15 `:718` — **shadowed by ATT-04 (`PUT /:id`,
  registered at `:173`), see R-01.**

### Reviews
- RV-04..RV-08 are ticket-level, RV-09..RV-12 job-level legacy paths; literal `/vbms/ticket|cub/ticket`
  segments are registered before `/vbms/:jobId|/cub/:jobId` (`:305` before `:589`, `:442` before
  `:683`) — no shadowing.
- RV-05 `:355` — creates `ticket_redo_history` row and a replacement ticket (same engine as JOB-33).

### MIS / Notifications / Audit
- MIS-02 `misRoutes.js:47` — recomputes `salary_inputs` from attendance + jobs.
- NT-01..06 `notificationRoutes.js:9-94` — user-scoped (`WHERE user_id = ?`) reads/writes.
- AU-01/02 `auditRoutes.js:9/:41` — read-only log access.

### Users
- US-02/03 `userMgmtRoutes.js:74/:147` — session administration; literal `/login-sessions`
  registered before `GET /:id` (`:165`) — safe.
- US-13..US-20 — role/permission administration; `/roles/all` (`:419`) precedes `/roles/:id`
  (`:497`) — safe; permission replacement is atomic (`:676`).

### Search / Dashboard
- SRCH-01 `searchRoutes.js:15` — `q` ≥2 chars, `%term%` LIKE, LIMIT 50 per entity; **no permission
  check**; customer scoping only for jobs/materials and only when the user has customer scopes —
  `getScopeIds` returns `null` (no restriction) when scopes are empty (`searchRoutes.js:11`),
  the opposite of the dashboard helper (`dashboardRoutes.js:20` returns `[]`). Members/locations/
  customers are returned with their mobile/status fields (`:37`, `:73`).
- DASH-01 `dashboardRoutes.js:79` — one call returning ~15 metric groups; customer roles are
  scoped manually (`:15-22`), staff/admin roles are unscoped by design (`NON_SCOPED_ROLES :10-13`);
  no `requirePermission` in the chain.

### Feedback
- FB-02 `feedbackRoutes.js:22` — only template list/active is public; FB-14/15 `:256/:297` —
  token-authenticated (`crypto.randomBytes(32)`, `data/feedbackStore.js:59`), single-use
  `token_used` flag, reactivation via FB-13.
- FB-11 `:137` — creates request + recipient rows, one token per recipient, dispatches email.
- FB-12 `:227` — delete cascades; deliberately gated on `feedback.delete`, not `feedback.send`.

---

## Section 5 — Middleware & Cron Summary

### Middleware (per-request)
| Middleware | File | Behaviour |
|---|---|---|
| `corsMiddleware` | middleware/cors.js:54 | Allow-list from `config.corsOrigin`; wildcard `*.domain` support (cors.js:17-24); `credentials:true`; blocked origins logged once (cors.js:57-60). Applied globally (app.js:37). |
| `express.json()` | app.js:38 | Default 100 KB body limit; `entity.too.large`→413, `entity.parse.failed`→400 via error handler (app.js:184-190). |
| upload-path rewriter | app.js:61-65 | Rewrites `/uploads/...` → `/api/uploads/...` inside every `res.json` body. |
| `requireAuth` | middleware/auth.js:6 | Bearer JWT → `jwt.verify` → user lookup → must be `active` (`:20`); then **4 DB queries per request**: role permissions (`:28`), employee scopes (`:37`), customer info (`:70`), `roles.child_permissions` (`:45`). Permission-load failure silently degrades to `permissions: []` (`:55-59`); any other failure → 401 (`:64`). |
| `requirePermission(name)` | middleware/rbac.js:7 | `super_admin` bypass (`:11`); DB check of `permissions ⋈ role_permissions` (`:13-18`); missing → 403, DB error → **500** (`:27`). |
| `requireAnyPermission([...])` | middleware/rbac.js:36 | Same, with `IN (...)`; bypass `:39`. |
| `enforceCustomerScope()` | middleware/rbac.js:69 | Computes `req.scopeFilter` for customer-scoped portal roles — **exported but never used by any route** (only referenced in a comment, dashboardRoutes.js:9). |
| 404 handler | app.js:147 | JSON `Route not found` for unmatched paths. |
| error handler | app.js:160 | Preserves status; Multer `LIMIT_FILE_SIZE`→413 `FILE_TOO_LARGE`, unexpected field→400, image filter error→400 `INVALID_FILE_TYPE` (app.js:166-190); 5xx logged, 4xx warned (app.js:192-193). |
| SPA fallback | app.js:135-144 | Prod only, skips `/api`, `/uploads`, `/downloads`. |

Not present (package.json dependencies): **no helmet, no express-rate-limit / rate limiting of
any kind, no hpp, no mongo-sanitize equivalent** (MySQL bound parameters are used throughout).

### Cron jobs (started in server.js:45-46)
| Job | Schedule | Action | Evidence |
|---|---|---|---|
| Attendance auto-refresh | From `attendance_config.refresh_hour/minute` (default 18:00), `auto_refresh_enabled` gate, timezone Asia/Kolkata | `CALL sp_refresh_daily_attendance(today)` then flips past-day `pending` tickets → `absent` | cron/attendanceCron.js:14-29, :35-61; config UI = ATT-14/ATT-15 |
| Location ping retention | Daily 03:20 IST (fixed) + once at boot | Deletes `job_location_pings` older than `app_settings.location_retention_days` (clamped 1-365, default 30) and orphaned pings | cron/locationCron.js:10-27, :29-43 |

Boot sequence: `app.listen` → schema self-heal migrations (`server.js:10-39`, gated by
`AUTO_MIGRATE`) → preference schema `ensureSchema` → `startCron` → `startLocationCron`
(`server.js:41-46`).

---

## Section 6 — Observed Risks (evidence-based)

| # | Risk | Evidence |
|---|---|---|
| R-01 | **`PUT /api/attendance/cron-schedule` is unreachable** — `PUT /:id` (attendanceRoutes.js:173) is registered before `PUT /cron-schedule` (attendanceRoutes.js:718), so Express matches `:id = 'cron-schedule'` and answers 404 "Attendance record not found". The cron schedule cannot be changed through the API; ATT-14 status endpoint works but ATT-15 never fires. | attendanceRoutes.js:173 vs :718 |
| R-02 | **Unauthenticated static serving of all uploads**, including police verification documents (`uploads/police_docs`), member documents, job photos and profile photos — `/uploads` (app.js:67) and `/api/uploads` (app.js:73) have no auth; any leaked/derived URL returns PII files. | app.js:67,73; memberRoutes.js:28,558; jobRoutes.js:196 |
| R-03 | **`enforceCustomerScope()` is never wired into a single route** — customer-scope enforcement depends on ad-hoc per-route helpers (`pushCustomerScope` in attendance/material routes, manual logic in dashboard/search). Any route lacking such a helper silently has no scope filter. | rbac.js:69 (only mention elsewhere: comment dashboardRoutes.js:9) |
| R-04 | **`GET /api/search` has no permission gate and inverted scope semantics** — `getScopeIds` returns `null` (no restriction) for users without scopes (searchRoutes.js:11) while the dashboard returns `[]` (deny) for the same case (dashboardRoutes.js:20); members are queried unscoped and their `mobile` is returned (searchRoutes.js:37,73). Any authenticated role (incl. portal/field users) can enumerate customers, jobs, materials, member phone numbers. | searchRoutes.js:15,11,37,73 |
| R-05 | **Orphaned `assetRoutes.js` with zero permission checks** — 4 handlers, `requireAuth` only, never imported/mounted in app.js (mount list app.js:5-29,107-131). Dead code that becomes an unauthenticated-by-permission CRUD surface the moment someone mounts it. | assetRoutes.js:9,40,63,87 |
| R-06 | **No rate limiting anywhere; public user-enumeration and email-bombing surface** — no rate-limit package in package.json (deps: bcrypt, cors, dotenv, express, jsonwebtoken, multer, mysql2, node-cron, nodemailer only); `POST /forgot-password` sends SMTP mail per call with no throttle (authRoutes.js:199-270); `GET /check-username/:username` is public (authRoutes.js:172). Login lockout exists (authRoutes.js:101-108) but is the only throttled flow. | package.json; authRoutes.js:199,172 |
| R-07 | **`GET /api/dashboard/stats` has no permission requirement** — any authenticated user (field_member, house_keeping, portal roles without customer scopes) receives organisation-wide job/ticket/attendance/audit-adjacent metrics; only customer roles are scoped, staff roles are explicitly unscoped (`NON_SCOPED_ROLES`, dashboardRoutes.js:10-13). | dashboardRoutes.js:79 |
| R-08 | **Runtime mutation of `.env`/env file from an API endpoint** — `POST /api/integrations/email` rewrites the env file on disk (`fs.writeFileSync`, integrationRoutes.js:55-58) and mutates live `config.smtp`; GET returns SMTP host/user (password masked). Depends solely on `settings.edit` + in-handler role list; a write failure or partial write can corrupt deployment config. | integrationRoutes.js:51-58,61-79 |
| R-09 | **Upload filename collisions / silent overwrite** — `police_${Date.now()}${ext}` (memberRoutes.js:36), `doc_${Date.now()}` (memberRoutes.js:565), `photo_${Date.now()}` (memberRoutes.js:699), `profile_${Date.now()}` (profileRoutes.js:41) use millisecond timestamps only; two uploads in the same ms overwrite each other. Job photos already fixed this with a random suffix (jobRoutes.js:226-228) — the pattern was not propagated. | memberRoutes.js:36,565,699; profileRoutes.js:41 vs jobRoutes.js:227 |
| R-10 | **Authorization model is split across middleware and in-handler checks, and costs 5+ queries per request** — `requireAuth` runs 4 DB lookups (auth.js:28,37,45 + customer info :70) and `requirePermission` another (rbac.js:13) on every call; permission-lookup DB errors return 500 (rbac.js:27) while permission-load failures inside `requireAuth` are swallowed to `permissions: []` (auth.js:55-59). Sensitive actions rely on bespoke in-handler role tests instead of the permission table (jobRoutes.js:2160, integrationRoutes.js:79), so audit of "who may do what" must read every handler. | auth.js:28-59; rbac.js:13-27,69; jobRoutes.js:2160; integrationRoutes.js:79 |

### Positive findings (for balance)
- All SQL observed uses `?` placeholders; dynamic fragments are server-built whitelist/placeholder
  strings (dashboardRoutes.js:123-136, searchRoutes.js:41-64, materialRoutes.js:210-216,
  misRoutes.js:26-34) — no request-string concatenation into SQL found.
- Password-reset and feedback tokens are `crypto.randomBytes(32)` (authRoutes.js:19,
  data/feedbackStore.js:59) with single-use invalidation (authRoutes.js:219).
- Multer limits (5-10 MB) + extension/mimetype double checks exist on all six upload configs.
- Route ordering was reviewed for shadowing across all 26 route files; **R-01 is the only genuine
  ordering conflict found**.
