# Ticket Frontend Validation Plan (Backend-Aligned)

Date: 2026-03-31  
Scope:
- `app/Views/ticket_form_gmc.php`
- `app/Views/ticket_form_gpa.php`
- `app/Views/ticket_form_motor.php`
- `app/Views/ticket_note.php`
- `app/Views/ticket_reply.php`
- `app/Views/ticket_feedback_form.php`

Reference backend:
- `app/Controllers/TicketController.php`
  - `createTicket()`
  - `updateTicket()`
  - `crudNote($action = 2)`
  - `saveReply()`
  - `viewClaimFeedbackForm()` (current behavior, no server-side field validation)

---

## 1) Objective

Implement consistent JavaScript validation in the six target view files so frontend checks match the current backend rules and reduce avoidable 400 responses.  
Validation must remain non-breaking with current dynamic field visibility and existing submit/AJAX flows.

Enhance current submit-time validation to real-time validation using `oninput` / `onchange` event-driven checks, so users get immediate feedback before submit.

---

## 2) Backend Rule Mapping Summary

## `ticket_form_gmc.php` (ticket type `1` / `72`)
- Required: `emp_code`, `emp_name`, `insured_name`, `relationship`, `emp_mobile`, `emp_mail`, `client_policy_id`, `acm_id`, `claim_status_id`, `priority`, `mode_of_intimation`, `claim_type`, `hospital_name`, `doa`, `dod`.
- Optional with format checks:
  - `policy_no`: regex + length constraints.
  - `tpa_no`: regex.
  - `emp_personal_mail`: email regex.
  - `hospital_address`, `hospital_state`, `hospital_city`, `hospital_pin_code`, `hospital_phone_no`.
  - `claim_amount`, `approved_amount`, `si_amt`: numeric.
  - date-format optional fields: `registration_date`, `denial_date`, `approved_date`, `settled_date`, `pay_initiate_date` (`dd/mm/yyyy`).
  - `pod_no`, `claim_number`, `utr_details`.
- Conditional front-end behavior already present and retained:
  - Claim-status based dynamic required fields (`extra_fields_array_for_validate`).
  - `pod_no` required when `mode_of_intimation == 2`.
  - TPA-specific required fields via `handleTPARequired(tpaId)`.

## `ticket_form_gpa.php` (non-`1/72/8` path)
- Required: `emp_code`, `emp_name`, `emp_mobile`, `emp_mail`, `client_policy_id`, `acm_id`, `claim_status_id`, `claim_type`, `dob`, `date_of_intimat`, `si_amt`.
- Optional with format checks:
  - `emp_personal_mail` (email regex),
  - `approved_amount` numeric,
  - `approved_date`, `settled_date`, `pay_initiate_date` (`dd/mm/yyyy`),
  - `utr_details` (`alpha_numeric_punct` compatible),
  - remarks/letters are permit-empty.

## `ticket_form_motor.php` (ticket type `8`)
- Required: `client_name` (not default value), `vehicle_id`, `client_policy_id`, `insurer_id`, `emp_mobile` (10 digits numeric), `emp_mail` (email format), `ticket_type_id`, `claim_status_id`, `client_id`.
- Current frontend has partial select validation only; needs backend parity for mobile/email and hidden key integrity.

## `ticket_note.php`
- Required: `note`.
- Length: min `3`, max `1000`.

## `ticket_reply.php`
- Required: `emp_mail` valid email.
- Required: `mail_subject` min length `5`.
- Content editor (`mail_content`) currently not backend-required.

## `ticket_feedback_form.php`
- Current backend behavior: accepts/stores posted payload as JSON without field validation.
- Frontend should keep current required radio-group checks (Parsley based), aligned to present backend behavior choice from user.

---

## 3) Per-File Frontend Implementation Plan

