# VBMS / VSFM — Field Dictionary & Glossary

**Date:** 2026-10-19
**Purpose:** client-friendly, plain-English explanations for the field/info-icon text in application forms (§5 of the QA master plan), plus a domain glossary of VBMS/VSFM terms (§6). Written from the shipped code and DB schema — every definition matches actual validation behaviour where one exists.

---

## §5 Field dictionary (form fields, grouped by screen)

Legend — **Type:** S=string, N=number, D=date, B=boolean/flag, E=enum, ID=relation. **Req:** R=required, O=optional. Notes describe what the user should be told via info-icon and what the system actually does.

### 5.1 Masters — States (`/master-setup/states`)

| Field | Type | Req | Plain-English explanation |
|---|---|---|---|
| Name | S(≤100) | R | The state's display name, used everywhere a job or member is filtered by state. Must be unique in practice; max 100 characters (rejected with 400 beyond that). |
| Code | S | O | Short abbreviation used in compact tables and reports (e.g. "TN"). |

### 5.2 Masters — Locations (`/master-setup/locations`)

| Field | Type | Req | Plain-English explanation |
|---|---|---|---|
| Name | S | R | The service location/city label under a state, used when scoping jobs and members. |
| State | ID→states | R | Which state this location belongs to. Drives cascading dropdowns. |
| Status | E(active/inactive) | O | Inactive locations stop appearing in new-job dropdowns but keep history. |

### 5.3 Masters — Customers (`/master-setup/customers`)

| Field | Type | Req | Plain-English explanation |
|---|---|---|---|
| Name | S | R | Customer account name (shown on jobs, invoices, dashboards). |
| Code | S | O | Customer short code; must be unique — duplicate returns 409. |
| Holiday calendar | ID | O | Which holiday calendar applies to this customer's ticket generation (tickets skip holidays listed here). |
| GPS enabled | B | O | When on, field check-in/out is geofenced for this customer's sites; when off, members can check in anywhere (explicit bypass for low-connectivity sites). |
| GPS update interval (s) | N | O | How often the mobile/field client should send location pings while a job is active (seconds; default 15). |
| GPS geofence buffer (m) | N | O | Allowed radius around a branch location for a valid check-in (metres; default 100). |
| GPS idle threshold (min) | N | O | Minutes of no movement before the client reports "idle" (default 5). |
| Status | E | O | Inactive customers are hidden from new jobs. |

### 5.4 Masters — Customer contact (nested under customer)

| Field | Type | Req | Plain-English explanation |
|---|---|---|---|
| Name / Email / Mobile / Designation | S | Name R | Contact person details shown to coordinators when scheduling. Email required only if login access is granted. |
| Is primary | B | O | Exactly one primary contact per customer (setting a new primary clears the old one). |
| Login required | E(yes/no) | O | "yes" provisions a portal user so this person can log in and see their customer-scoped data. |
| Username / Password | S | R if login=yes | Portal credentials; password min 6 chars. Server-side role is always a customer-side role (customer_admin/customer_operator/customer_viewer) regardless of what the API sends — super_admin/admin are rejected (R-05 fix). |
| Login role | E | O | Portal permission level. customer_admin = full customer portal, operator = day-to-day, viewer = read-only. |

### 5.5 Masters — Branch & Branch location (nested)