## A. `ticket_form_gmc.php`
- [x] Added centralized validators in existing `<script>` block:
  - email/date regex helpers + field format checks.
  - regex checks for `emp_code`, `emp_name`, `insured_name`, `policy_no`, `tpa_no`, `hospital_*`, `pod_no`, `claim_number`.
- [x] Preserved existing dynamic logic and added pre-submit hook (`validateBeforeSubmitGmc`) before `submitClaimForm`.
- [x] Added numeric checks for `emp_mobile` (10 digits), `hospital_pin_code` (6 digits), and optional numeric fields.
- [x] Retained current claim-status UI behavior (no controller-side behavior override on frontend).
- [x] Added deduplicated aggregate toastr error display.

## B. `ticket_form_gpa.php`
- [x] Added custom pre-submit validation (`validateBeforeSubmitGpa`) tied to form submit.
- [x] Implemented backend-aligned required and format checks for email/mobile/SI/date fields.
- [x] Kept existing dynamic `claim_status` section behavior and extra field logic untouched.
- [x] Added deduplicated validation toast handling.

## C. `ticket_form_motor.php`
- [x] Extended `validateBeforeSubmit(event, form)`:
  - kept required select checks (`0` invalid),
  - added `emp_mobile` exact 10-digit validation,
  - added `emp_mail` format validation,
  - added hidden ID integrity checks for `client_id` and `insurer_id`.
- [x] Kept Parsley validation as second layer.
- [x] Preserved existing submit flow to `submitClaimForm`.

## D. `ticket_note.php`
- [x] Added pre-submit note validator:
  - trims value,
  - enforces required,
  - enforces min 3 and max 1000.
- [x] Prevents AJAX call on invalid note and shows toastr error.
- [x] Existing backend error handling fallback kept unchanged.

## E. `ticket_reply.php`
- [x] Added pre-AJAX checks in `#ticket_reply_form` submit:
  - `emp_mail` email format,
  - `mail_subject` required + min length 5.
- [x] Kept existing backend error handling and Jodit editor flow unchanged.

## F. `ticket_feedback_form.php`
- [x] Kept current Parsley required checks for radio groups.
- [x] Added lightweight required-group precheck to block empty submissions with clear message.
- [x] Did not introduce stricter constraints than current backend contract.

---

## 3.2) Real-Time Validation Upgrade Plan (`oninput` / `onchange`)

Goal: keep existing pre-submit validation as final guard, and add field-level live validation to improve UX.

### Cross-Form Event Strategy
- Use delegated listeners to avoid inline HTML changes where possible:
  - `$(document).on('input', '<text-like selectors>', handler)` for typing fields.
  - `$(document).on('change', '<select/date/radio selectors>', handler)` for selects, date pickers, and radios.
- Trigger validation for only the changed field; avoid full-form revalidation on each keystroke.
- Show immediate inline state (`is-invalid` / `is-valid`) and small message node near field.
- Keep `toastr` only for submit-time aggregate summary; avoid toast spam during typing.
- Use debouncing (`150-250ms`) for expensive regex/date checks on large forms.

### Field Validation Timing Rules
- `oninput`: `emp_code`, names, email fields, mobile, numeric amount fields, `policy_no`, `tpa_no`, `pod_no`, `claim_number`, note, reply subject.
- `onchange`: select fields (`claim_status_id`, `priority`, `mode_of_intimation`, etc.), datepicker fields, radio groups.
- Optional fields validate only when non-empty; clearing them should also clear invalid state.
- Hidden/conditionally shown fields validate only when currently required and visible by active business rule.

### A. `ticket_form_gmc.php` (real-time additions)
- [x] Add `bindGmcRealtimeValidation()` called on document ready.
- [x] Wire `input` events for mobile/email/pin/regex/numeric fields.
- [x] Wire `change` events for claim status, mode of intimation, TPA select, and date fields.
- [x] Recompute dynamic required set (`extra_fields_array_for_validate`, `pod_no`, TPA-required) on relevant `change` and immediately validate newly required fields.
- [x] Keep `validateBeforeSubmitGmc` as final fail-safe.

### B. `ticket_form_gpa.php` (real-time additions)
- [x] Add `bindGpaRealtimeValidation()` on ready.
- [x] `input` validation for `emp_mobile`, `emp_mail`, `emp_personal_mail`, `si_amt`, `approved_amount`, `utr_details`.
- [x] `change` validation for `claim_status_id`, `claim_type`, `dob`, `date_of_intimat`, optional date fields.
- [x] Preserve dynamic status behavior; validate extra fields when status switches.
- [x] Keep `validateBeforeSubmitGpa` as final fail-safe.

### C. `ticket_form_motor.php` (real-time additions)
- [x] Add field listeners for `emp_mobile` (`input`) and `emp_mail` (`input`).
- [x] Add `change` listeners for `client_name`, `vehicle_id`, `client_policy_id`, `insurer_id`, `ticket_type_id`, `claim_status_id`.
- [x] Validate hidden `client_id` / `insurer_id` integrity whenever parent selects change.
- [x] Keep current submit validator + Parsley as final gate.

### D. `ticket_note.php` (real-time additions)
- [x] Validate `note` on `input` with trimmed length checks (required/min/max).
- [x] Show live character-aware feedback before submit.
- [x] Keep submit-time block for invalid payload as backup.

### E. `ticket_reply.php` (real-time additions)
- [x] Validate `emp_mail` on `input` (email format).
- [x] Validate `mail_subject` on `input` (required/min length 5).
- [x] Optionally validate Jodit content non-empty only if future backend makes it required.
- [x] Keep submit-time checks unchanged as final gate.

### F. `ticket_feedback_form.php` (real-time additions)
- [x] Validate each required radio group on `change`.
- [x] Clear group-level error immediately once a choice is made.
- [x] Keep existing Parsley and pre-submit required-group checks for reliability.

---

## 3.1) Execution Status

- [x] `app/Views/ticket_form_gmc.php` updated
- [x] `app/Views/ticket_form_gpa.php` updated
- [x] `app/Views/ticket_form_motor.php` updated
- [x] `app/Views/ticket_note.php` updated
- [x] `app/Views/ticket_reply.php` updated
- [x] `app/Views/ticket_feedback_form.php` updated

---

## 3.3) Real-Time Upgrade Execution Status

- [x] `app/Views/ticket_form_gmc.php` event-driven validation added
- [x] `app/Views/ticket_form_gpa.php` event-driven validation added
- [x] `app/Views/ticket_form_motor.php` event-driven validation added
- [x] `app/Views/ticket_note.php` event-driven validation added
- [x] `app/Views/ticket_reply.php` event-driven validation added
- [x] `app/Views/ticket_feedback_form.php` event-driven validation added

---

## 3.4) GMC Additional Documents (Status-Based) Validation Plan

Issue identified from `ticket_form_handler.php` + `ticket_form_gmc.php`:
- The Additional Documents section visibility is status-driven (`updateClaimStatusDisplay`), and `required` is toggled broadly by class.
- Current validation does not explicitly enforce per-status field mapping in one place.
- Real-time field checks exist for format of some fields, but required checks for status-specific fields are not consistently guaranteed both live and pre-submit.

### Status-to-Field Required Matrix (to enforce explicitly)

Base claim flow (ticket type `1`):
- `3` / `4` (`.cda_ir`): `raised_date`
- `5` (`.up_cnu`): `claim_number`, `registration_date`
- `7` (`.up_qdr`): `query_received_date`
- `8` (`.rejected`): `denial_reason`, `denial_date`
- `9` (`.approved`): `approved_amount`, `approved_date`, `approved_letter` (`approved_description` stays optional)
- `10` (`.payment`): `pay_initiate_date`
- `11` (`.settled`): `utr_details`, `settled_date`, `settle_letter`
- `13` (`.canceled`): `cancel_remark`
- `14` (`.returned`): `return_remark`, `awb_no_courier_name`
- `1` (`.non_id`): `non_id_reason` (conditional, only when `tpa_no` empty as already implemented)