| Field | Type | Req | Plain-English explanation |
|---|---|---|---|
| Branch name | S | R | The customer's site/office the jobs are booked against. |
| Location (lat/lng/label) | N,N,S | R for branches with GPS | Physical coordinates used as the geofence anchor for check-in. |
| Contacts | relation | O | Site-level contacts (separate from the customer's main contacts). |

### 5.6 Masters — Materials (`/master-setup/materials`)

| Field | Type | Req | Plain-English explanation |
|---|---|---|---|
| Name / Material type | S/ID | R | Item description and its category (electrical, consumables, …). |
| Unit price | N | R | Per-unit cost used in material consumption reporting. |
| GST % | N | O | GST rate applied when this material is consumed (added via step migrations; shown on reports). |
| Order no. | S | O | Purchase-order reference for procurement tracking. |
| Month | M | O | Ordering month this rate applies to (monthly price lists). |
| Owner type | E | O | Who owns/bears the cost of the material (customer-owned, company stock, etc.). |

### 5.7 Masters — Service types / Material types / Companies

| Field | Type | Req | Plain-English explanation |
|---|---|---|---|
| Service type name + default duration | S/N | R | The kind of work a job represents (installation, maintenance…); duration pre-fills job scheduling. |
| Material type name | S | R | Category label used to group materials. |
| Company name + code | S | R | Operating/legal company under which members and jobs are booked. |

### 5.8 MIS — Members (`/mis/members`)

| Field | Type | Req | Plain-English explanation |
|---|---|---|---|
| Employee ID | S | auto | System-generated personnel number. |
| Name / Mobile / Email | S | Name, mobile R; email O | Core contact details. Email may be left blank (historically it crashed create — D-001 fixed: column is nullable). |
| Aadhaar no. | S(12 digits) | O | National ID for statutory compliance; masked in list views. |
| DOB / Joining date | D | O | For HR records and service-length calculations. |
| State / Company | ID | O | Assignment scope — determines which jobs the member can be assigned. |
| Availability status | E | O | Whether the member can receive new assignments today. |
| Employment status | E | O | Active/on-notice/etc.; inactive members cannot be assigned. |
| ESF/EPF number | S | O | Statutory fund numbers (labour compliance). |
| Login enabled | B | O | Grants the member a system login. Turning it off disables access without deleting history. |
| Login username/password | S | R if login enabled | Credentials for member portal. Password min 6. |
| Login role | E | R if login enabled | **Only operational member roles allowed** (field_member, house_keeping, coordinator, vbms_reviewer, cub_reviewer) — admin/super_admin and customer-side roles are rejected server-side (R-05 fix). Default: field_member. |
| Photo | file→URL | O | Profile photo stored under `/uploads` — URLs are now HMAC-signed (7-day TTL) and only readable with a valid signature or login (D-003 fix). |

### 5.9 Jobs (`/job-management/all`)

| Field | Type | Req | Plain-English explanation |
|---|---|---|---|
| Job date / Job end date | D | R | Scheduled start/end of the work. End ≥ start. |
| Customer / Branch | ID | R | Who and where. Branch list filters by chosen customer. |
| Service type | ID | R | What kind of work (drives duration default). |
| Assignees | ID(s) | O | Members assigned; assignment writes an audit row (`assigned_by` = who made the assignment). |
| Status workflow | E | — | Lifecycle: created → assigned → in-progress (geofenced check-in/out) → submitted → VBMS review → (approve → CUB queue) or (rework → redo). |
| Notes / materials consumed | S/list | O | Technician remarks and material usage (price/GST roll up). |

### 5.10 Tickets — Daily tasks (`/job-management/all-tickets`)

| Field | Type | Req | Plain-English explanation |
|---|---|---|---|
| Task date / Active day | D/N | auto | One ticket per (job, task date, active day) — unique key `unique_active_job_date` (D-013 fix; the old flat key that blocked rework was dropped). |
| Photos / checklist | files | O | Proof-of-work images; stored under `/uploads` (signed URLs). |
| Redo lineage | read-only | — | On rework, the original ticket freezes as `redo` and a replacement ticket is auto-generated; `ticket_redo_history` keeps the chain. |
| Ticket review comment | S | O | Reviewer feedback attached to the ticket (`job_reviews.ticket_id` links it — D-011 fix). |

### 5.11 Attendance / Leaves / Capacity

| Field | Type | Req | Plain-English explanation |
|---|---|---|---|
| Check-in / Check-out time | D/time | auto | Captured geofenced: rejected *before* writing if far outside the fence; customer with GPS disabled bypasses the fence. |
| Cron schedule (admin API) | cron S | R | When attendance auto-processing runs. Route reachable after D-002 fix (was shadowed). |
| Leave type / dates / reason | E/D/S | R | Leave request; range validated (end ≥ start, no overlaps). Approve/reject changes DB status. |
| Capacity day slots | N/N | R | How many jobs a member/day can hold; POST validates ranges. |

### 5.12 Reviews (VBMS / CUB) & Feedback

| Field | Type | Req | Plain-English explanation |
|---|---|---|---|
| Approve / Rework | action | — | Approve advances to CUB; Rework creates the redo/replacement pair. |
| Neutral comment | S | O | Reviewer note that does not alter outcome. |
| Feedback rating + comment | 1–5 + S | R for public form | Public survey (`/feedback/:token`): tokenized link, double-submit prevented. |
| Feedback request | action | — | Sends the tokenized survey to the customer contact (requires SMTP — R-06 env). |

### 5.13 Users & Roles (`/users-roles/users`)

| Field | Type | Req | Plain-English explanation |
|---|---|---|---|
| Name / Email / Phone | S | Name, email R | Account identity. |
| Username | S | O | Login handle; unique. |
| Password | S(≥6, policy≤128) | R | Hashed with bcrypt; plaintext retained in `users.original_password` **by product decision** (R-01) for admin recovery display — never returned by APIs, scrubbed from audit logs. |
| Role | E(10 values) | R(default coordinator) | Must be one of the DB enum values — invalid → 400 (R-05 fix). Only a super_admin may assign `super_admin` (403 otherwise). |
| Status | E(active/inactive) | O(default active) | Inactive accounts cannot log in (401 on login). Deletion is a soft delete to inactive + clears any lockout rows (R-07 fix). |

### 5.14 Settings / Preferences

| Field | Type | Req | Plain-English explanation |
|---|---|---|---|
| Font size / scale | E/N | O | Personalization preference. Known defect: 500 hardcoded px declarations in CSS currently defeat this (DEF-UI-001) — not yet fixed (UI-redesign constraint). |
| Theme / density / topbar | E | O | Look-and-feel choices persisted per user (steps 2/3 migrations). |
| Notification toggles | B list | O | Which events push email/in-app notifications. |
| Password policy (admin) | N/B | O | `security_password_min_length` (default 8), `security_require_special_chars` (default true) — enforced on reset/change. |

### 5.15 Holidays (`/holiday-calendar/*`)

| Field | Type | Req | Plain-English explanation |
|---|---|---|---|
| Calendar | S/D list | — | Named set of holidays a customer can be linked to. |
| Override dates | D | O | One-off additions/removals for a customer on top of the calendar. |
| Rules | E | O | Whether ticket generation skips holidays and how weekends are treated. |

---

## §6 Glossary

| Term | Definition |
|---|---|
| **VBMS** | Voltech Business Management System — the admin/coordinator web app (this codebase's primary app). |
| **VSFM** | Voltech Field Service Management — the field/operations product name used for the same platform (deployment at vsfm.voltechgroup.com). |
| **MIS** | Management Information System — the member/personnel module (`/mis/*`: members, documents, locations, skills). |
| **CUB** | Second-tier review board: jobs approved by VBMS review queue for CUB sign-off before closure. |
| **CUB reviewer** | Role that sees only the CUB review queue (read + approve/comment/feedback actions). |
| **Job** | A unit of scheduled work at a customer branch for a service type on a date range. |
| **Ticket (Daily task)** | Per-day slice of a job (`job_daily_tasks`); unique per (job, task_date, active_day). Field members work against tickets. |
| **Active day** | Which scheduled day of a multi-day job a ticket belongs to (part of the unique ticket key). |
| **Assignment** | Linking a member to a job/ticket; `assigned_by` records who assigned (audit). |
| **Redo / Rework** | Reviewer rejects submitted work: original ticket freezes with status `redo`, a replacement ticket is auto-generated; chain kept in `ticket_redo_history`. |
| **Replacement ticket** | The new ticket created by a rework, carrying the same scope as the frozen original. |
| **Geofence** | Radius (customer's GPS buffer, default 100 m) around a branch location within which check-in/out is accepted. Check-ins far outside are rejected *before* any row is written. |
| **GPS bypass** | Customer with `gps_enabled = 0`: members may check in/out without location validation. |
| **Check-in / Check-out** | Start/end capture of field work on a ticket; geofenced, audited. |
| **Attendance cron schedule** | Admin-configured schedule for automatic attendance processing (route: `PUT /api/attendance/cron-schedule`). |
| **Capacity** | Per-member/day limit of jobs, used by planning views. |
| **Scope (`employee_scopes`)** | Row-level visibility rules: a user with scope `customer/5` sees only customer 5's data. Empty scope list = admin-wide. |
| **Login role** | Role assigned when provisioning a login through member/contact forms (always validated against a whitelist — R-05). |
| **`users.role` (system role)** | Authoritative permission role from a 10-value enum: super_admin, admin, coordinator, field_member, vbms_reviewer, cub_reviewer, customer_admin, customer_viewer, customer_operator, house_keeping. |
| **RBAC** | Role-based access control: `requireAuth` + `requirePermission(…)` per route; enforced server-side (suite: 18/18). |
| **`original_password`** | Plaintext copy of the user's password kept in DB **by product decision** (admin recovery display). Excluded from API responses and scrubbed from audit JSON. |
| **Account lockout** | 5 consecutive failed logins → 15-min lock (HTTP 423) keyed by login identifier (`account_lockouts`). |
| **Per-IP login limiter** | New: 40 failed logins per IP per 15 min → HTTP 429 regardless of account (anti-spraying); success resets the counter. |
| **Signed upload URL** | `/api/uploads/<file>?exp=…&sig=…` — HMAC-SHA256 over `path|exp`, key `sha256(JWT_SECRET:uploads)`, 7-day TTL; required for unauthenticated file reads (D-003). Response payloads re-sign any persisted `/uploads/` path so stored rows never go dark. |
| **APK downloads** | Public static mount (`/api/downloads/file/vbms.apk`) serving the field app installer for QR codes — intentionally unauthenticated (D-004 by-design), contains no user data. |
| **Audit log (`audit_logs`)** | Who-did-what rows; JSON payloads pass through `scrubSecrets` so password/token/secret keys are masked. |
| **Migration step files** | `migration_step*.sql` applied in order by `runMigrations.js`, tracked in `schema_migrations`. |
| **Standalone migrations** | Non-step `.sql` files now applied by a second guarded pass (`applyStandaloneFiles`) — e.g. `migration_branch_scope.sql`, `migration_contact_login.sql` (D-009 fix). |
| **Step 51** | `migration_step51_qc_defect_fixes.sql` — this engagement's idempotent schema repair (nullable member email, photo_url, ticket_id, assigned_by, created_by, location_contacts.user_id, customers.gps_*, unique-index repair). |
| **CRITICAL_COLUMNS** | `schemaSpec.js` list healed at boot (`ensureCriticalColumns`) so a partially-provisioned DB self-repairs even with `AUTO_MIGRATE=false`. |
| **Pagination clamp** | Global middleware: `page ≥ 1`, non-numeric → default, `limit` capped at `MAX_LIMIT = 5000` (D-005..007, R-008). |
| **Soft delete** | Users/customers/members are flagged `inactive` rather than dropped (history and FK integrity preserved). |
| **Public feedback token** | One-time URL token for customer surveys (`/feedback/:token`); double-submit blocked by used-token check. |
| **Mail formats** | Admin-managed email templates used by notifications/feedback (SMTP required to actually send — R-06). |
| **Housekeeping role** | Non-technical staff role: can view, cannot edit settings; also a valid member login role. |
| **Super admin** | Only role that bypasses all permission checks and the only role allowed to create other super admins. |

---

*Sources: backend routes (authRoutes, userMgmtRoutes, memberRoutes, customerRoutes, jobRoutes, attendanceRoutes), `schema.sql` + migration steps 1–51, and the executed test evidence in `qa/04-automation/results/`.*