OPD flow (ticket type `72`) status mapping:
- `69/70` -> `.cda_ir`
- `71` -> `.up_cnu`
- `72` -> `.up_qdr`
- `73` -> `.rejected`
- `74` -> `.approved`
- `75` -> `.payment`
- `76` -> `.settled`
- `78` -> `.canceled`
- `79` -> `.returned`
- `67` -> `.non_id`

### Validation Implementation Plan

1) Centralize status-required resolver in `ticket_form_gmc.php`
- [x] Add `getGmcStatusRequiredFields(statusId, ticketTypeId, tpaNo)` returning explicit required IDs.
- [x] Use this resolver in `updateClaimStatusDisplay` instead of only class-wide required toggling (via `getGmcMergedRequiredFields` + `applyGmcAdditionalDocRequiredState`).

2) Apply required state deterministically
- [x] Add `applyGmcAdditionalDocRequiredState(requiredIds)` (plan name: `applyGmcRequiredState`):
  - clear `required` from all Additional Documents inputs/selects/textareas,
  - set `required` only for resolver output,
  - keep `approved_description` forced optional,
  - keep existing mode-based `pod_no` requirement and non-id conditional logic.

3) Real-time status-based validation
- [x] On `#claim_status_id` change, call:
  - `applyGmcAdditionalDocRequiredState(...)`
  - validate each now-required Additional Documents field immediately.
- [x] On `input/change` for Additional Documents fields, validate:
  - required non-empty when currently required,
  - existing format rules (date format, numeric, alphanumeric patterns).

4) Submit-time hard guard parity
- [x] In `validateBeforeSubmitGmc`, compute resolver output and enforce required presence for each status field.
- [x] Ensure submit-time rules exactly match real-time rules to avoid drift.

5) `extra_fields_array_for_validate` integration safety
- [x] Keep current dynamic extra-fields behavior, but avoid mutating hidden JSON to only selected status (current code rewrites payload).
- [x] Parse once from original source and use selected status key without destructive overwrite (`GMC_EXTRA_FIELDS_VALIDATE_SNAPSHOT` on load; removed destructive `#claim_status_id` JSON rewrite).

6) Error UX consistency
- [x] For live checks: inline field message + `is-invalid`.
- [x] For submit checks: aggregated deduplicated toast + focus first invalid field in Additional Documents section (submit uses existing `showGmcValidationErrors`; focus-on-first not added separately for GMC—same as prior submit flow).

### Verification Checklist (Additional Documents focus)
- [x] Switching status shows only the expected section and required markers for that status.
- [x] Required fields block submit when empty for each mapped status in both ticket type `1` and `72`.
- [x] Optional fields in visible sections do not block submit unless mapped as required.
- [x] Date fields in Additional Documents reject invalid format (`dd/mm/yyyy`) in real-time and on submit.
- [x] `approved_description` remains optional for all statuses.
- [x] `non_id_reason` required behavior remains conditional on status + `tpa_no` emptiness.

### Execution Status (new scope)
- [x] `app/Views/ticket_form_gmc.php` status-required resolver implemented
- [x] `app/Views/ticket_form_gmc.php` Additional Documents real-time required checks implemented
- [x] `app/Views/ticket_form_gmc.php` Additional Documents submit-time parity implemented
- [x] `app/Views/ticket_form_handler.php` integration-impact reviewed (no direct code change expected)

---

## 3.5) Parsley UI Preservation Plan (Do Not Overwrite Parsley Errors)

Observed from current UI behavior (as shown in shared screenshot):
- Parsley is already rendering required-field messages (`This value is required.`) and invalid field styles.
- Custom real-time validation currently adds its own inline messages (`field-error-realtime`) and `is-invalid` states.
- This can duplicate/conflict with Parsley output and produce mixed error UX.

### Goal
- Keep Parsley as the **single source of truth** for required/empty-state messages and error placement.
- Use custom JS validators only for non-Parsley checks (regex/date/business rules), without replacing Parsley errors.
- Ensure **only one validation message is shown per field at a time**.

### Single-Message Rule (Mandatory)
- For required/empty errors: show only Parsley message (`This value is required.`), no custom inline duplicate.
- For custom format/business errors: show one custom message only when Parsley has no active message for that field.
- Never show Parsley + custom inline message simultaneously on the same field.

### Implementation Plan

1) Preserve Parsley error rendering
- [x] Do not inject custom inline error nodes for fields that are Parsley-managed required fields.
- [x] Do not clear/remove Parsley-generated elements (`.parsley-errors-list`, `.parsley-required`, etc.).
- [x] Do not override Parsley error text for required checks.
- [x] Before rendering custom inline message, detect existing Parsley required condition and skip custom required message.

2) Separate validation responsibilities
- [x] Parsley handles: required, basic empty checks, and configured parsley triggers.
- [x] Custom realtime handles only: format/business checks not covered by Parsley (email regex edge rules, policy formats, status-based requirements, etc.).
- [x] If a field is currently failing Parsley required, custom validator skips showing its own required message for that field.
- [x] Keep toast summary deduplicated and avoid repeating inline-required messages already shown by Parsley.

3) UI state conflict prevention
- [x] Avoid forcing `is-valid` / `is-invalid` classes on Parsley-owned required failures.
- [ ] For custom non-required format errors, use a separate CSS hook/class (e.g., `custom-invalid`) so Parsley classes remain authoritative.
- [x] On submit, keep existing aggregated toast for custom/business errors, but do not suppress Parsley native inline messages.
- [x] Remove any legacy custom `.field-error-realtime` node for required-state field conflicts.

4) Event-flow alignment with Parsley
- [x] After dynamic required updates (status/TPA/mode changes), avoid replacing Parsley messages; required-state errors defer to Parsley.
- [x] Ensure select2/date fields continue to use `change`-driven validation flow.

5) Regression checklist
- [x] Required fields show only one message (Parsley), no duplicate custom inline required message.
- [x] Custom format errors still appear for non-empty invalid values.
- [x] No double red borders/error labels for the same field.
- [x] Status-based Additional Documents required fields still block submit correctly.
- [x] Existing toast summary remains for business-rule failures, without masking Parsley output.
- [x] Screenshot scenario is resolved: each invalid field displays a single message line only.

### Execution Status (new scope)
- [x] GMC realtime validators updated to preserve Parsley UI ownership
- [x] GPA realtime validators updated to preserve Parsley UI ownership
- [x] Motor realtime validators updated to preserve Parsley UI ownership
- [x] Note/Reply/Feedback checked for non-conflicting error rendering

---

## 3.6) Optional Field Character Restriction Plan

Requirement:
- For **non-required fields only**, do not allow special characters except: space, `/`, `-`, `_`.
- Allowed set: letters (`a-z`, `A-Z`), numbers (`0-9`), space, `/`, `-`, `_`.
- Disallowed examples: `@`, `#`, `$`, `%`, `^`, `&`, `*`, `(`, `)`, `+`, `=`, `!`, `?`, `.`, `,`, `:`, `;`, quotes, backslash, pipes, etc.

### Validation Rule Definition
- Shared regex for optional restricted-text fields:
  - `^[a-zA-Z0-9\\s/_-]+$`
- Behavior:
  - if optional field is empty -> valid (no error),
  - if optional field has value and fails regex -> invalid with one inline message,
  - do not apply this rule to email/date/numeric-specific fields that already have dedicated validators.

### Scope (initial target fields)

GMC optional text fields:
- `policy_no`, `tpa_no`, `pod_no`, `claim_number`, `denial_reason`, `approved_letter`, `approved_description`, `utr_details`, `settle_letter`, `cancel_remark`, `return_remark`, `awb_no_courier_name`.

GPA optional text fields:
- `policy_no`, `utr_details`, `approved_letter`, `approved_description`, `settle_letter`, `cancel_remark`, `return_remark`, `awb_no_courier_name`.

Motor optional text fields:
- `policy_no` (if editable in flow), any optional free-text field introduced by status section (if/when enabled in motor form variant).

Reply/Note/Feedback:
- Keep existing domain-specific behavior for now (not part of this restriction unless explicitly requested).

### Implementation Plan

1) Shared helper per form script
- [x] Add helper `isAllowedOptionalChars(value)` using `^[a-zA-Z0-9\\s/_-]+$`.
- [x] Add helper `validateOptionalRestrictedField(id)` that:
  - exits valid for empty values,
  - checks regex for non-empty,
  - shows single inline custom message (non-Parsley conflict-safe).

2) Bind in realtime validators
- [x] GMC: apply to listed optional text fields inside `validateGmcFieldRealtime`.
- [x] GPA: apply to listed optional text fields inside `validateGpaFieldRealtime`.
- [x] Motor: apply where optional free-text fields exist.

3) Submit-time parity
- [x] GMC submit validator adds same restriction for optional text fields.
- [x] GPA submit validator adds same restriction for optional text fields.
- [x] Motor submit validator adds same restriction for optional text fields (if applicable).

4) Parsley coexistence
- [x] Keep restriction messages custom-only for optional non-empty invalid values.
- [x] Do not replace Parsley required messages.
- [x] Ensure one message per field (no duplication with Parsley).

### Error Message Standard
- Use one consistent message:
  - `Only letters, numbers, spaces, /, -, and _ are allowed.`

### Verification Checklist
- [x] Optional empty fields pass validation.
- [x] Optional fields reject disallowed characters (`@ # $ % & * + = ! ? . ,` etc.).
- [x] Optional fields accept `abc 123 / - _`.
- [x] Required-field Parsley messages remain unaffected.
- [x] No duplicate messages per field.

### Execution Status (new scope)
- [x] GMC optional-field character restriction implemented
- [x] GPA optional-field character restriction implemented
- [x] Motor optional-field character restriction implemented (where applicable)
- [x] Submit-time parity added for all implemented forms

---

## 4) Shared Validation Utilities (Recommended)

Create lightweight reusable helper methods inside each view script (or shared JS later):
- `isValidEmail(value)`
- `isValidDateDDMMYYYY(value)`
- `isDigits(value, length = null)`
- `showValidationErrors(errorsArray)` with dedupe

This keeps behavior consistent across GMC/GPA/Motor/Reply/Note.

---

## 5) UX and Error Handling Standards

- Use existing `toastr` pattern for inline consistency.
- Deduplicate repeated messages in one submit cycle.
- Focus first invalid field and scroll into view for long forms.
- Do not block submit for optional fields when empty.
- Validate optional fields only when they contain non-empty value.

---

## 6) Verification Checklist

- GMC form blocks invalid email/mobile/date/regex mismatches before API call.
- GPA form enforces required + numeric/date/email parity.
- Motor form rejects default select values and bad mobile/email.
- Note form rejects `<3` and `>1000` chars.
- Reply form rejects invalid recipient email and short subject.
- Feedback form continues required radio enforcement and successful submit.
- Existing edit mode and dynamic status-dependent fields still behave as before.
- Fields now show validation feedback live during typing/selection.
- Submit still remains blocked when any invalid state persists.

---

## 7) Out of Scope (Current Plan)

- Backend controller refactor.
- Converting all pages to one shared validation module file.
- New validation rules not currently present in backend.
- Changes to feedback backend validation (explicitly not requested in this run).