@@ -1512,31 +1518,74 @@ input:checked + .slider_blue::before {
});
- //for date convert to indian formate like this 'yyyy-mm-dd' to this 'dd-mm-yyyy'
- function rearrangeDateFormat(inputDate) {
-
- console.log('inputDate', inputDate)
- // Check if inputDate is a string and not empty
- if (typeof inputDate === 'string' && inputDate.trim() !== '') {
- var dateComponents = inputDate.split("-");
-
- // Check if dateComponents has the expected number of parts
- if (dateComponents.length === 3) {
- var rearrangedDate = dateComponents[2] + "-" + dateComponents[1] + "-" + dateComponents[0];
- return rearrangedDate;
- } else {
- // Handle unexpected date format
- return '';
- }
- } else {
- // Handle the case where inputDate is not a valid string
- return '';
+ function parsePolicyDate(inputDate) {
+ if (!inputDate || (typeof inputDate === 'string' && inputDate.trim() === '')) {
+ return null;
}
+ var str = String(inputDate).trim();
+ var dmyMon = str.match(/^(\d{1,2})\/([A-Za-z]{3})\/(\d{4})$/i);
+ if (dmyMon) {
+ return new Date(str);
+ }
+ var dmy = str.match(/^(\d{1,2})\/(\d{1,2})\/(\d{4})$/);
+ if (dmy) {
+ return new Date(parseInt(dmy[3], 10), parseInt(dmy[2], 10) - 1, parseInt(dmy[1], 10));
+ }
+ var iso = str.match(/^(\d{4})-(\d{2})-(\d{2})/);
+ if (iso) {
+ return new Date(parseInt(iso[1], 10), parseInt(iso[2], 10) - 1, parseInt(iso[3], 10));
+ }
+ var dmyDash = str.match(/^(\d{1,2})-([A-Za-z]{3}|\d{1,2})-(\d{4})$/i);
+ if (dmyDash) {
+ if (/^[A-Za-z]{3}$/i.test(dmyDash[2])) {
+ return new Date(str);
+ }
+ return new Date(parseInt(dmyDash[3], 10), parseInt(dmyDash[2], 10) - 1, parseInt(dmyDash[1], 10));
+ }
+ var parsed = new Date(str);
+ return isNaN(parsed.getTime()) ? null : parsed;
+ }
+
+ var policyMonthNames = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+ function formatPolicyDisplayDate(inputDate) {
+ var d = parsePolicyDate(inputDate);
+ if (!d) {
+ return (inputDate && String(inputDate).trim() !== '') ? String(inputDate) : '';
+ }
+ return d.getDate() + '/' + policyMonthNames[d.getMonth()] + '/' + d.getFullYear();
+ }
+
+ function formatPolicyFormDate(inputDate) {
+ var d = parsePolicyDate(inputDate);
+ if (!d) {
+ return (inputDate && String(inputDate).trim() !== '') ? String(inputDate) : '';
+ }
+ var day = ('0' + d.getDate()).slice(-2);
+ var month = ('0' + (d.getMonth() + 1)).slice(-2);
+ return day + '/' + month + '/' + d.getFullYear();
+ }
+
+ function policyFormDateForSubmit(inputDate) {
+ var formatted = formatPolicyFormDate(inputDate);
+ if (!formatted) {
+ return inputDate || '';
+ }
+ var parts = formatted.split('/');
+ return parts[0] + '-' + parts[1] + '-' + parts[2];
+ }
+
+ // Convert API/storage dates to d/m/Y for form inputs
+ function rearrangeDateFormat(inputDate) {
+ return formatPolicyFormDate(inputDate);
}
function checkDateStatus(inputDate, bg = false) {
- var givenDate = new Date(inputDate);
+ var givenDate = parsePolicyDate(inputDate);
+ if (!givenDate) {
+ return bg ? '' : '';
+ }
var currentDate = new Date();
if (bg != false) {
@@ -2763,7 +2812,7 @@ $(document).ready(function () {
${policy_name_data} |
${item.branch_name ? item.branch_name : ' - '} |
${tpaValue} |
-
${(item.policy_start_date)} / ${(item.policy_end_date)} |
+
${formatPolicyDisplayDate(item.policy_start_date)} - ${formatPolicyDisplayDate(item.policy_end_date)} |
${checkDateStatus(item.policy_end_date, 1)} |
@@ -2809,7 +2858,7 @@ $(document).ready(function () {
| ${policy_name_data} |
${item.branch_name ? item.branch_name : ' - '} |
${tpaValue} |
-
${(item.policy_start_date)} / ${(item.policy_end_date)} |
+
${formatPolicyDisplayDate(item.policy_start_date)} - ${formatPolicyDisplayDate(item.policy_end_date)} |
${checkDateStatus(item.policy_end_date, 1)} |
diff --git a/app/Views/commission_file_upload.php b/app/Views/commission_file_upload.php
index 685074c2..ac13bac9 100644
--- a/app/Views/commission_file_upload.php
+++ b/app/Views/commission_file_upload.php
@@ -182,7 +182,7 @@
| |
|
|
-
' . $row['created_user_name'] . '' ?>
+ | ' . $row['created_user_name'] . '' ?>
|
diff --git a/app/Views/docs/bds-commission.php b/app/Views/docs/bds-commission.php
new file mode 100644
index 00000000..55f83aed
--- /dev/null
+++ b/app/Views/docs/bds-commission.php
@@ -0,0 +1,292 @@
+
+
+
+ BDS commission is a two-part flow: admins upload commission rules
+ (Excel) per insurer, month, and department; partner/BDS systems then call an API to
+ calculate payout for a policy using those rules.
+
+
+ Overview
+
+
+
+flowchart LR
+ A["Upload rules Excel"] --> B["Save JSON on disk"]
+ B --> C["Edit rules in UI"]
+ D["Policy data POST"] --> E["Load matching JSON"]
+ E --> F["Match rule and return payout"]
+
+
+
+ In short:
+
+ - Setup:
RuleImportController + commission_file_upload.php — import and manage rules.
+ - Runtime:
POST getCommission → InsuranceCommissionController::initiateCommissionCalc — read JSON, pick first matching rule, return payout.
+ - Rules file path:
writable/uploads/commission/rules/{MONYYYY}/{insurer_id}_{department}.json (e.g. SEP2025/5_motor.json).
+
+
+ Key files
+
+
+
+ | Part | File |
|---|
+
+
+ | Upload list UI | app/Views/commission_file_upload.php |
+ | Rules editor UI | app/Views/commission_rules_list.php |
+ | Upload and editor API | app/Controllers/RuleImportController.php |
+ | Excel parsing | ruleImportService (via Config\Services::ruleImportService()) |
+ | Payout calculation API | app/Controllers/InsuranceCommissionController.php |
+ | Upload metadata DB | commission_files (CommissionFilesModel) |
+
+
+
+ Routes
+
+ Admin (commission group):
+
+
+ | Route | Handler |
|---|
+
+
+ GET/POST commission/list | commissionFileUploadList |
+ POST commission/upload | upload |
+ GET commission/sample_file | Sample CSV download |
+ GET commission/downloadErrorFile | Annotated error Excel |
+ GET commission/checkSameEntry | Duplicate insurer + month + department check |
+ GET commission/rules/list/(:id) | ruleList — rules editor page |
+ POST commission/rules/save/ | saveRule |
+ POST commission/rules/remove/ | removeRule |
+ GET commission/checkRuleUsage | Whether rule is used on partner policies |
+ GET commission/deleteCommissionData/(:id) | Soft-delete file + mark rules deleted |
+
+
+
+ Runtime API:
+ POST getCommission
+ → InsuranceCommissionController::initiateCommissionCalc
+ → filter: CommissionApiFilter
+
+
+
+
+ Use the template from the upload screen (Download sample file) or copy from
+ public/sample_excel/sample_commission.csv. Dev copies also live under
+ writable/uploads/commission/files/ (e.g. sample_commission.csv,
+ Sample_commission_file-New.xlsx). After a successful import, see the generated JSON under
+ writable/uploads/commission/rules/{MONYYYY}/ (example: NOV2025/1_motor.json).
+
+
+
+ !
+
+ Use the current column layout
+ Some older CSVs in writable/uploads/commission/files/ use legacy headers
+ (Rule Name, Commission Params(TP:OD:PA)). The importer expects the
+ S.No layout below (RuleImportService). Wrong headers fail with
+ “Missing required columns”.
+
+
+
+ Required columns (row 1 headers)
+
+ Header text must match exactly (one row per rule, starting row 2). Empty cells are allowed and simply skip that condition.
+
+
+
+ | Column | Purpose | Example |
|---|
+
+
+ | S.No | Serial (not used in logic) | 1 |
+ | Premium Type | Maps to policy_type | OD, TP, COM |
+ | Vehicle Type | vehicle_type; comma = multiple (IN) | Two Wheeler, Four Wheeler |
+ | Vehicle Sub Type | vehicle_sub_type | Car, PCV |
+ | Make / Model | Vehicle make and model | Honda, i10 |
+ | CC Min / CC Max | Cubic capacity range | 1000, 3000 |
+ | Fuel Type | Comma-separated fuels | Petrol, Diesel |
+ | Vehicle Age Min / Max | Vehicle age range (years) | 1, 5 |
+ | Vehicle Weight Min / Max | Weight range (kg) | 2000, 3000 |
+ | RTO State / RTO Code | geo_rto_state, geo_rto_city | RJ, 41 |
+ | Renewal Type | renewal_type | Online, Cash, Card |
+ | Commission Type | percentage, composite, flat, tiered | percentage |
+ | Commission Value | % or flat amount (required for percentage / flat) | 15 or 500 |
+ | Commission Params (TP) | Composite: % on TP premium | 18 |
+ | Commission Params (OD) | Composite: % on OD premium | 10 |
+ | Commission Params (PA) | Composite: % on PA premium | 0 or empty |
+
+
+
+ Commission types (what to fill)
+
+
+
+ | Type | Fill in sheet | Becomes in JSON |
|---|
+
+
+
+ percentage |
+ Commission Value = e.g. 10 |
+ 10% of premium |
+
+
+ composite |
+ Leave Value empty; set TP / OD / PA param columns (percent each) |
+ Split % on tp_premium, od_premium, pa_premium |
+
+
+ flat |
+ Commission Value = fixed rupee amount e.g. 500 |
+ Fixed payout on premium |
+
+
+
+
+ Sample rows (from project files)
+
+ Template header + rows (public/sample_excel/sample_commission.csv):
+ S.No,Premium Type,Vehicle Type,...,Commission Type,Commission Value,Commission Params (TP),Commission Params (OD),Commission Params (PA)
+1,OD,Car,...,percentage,15,,,
+2,TP,Two Wheeler,...,composite,,18,10,
+3,COM,PCV,...,percentage,25,,,
+4,COM,GCV,...,composite,,,10,
+
+ Example A — composite two-wheeler (from writable/.../rules/NOV2025/1_motor.json):
+
+ - Vehicle Type =
Two Wheeler, CC Min/Max = 100
+ - Commission Type =
composite, TP = 10, OD = 25
+ - Result: 10% on TP premium + 25% on OD premium when policy matches
+
+
+ Example B — percentage four-wheeler:
+
+ - Vehicle Type =
Four Wheeler, CC = 1000, Vehicle Age Min/Max = 5
+ - Commission Type =
percentage, Commission Value = 10
+ - Result: 10% of total premium
+
+
+ Example C — composite TP-only:
+
+ - Premium Type =
TP, Vehicle Type = Four Wheeler
+ - Commission Type =
composite, Commission Params (TP) = 10
+ - Result: 10% on TP premium only
+
+
+ Example D — flat amount:
+
+ - Vehicle Type =
Two Wheeler,Four Wheeler (comma → matches either)
+ - Commission Type =
flat, Commission Value = 500
+ - Result: fixed ₹500 when matched
+
+
+ Tips:
+
+ - Min must not be greater than Max (CC, age, weight) or the row fails validation.
+ - On failure, download the annotated file — errors are written into the sheet.
+ - Supported formats:
.csv, .xlsx, .xls, .ods.
+ - Upload UI departments:
motor, health; import logic is built for motor columns today.
+
+
+ Rule upload
+
+ From commission_file_upload.php the user picks insurer, commission month, department (motor / health), and an Excel/CSV file.
+
+
+ checkSameEntry — if a successful upload already exists for the same trio, SweetAlert offers Overwrite or Append (overwrite=1 or 0 on POST).upload — stores file under writable/uploads/commission/files/, inserts commission_files row (pending).ruleImportService->processUpload() — validates Excel rows; on success returns rules array; on failure returns annotated_file for download.- On success — writes JSON to
rules/{MONYYYY}/{insurer_id}_{department}.json; sets file_status=success and rules_count.
+ - On failure —
file_status=failed; user downloads annotated_{filename} via downloadErrorFile.
+
+
+ Rules editor
+
+
+ For successful uploads, action View Rules opens
+ commission/rules/list/{file_id} (commission_rules_list.php).
+
+
+ - Lists rules from the JSON file for that upload’s insurer, month, and department.
+ saveRule — create or update a rule (conditions + calculation + name) in the JSON via updateCommissionRules().removeRule — soft-delete one rule (is_deleted=true).checkRuleUsage — warns if partner_policy.commission_applied_rule references the rule.- Deleting the whole upload marks all rules with that
file_id as deleted in JSON, then sets commission_files.is_active=0.
+
+
+ Rule JSON shape
+
+ Each rule is roughly:
+ {
+ "id": "rule_…",
+ "name": "Rule name",
+ "department": "motor",
+ "file_id": 12,
+ "is_deleted": false,
+ "conditions": [
+ { "field": "vehicle_type", "operator": "==", "value": "car" }
+ ],
+ "calculation": {
+ "type": "percentage",
+ "value": 10,
+ "on": "premium"
+ }
+}
+
+ Calculation types in InsuranceCommissionController: percentage, composite, fixed. Conditions support ==, !=, >, >=, <, <=, between, in.
+
+ Commission calculation API
+
+ initiateCommissionCalc() expects POST/JSON including at least:
+
+ policy_issue_date — used to pick folder {MON}{YEAR} (e.g. SEP2025)insurer_iddepartment — motor, health, etc.- Fields referenced in rule conditions and calculation bases (e.g.
premium, od_premium)
+
+
+
+
+flowchart TD
+ A["POST getCommission"] --> B{"Required fields present?"}
+ B -->|No| C["Validation error"]
+ B -->|Yes| D["Load rules JSON for month, insurer, department"]
+ D --> E{"File exists?"}
+ E -->|No| F["Rules file not found"]
+ E -->|Yes| G["Find first rule where all conditions match"]
+ G --> H{"Rule found?"}
+ H -->|No| I["No matching rules"]
+ H -->|Yes| J["Apply calculation type"]
+ J --> K["Return payout and rule"]
+
+
+
+ Rules with is_deleted: false are loaded; the first matching rule wins (no priority field yet).
+
+ Developer steps
+
+
+ - Open
/commission/list (logged-in admin).
+ - Download sample file, fill rules for insurer + month + department, upload.
+ - If validation fails, download the annotated error file and fix the sheet.
+ - Use View Rules to tweak conditions or calculation without re-uploading the whole file.
+ - Test payout:
POST getCommission with the same insurer, department, and a policy_issue_date in that commission month.
+
+
+ Common pitfalls
+
+
+ - Month folder must match policy date — upload uses commission month; API uses
policy_issue_date to resolve the same MONYYYY folder.
+ - Append vs overwrite — append merges JSON arrays; overwrite backs up the old file then replaces.
+ - Departments — upload UI currently offers motor and health; API department string must match the JSON filename slug.
+ - HTTP 200 on upload errors — check
status and code in the JSON body, not only HTTP status.
+
diff --git a/app/Views/docs/bds-insurer-statement.php b/app/Views/docs/bds-insurer-statement.php
new file mode 100644
index 00000000..a504be59
--- /dev/null
+++ b/app/Views/docs/bds-insurer-statement.php
@@ -0,0 +1,309 @@
+
+
+
+ BDS Insurer statement lets finance users upload an insurer-provided Excel statement,
+ validate each row against NHance policy transactions (pt_co_share_details +
+ policy_transaction), and persist matched brokerage amounts into
+ co_share_stmt_details. The admin UI is
+ app/Views/insurer_statement_list.php; all server logic lives in
+ PolicyTransactionController under the policy_tranction/statement route group.
+
+
+
+ i
+
+ Auth
+ Statement routes use the authMVC filter. Upload and list are browser AJAX/form calls from an authenticated session, not public API endpoints.
+
+
+
+ Overview
+
+
+
+flowchart LR
+ A[Upload Excel] --> B[validateInsurerStatement]
+ B --> C{All rows OK?}
+ C -->|Yes| D[updateInsurerStatement]
+ C -->|No| E[file_status failed]
+ D --> F[co_share_stmt_details]
+
+
+
+ Row validation logic
+
+
+ validateInsurerStatement() checks that every Excel line maps to a real NHance transaction
+ for the selected insurer branch. Each row is matched on policy number (column B) and
+ endorsement number (column C).
+
+
+
+
+flowchart TD
+ A["Read Excel"] --> B["Fetch NHance rows for policies in the file"]
+ B --> C["Check each non-empty row"]
+ C --> D{"Policy and endorsement found in NHance?"}
+ D -->|"Yes, first time in file"| E["Row valid"]
+ D -->|"Same combo again"| F["Duplicate"]
+ D -->|"Policy not found"| G["Invalid policy"]
+ D -->|"Policy OK, wrong endorsement"| H["Invalid endorsement"]
+ E --> I{"Any bad rows?"}
+ F --> I
+ G --> I
+ H --> I
+ I -->|No| J["Validation passes"]
+ I -->|Yes| K["Validation fails"]
+
+
+
+ In short:
+
+ - Empty rows are ignored.
+ - A row is valid only if that policy + endorsement exists in NHance and appears once in the upload.
+ - If anything fails, the whole file is marked
failed and errors are shown per row in the UI.
+
+
+ Key files and routes
+
+
+
+ | Area | Location |
|---|
+
+
+
+ | UI |
+ app/Views/insurer_statement_list.php — DataTable list, upload modal, validation error modal, invoice modal |
+
+
+ | Controller |
+ app/Controllers/PolicyTransactionController.php |
+
+
+ | Statement header model |
+ app/Models/InsurerStatements.php → insurer_statements |
+
+
+ | Line-item model |
+ app/Models/COShareStmtDetailsModel.php → co_share_stmt_details |
+
+
+ | NHance source rows |
+ app/Models/PTCOShareDetailsModel.php → getNonReconcileredPolicyTransactionByPolicyAndEndorsement() |
+
+
+ | Sample Excel |
+ public/sample_excel/insurer_stament_sample.xlsx |
+
+
+
+
+ Routes (prefix policy_tranction/statement, filter authMVC):
+
+
+
+ | Method | Route | Handler |
|---|
+
+
+ | GET | list | statementList |
+ | POST | upload | uploadInsurerStatement |
+ | GET | downloadSampleInsurerStatement | Sample file download |
+ | GET | downloadInsurerStatement/(:num) | Uploaded file download |
+ | GET | getFileErr/(:any) | Validation failure JSON for modal |
+ | GET | getInsurerStatementMonth | Used to disable already-used statement numbers |
+ | GET | deleteStatement/(:any) | Soft-delete statement + related rows |
+ | GET | getPaymentDetails/(:any) | Invoice modal data |
+ | POST | saveInvoicePaymentDetails | Invoice / payment save |
+
+
+
+ $routes->group('policy_tranction', ['filter' => 'authMVC'], function ($routes) {
+ $routes->group('statement', ['filter' => 'authMVC'], function ($routes) {
+ $routes->get('list', 'PolicyTransactionController::statementList');
+ $routes->post('upload', 'PolicyTransactionController::uploadInsurerStatement');
+ // ...
+ });
+});
+
+ Statement list UI
+
+
+ statementList() loads insurers/branches via
+ insurerBranchModel::getInsurerBranchesWithInsurerNames(), invoice status labels, and
+ statements from the last 180 days (is_active = 1). The view shows:
+
+
+
+ - Insurer branch, statement month, statement serial no, filename (download link), line items count
+ file_status — success or failed (failed rows show an alert icon → error modal)invoice_status — pending / generated / sent / payment received- Actions (non-failed only): invoice status update, delete
+
+
+
+ Upload form fields (#insurer_statement_upload_form): insurer
+ (insurer_id-branch_id), statement month (flatpickr), statement no (1–7), Excel file.
+ Submit is AJAX POST to relative upload. On success the page reloads; on validation failure
+ the API still returns HTTP 200 with dataStatus: false and error_data.
+
+
+ uploadInsurerStatement()
+
+
+ - Validates uploaded file: Excel MIME types, max 16 MB (
max_size[statement,16384] KB).
+ - Moves file to
WRITEPATH . 'uploads/statements/' (see createStatementFolder() for folder creation).
+ - Parses POST:
insurer as {insurer_id}-{branch_id}, statement_month (converted to first-of-month Y-m-d), statement_no → stmt_sno.
+ - Inserts
insurer_statements row via InsurerStatements model.
+ - Calls
validateInsurerStatement(['file_id' => $file_id]).
+ - If validation passes, calls
updateInsurerStatement(['file_id' => $file_id]).
+ - On validation failure: responds with
dataStatus: false, error_data, error_code (HTTP 200).
+ - On success: sets
invoice_status = 'pending' and returns dataStatus: true.
+
+
+ validateInsurerStatement($params)
+
+ Runs immediately after upload (and can be re-run manually in dev with a hard-coded file_id in statementList() comment).
+
+ Steps
+
+
+ - Load
insurer_statements by file_id; fail if missing or physical file absent under writable/uploads/statements/.
+ - Load active sheet via PhpSpreadsheet; drop header row; sanitize with
ExcelSanitizeHelper::sanitizeArrayData().
+ - Collect unique policy numbers from column B (index
1), skipping empty rows via check_row_is_empty_or_null().
+ - Fetch NHance candidates:
+
PTCOShareDetailsModel::getNonReconcileredPolicyTransactionByPolicyAndEndorsement(insurer_id, branch_id, policy_no[])
+ — matches pt.policy_no for completed transactions on that insurer branch.
+ - Build lookup keys
policy_no|endorsement_no (sanitized) for source and Excel rows.
+ - For each non-empty Excel row, match policy + endorsement; track duplicates in
$matched_entry.
+ - On mismatch, append row-wise HTML messages under
error_data[row_index].
+ - Update
insurer_statements.line_items, file_status (success / failed), reason (JSON).
+
+
+ sanitizeStatementLookupValue()
+
+ Private helper trims Unicode spaces and strips zero-width / BOM characters from policy and endorsement values before comparison — avoids “looks equal” mismatches in Excel.
+
+ Validation error codes
+
+
+
+ | error_code | Meaning | UI |
|---|
+
+
+ 0 | DB row missing or physical file not found | Plain message in modal |
+ 1 | Legacy: list of row numbers (old format) | Comma-separated row list |
+ 2 | Row-wise validation (current) | Modal lists each row with policy / endorsement / duplicate messages |
+
+
+
+ Row keys in error_data are the array index from the Excel loop (first data row is typically 1 after header removal), not necessarily the Excel row number on sheet.
+
+ updateInsurerStatement($params)
+
+ Runs only when validation returned status: true.
+
+
+ - Same file load / sanitize path as validation.
+ - Rebuild policy list and source lookup (policy + endorsement → array of
pt_co_share_details rows).
+ - For each Excel row with a matching source entry, compute brokerage totals and variance:
+
+ - BP: amount col
3, brokerage col 5
+ - TP: amount col
4, brokerage col 6
+ - TEP: forced to
0 in current code
+ reward from col 7variance = exp_amt - total_amt (from source exp_amt)
+
+ COShareStmtDetailsModel::insertBatch($data_to_update) — one row per matched Excel line.- Sets
file_status = success, invoice_status = pending, clears/sets reason.
+
+
+ Excel column mapping (0-based index)
+
+ Header row is removed; data columns used by validation/update:
+
+
+
+ | Index | Column | Use |
|---|
+
+
+ 1 | B | Policy number (required for matching) |
+ 2 | C | Endorsement number |
+ 3 | D | Actual BP amount |
+ 4 | E | Actual TP amount |
+ 5 | F | Actual BP brokerage |
+ 6 | G | Actual TP brokerage |
+ 7 | H | Reward |
+
+
+
+ Download the canonical layout from the list page link → downloadSampleInsurerStatement.
+
+ NHance source query
+
+ getNonReconcileredPolicyTransactionByPolicyAndEndorsement() joins:
+
+
+ pt_co_share_details (active) → policy_transaction (active, status = completed)- Filtered by
insurer_id, insurer_branch_id, and pt.policy_no IN (...)
+
+
+
+ Matching is on sanitized policy_no + endorsement_no. The method name suggests
+ “non-reconciled” but the current query does not filter statement_id IS NULL;
+ be aware when re-uploading or debugging duplicate reconciliation.
+
+
+ Invoice status and delete
+
+ After a successful upload, users manage invoice lifecycle from the list (separate from upload/validate):
+
+
+ invoice_status: pending, generated, sent, payment_receivedsaveInvoicePaymentDetails — JSON POST from invoice modaldeleteStatement($id) — soft-deletes co_share_stmt_details, inv_payment_details, and insurer_statements for that id
+
+
+ getInsurerStatementMonth returns successful statements for insurer+month so the UI can
+ disable statement numbers already used (disableStatementNo() in the view).
+
+
+ Developer steps
+
+
+ - Ensure
writable/uploads/statements/ exists and is writable (or call createStatementFolder() once).
+ - Open
policy_tranction/statement/list in a logged-in session.
+ - Use sample Excel; pick insurer branch and month; choose an unused statement number (1–7 per insurer/month).
+ - Confirm policy/endorsement exist on a completed BDS transaction for that insurer branch.
+ - On failure, open the alert icon → modal calls
getFileErr/{id} and renders reason JSON.
+ - To debug validation only: temporarily uncomment the
validateInsurerStatement / updateInsurerStatement one-liner in statementList() with a known file_id.
+
+
+ Common pitfalls
+
+
+ - Hidden Excel characters — policy/endorsement must pass
sanitizeStatementLookupValue(); re-type values if NHance shows a match but upload fails.
+ - Duplicate policy + endorsement in the same file →
error_code 2, duplicate message on second row.
+ - Validation failed but file on disk —
insurer_statements row remains; user sees failed status; re-upload needs a new statement or delete the failed row.
+ - Statement number reuse — only successful uploads for that insurer/month block numbers in the dropdown via
getInsurerStatementMonth.
+ - Upload response HTTP 200 on error — front-end checks
dataStatus, not status code alone.
+ - Legacy handlers —
validateInsurerStatementOld, updateInsurerStatementOLD remain in the controller; production path is the non-Old methods documented here.
+
+
+
+
+
+ - BDS reports:
policy_tranction/report/list, variance, finance, outstanding lists
+ - Daily BDS cron mail:
cronDailyBDSReport (separate from statement upload)
+
diff --git a/app/Views/docs/correction.php b/app/Views/docs/correction.php
new file mode 100644
index 00000000..d8d68029
--- /dev/null
+++ b/app/Views/docs/correction.php
@@ -0,0 +1,265 @@
+
+
+
+ Correction updates existing member data on an active policy via Excel upload
+ (files.action = correction). The final step creates pending correction endorsements
+ on the employees table — data is not updated until those endorsements are applied downstream.
+
+
+
+ Processing is in EmployeeServiceController::employeesCorrectionProcess, queued after the same
+ format and data validation steps used for inception and deletion.
+
+
+ Overview
+
+
+
+flowchart LR
+ A["Upload Excel action correction"] --> B["excelFileFormatValidation"]
+ B --> C["excelFileDataValidation"]
+ C --> D["employeesCorrectionProcess job"]
+ D --> E["emp_endorsement pending on employees"]
+ B -->|errors| F["files.status failed"]
+ C -->|errors| F
+ D -->|loop done| G["files.status success"]
+
+
+
+ In short:
+
+ - Step 1 — Format: 8 columns (A–H); field must be one of four allowed names; dates
d-M-Y.
+ - Step 2 — Data: Member must exist (emp code + name + active policy); code 10 if not found.
+ - Step 3 — Correction: One pending endorsement per row per field (skips duplicate pending corrections).
+ - Each Excel row = one field change for one member (not a full-family operation).
+
+
+ Key files and routes
+
+
+
+ | Area | Location |
|---|
+
+
+
+ | UI |
+ app/Views/employee_upload.php — action Correction |
+
+
+ | Upload |
+ EmployeeController::employeesUplodWithEvents |
+
+
+ | Validation |
+ excelFileFormatValidation, excelFileDataValidation |
+
+
+ | Correction process |
+ EmployeeServiceController::employeesCorrectionProcess |
+
+
+ | Column config API |
+ getCorrectionExcelColumns() — used when building correction Excel programmatically |
+
+
+ | Job |
+ employeesCorrectionProcess in JobWorker.php |
+
+
+ | Endorsements |
+ EmpEndorsementModel — actions = c, table_name = employees, status = pending |
+
+
+
+
+ Routes (group /employee, authMVC):
+
+ GET /employee/upload — upload screenPOST /employee/upload — upload-action-type=correctionGET /employee/excel_error/{file_id} — validation errors
+
+
+ i
+
+ files.policy_id is the client policy id. Lookup requires active
+ employees + employee_polices on that policy and branch.
+
+
+
+ Sync vs background jobs
+
+
+
+ | Step | < 1 MB | ≥ 1 MB |
|---|
+
+
+ | Format validation | Inline on upload | Job excelFileFormatValidation |
+ | Data validation | Job excelFileDataValidation | Same |
+ | Correction process | Job employeesCorrectionProcess | Same |
+
+
+
+
+
+
+ - Uses
$correction_excel_columns — 8 columns (A–H).
+ - Action code
C for mandatory rules on correction-specific columns.
+ - Field (column D): only
name, dob, relationship, email_corporate.
+ - Date of Correction (F):
d-M-Y.
+ - Change event (G) and Value (E) are mandatory.
+
+
+
+
+
+
+ | Code | Meaning |
|---|
+
+
+ | 1 | Mandatory missing |
+ | 2 | Wrong format |
+ | 3 | Not in allowed list (e.g. invalid Field value) |
+ | 4 | Custom validation failed |
+ | 5 | File / policy problem |
+ | 6 | Column headers wrong |
+
+
+
+ Step 2: excelFileDataValidation
+
+ Rows grouped by EMP ID; for correction the critical check is name_and_empid_check_in_db:
+
+ - Each row must match an active employee on the uploaded policy (emp code + name).
+ - Not found → error code 10 (“Record Not found”).
+
+
+ On success → queues employeesCorrectionProcess (with optional batch_file_id for TPA multi-file flows).
+
+ Step 3: employeesCorrectionProcess
+
+
+
+flowchart TD
+ A["Read each Excel row"] --> B["Match emp_code plus name on active policy"]
+ B --> C{"Pending correction for same field?"}
+ C -->|Yes| D["Skip row"]
+ C -->|No| E["Insert emp_endorsement actions c"]
+ E --> F["old_value from DB new_value from Excel"]
+
+
+
+ Per row:
+
+ field_name ← column D (name, dob, relationship, email_corporate)new_value ← column E; if field is dob, converted from d-M-Y to Y-m-ddate_of_correction ← column F (converted to Y-m-d)remarks ← column H (optional)old_value ← current value from employees.{field_name}
+
+
+ Skips insert when a pending correction endorsement already exists for the same
+ emp_code, name, and field_name
+ (actions = c, endorsement_id IS NULL, status != truncated).
+
+
+
+ Sets files.status = success when the loop completes and sends a success pull notification.
+ Rows with no DB match are not endorsed (no row-level failure on the file record).
+
+
+
+ TPA batch: If batch_file_id is set, also queues
+ updateEmployeeDataFromTpa, reconTpaApiDataWithEmployeepolicies, and
+ initializeDeletionProcessForTpaApiData.
+
+
+ Correction Excel columns
+
+
+
+ | Col | Header | Required | Notes |
|---|
+
+
+ | A | S.No | Yes | |
+ | B | EMP ID | Yes | |
+ | C | NAME OF EMP/DEP | Yes | Must match DB before correction |
+ | D | Field | Yes | name, dob, relationship, email_corporate |
+ | E | Value | Yes | New value; DOB as d-M-Y |
+ | F | Date of Correction | Yes | d-M-Y |
+ | G | Change event | Yes | e.g. correction |
+ | H | Remarks | No | Stored on endorsement |
+
+
+
+ Row layout examples
+
+ Fix DOB — one row, one field:
+
+
+
+ | EMP ID | NAME | Field | Value | Date of Correction | Change event | Remarks |
|---|
+
+
+
+ | EMP001 |
+ Raj Kumar |
+ dob |
+ 15-Jan-1985 |
+ 19-May-2026 |
+ correction |
+ Typo in upload |
+
+
+
+
+ Multiple fixes — use separate rows (same or different members):
+
+
+
+ | EMP ID | NAME | Field | Value |
|---|
+
+
+ | EMP001 | Raj Kumar | email_corporate | raj.kumar@company.com |
+ | EMP001 | Priya Kumar | relationship | Spouse |
+
+
+
+ Developer steps
+
+
+ - Upload with
upload-action-type=correction; note file_id.
+ - On validation failure, check
/employee/excel_error/{file_id} for code 10.
+ - After success, query
emp_endorsement where file_id = upload id, actions = 'c', status = 'pending'.
+ - Compare
field_name, old_value, new_value per row to the Excel.
+ - To generate correction Excel in code, use
getCorrectionExcelColumns() for header layout.
+
+
+ Common pitfalls
+
+
+ - Name must match DB — correction identifies the member by current
emp_code + name; rename via a name field row uses the old name in column C.
+ - Only four fields — mobile, SI, band, etc. are not supported in this upload path.
+ - Duplicate pending correction — second upload for the same field is skipped until the first endorsement is processed or truncated.
+ - File success vs rows —
files.status = success does not mean every row created an endorsement.
+ - Not live update —
employees columns change only after endorsement approval/application.
+
+
+
+ Related:
+ Inception,
+ Deletion.
+
diff --git a/app/Views/docs/deletion.php b/app/Views/docs/deletion.php
new file mode 100644
index 00000000..aff0fdba
--- /dev/null
+++ b/app/Views/docs/deletion.php
@@ -0,0 +1,259 @@
+
+
+
+ Deletion removes active members from a client policy via Excel upload
+ (files.action = deletion). Unlike inception, the final step does not delete rows immediately —
+ it creates pending endorsement records on employee_polices for approval/processing later.
+
+
+
+ Core processing lives in EmployeeServiceController::employeeDisembark.
+ EmployeeController::initializeDeletionProcessForTpaApiData is a separate TPA-reconcile path that
+ builds a deletion Excel file and calls the same disembark function.
+
+
+ Overview
+
+
+
+flowchart LR
+ A["Upload Excel action deletion"] --> B["excelFileFormatValidation"]
+ B --> C["excelFileDataValidation"]
+ C --> D["employeeDisembark job"]
+ D --> E["emp_endorsement pending rows"]
+ B -->|errors| F["files.status failed"]
+ C -->|errors| F
+ D -->|always| G["files.status success"]
+
+
+
+ In short:
+
+ - Step 1 — Format: 7 columns (A–G), mandatory exit fields per action code
D.
+ - Step 2 — Data: Member must exist in DB (emp code + name + active policy); code 10 if not found.
+ - Step 3 — Disembark: Writes pending deletion endorsements; Self row removes whole family, dependent row removes one member.
+ - Files < 1 MB run format validation inline; data validation and disembark are always queued.
+
+
+ Key files and routes
+
+
+
+ | Area | Location |
|---|
+
+
+
+ | UI |
+ app/Views/employee_upload.php — action Deletion |
+
+
+ | Upload |
+ EmployeeController::employeesUplodWithEvents |
+
+
+ | Validation |
+ EmployeeServiceController::excelFileFormatValidation, excelFileDataValidation |
+
+
+ | Deletion process |
+ EmployeeServiceController::employeeDisembark |
+
+
+ | TPA auto-deletion |
+ EmployeeController::initializeDeletionProcessForTpaApiData |
+
+
+ | Job |
+ employeeDisembark in JobWorker.php |
+
+
+ | Endorsements |
+ EmpEndorsementModel → emp_endorsement (actions = d, status = pending) |
+
+
+
+
+ Routes (group /employee, authMVC):
+
+ GET /employee/upload — upload screenPOST /employee/upload — upload-action-type=deletionGET /employee/excel_error/{file_id} — read files.reason after validation failure
+
+
+ i
+
+ files.policy_id is the client policy id. Member lookup joins
+ employees + employee_polices on that policy and branch.
+
+
+
+ Sync vs background jobs
+
+
+
+ | Step | < 1 MB | ≥ 1 MB |
|---|
+
+
+ | Format validation | Inline on upload | Job excelFileFormatValidation |
+ | Data validation | Job excelFileDataValidation | Same |
+ | Disembark | Job employeeDisembark | Same |
+
+
+
+
+
+
+ - Uses
$deletion_excel_columns — 7 columns (A–G).
+ - Action code
D drives mandatory fields: Change event, Date of exit, Reason for exit, Claim status.
+ - Date of exit format:
d-M-Y.
+ - Claim status allowed:
0 or 1.
+
+
+
+
+
+
+ | Code | Meaning |
|---|
+
+
+ | 1 | Mandatory missing |
+ | 2 | Wrong format |
+ | 3 | Not in allowed list |
+ | 4 | Custom validation failed |
+ | 5 | File / policy problem |
+ | 6 | Column headers wrong |
+
+
+
+ Step 2: excelFileDataValidation
+
+ Rows are grouped by EMP ID. For deletion, the main check is name_and_empid_check_in_db:
+
+ - Each row must match an active employee + active
employee_polices row on the uploaded policy/branch.
+ - If not found → error code 10 (“Record Not found”) on that Excel row.
+
+
+ On success → queues employeeDisembark (not employeesOnboardPreprocess).
+
+ Step 3: employeeDisembark
+
+ Loads the Excel again and processes each non-empty row.
+
+
+
+flowchart TD
+ A["Match emp_code plus name on active policy"] --> B{"Found?"}
+ B -->|No| C["Log error skip row"]
+ B -->|Yes| D{"Pending deletion endorsement?"}
+ D -->|Yes| E["Log skip row"]
+ D -->|No| F{"Relationship Self?"}
+ F -->|No| G["Endorse this member only"]
+ F -->|Yes| H["Endorse all active family members"]
+ G --> I["emp_endorsement pending"]
+ H --> I
+
+
+
+ Per matched member, four pending endorsement rows are inserted on employee_polices:
+
+ date_of_exit ← Excel column E (converted to Y-m-d)reason_for_exit ← column Fstatus → inactiveclaim_status ← column G
+
+
+ Returns an array of processed employee.id values. Sets files.status = success when the loop finishes
+ (even if some rows were skipped — check logs for “not found” or “existing endorsement pending”).
+
+
+ TPA auto-deletion (EmployeeController)
+
+ initializeDeletionProcessForTpaApiData($file_id):
+
+ - Reads TPA reconcile file context (
tpa_api_data, action_flag_status = D).
+ - Builds candidate members and writes
writable/uploads/excel/tpa_auto_deletion_{fileId}_{timestamp}.xls.
+ - Inserts a new
files row with action = deletion.
+ - Calls
employeeDisembark(['file_id' => $newFileId]) synchronously.
+ - Exports endorsement data for TPA via
getDeletionEmployeeDataForExportExcel.
+
+
+ Deletion Excel columns
+
+
+
+ | Col | Header | Required | Notes |
|---|
+
+
+ | A | S.No | Yes | |
+ | B | EMP ID | Yes | Employee / family code |
+ | C | NAME OF EMP/DEP | Yes | Must match DB name exactly |
+ | D | Change event | Yes | e.g. deletion |
+ | E | Date of exit | Yes | d-M-Y |
+ | F | Reason for exit | Yes | |
+ | G | Claim status | Yes | 0 or 1 |
+
+
+
+ Row layout examples
+
+ Delete one dependent — only that name appears; Self row is not required in the file.
+
+
+
+ | Row | EMP ID | NAME | Change event | Date of exit | Reason | Claim |
|---|
+
+
+ | 2 | EMP001 | Arjun Kumar | deletion | 19-May-2026 | Resigned | 0 |
+
+
+ Result: endorsements for Arjun only (relationship ≠ Self).
+
+ Delete entire family — list the Self row; disembark loads all active family members for that EMP ID.
+
+
+
+ | Row | EMP ID | NAME | Change event | Date of exit | Reason | Claim |
|---|
+
+
+ | 2 | EMP001 | Raj Kumar | deletion | 19-May-2026 | Resigned | 0 |
+
+
+ Result: pending endorsements for Self + all active dependents on that policy (same exit date/reason/claim from the row).
+
+ Developer steps
+
+
+ - Upload via
/employee/upload with action deletion; note file_id.
+ - If validation fails, use
GET /employee/excel_error/{file_id} — look for code 10 (member not in DB).
+ - After success, query
emp_endorsement where file_id = upload id, actions = 'd', status = 'pending'.
+ - If rows were skipped, search logs for
not found or Existing endorsement pending.
+ - TPA path: trace
initializeDeletionProcessForTpaApiData and the generated tpa_auto_deletion_*.xls file.
+
+
+ Common pitfalls
+
+
+ - Name mismatch — Excel name must match
employees.name exactly (case/spacing).
+ - Not active — only
emp_status = active and employee_polices.status = active match.
+ - Duplicate pending deletion — row skipped if a pending deletion endorsement already exists for that policy row.
+ - Self vs dependent — wrong relationship in the row changes scope (one member vs whole family).
+ - File always success after disembark —
files.status does not reflect per-row skips; use endorsements table + logs.
+ - Not immediate delete — members stay active until endorsements are approved/applied downstream.
+
+
+ Related: Inception (onboard pipeline uses the same upload screen and first two validation steps).
diff --git a/app/Views/docs/docs_header.php b/app/Views/docs/docs_header.php
index 2b8a8e6e..949ee16e 100644
--- a/app/Views/docs/docs_header.php
+++ b/app/Views/docs/docs_header.php
@@ -39,6 +39,7 @@ $base = base_url();
/* ─── TOKENS ─────────────────────────────── */
:root {
--sidebar-w : 260px;
+ --toc-w : 200px;
--topbar-h : 56px;
--bg : #ffffff;
--bg2 : #f7f8fa;
@@ -143,6 +144,8 @@ $base = base_url();
/* ─── LAYOUT WRAPPER ─────────────────────── */
.docs-layout {
display : flex;
+ width : 100%;
+ align-items: flex-start;
margin-top: var(--topbar-h);
min-height: calc(100vh - var(--topbar-h));
}
@@ -208,6 +211,15 @@ $base = base_url();
.callout.success { background: #f0fdf4; border-color: #4ade80; color: #15803d; }
/* ─── TABLES ─────────────────────────────── */
+ .docs-table-wrap {
+ overflow-x: auto;
+ -webkit-overflow-scrolling: touch;
+ margin: 20px 0;
+ border: 1px solid var(--border);
+ border-radius: 8px;
+ }
+ .docs-table-wrap table { margin: 0; min-width: 640px; }
+ .docs-table-wrap--fluid table { min-width: 0; width: 100%; }
table { width: 100%; border-collapse: collapse; margin: 20px 0; font-size: 13.5px; }
th {
background : var(--bg2);
diff --git a/app/Views/docs/docs_main_open.php b/app/Views/docs/docs_main_open.php
index e964f522..e9a75656 100644
--- a/app/Views/docs/docs_main_open.php
+++ b/app/Views/docs/docs_main_open.php
@@ -27,10 +27,11 @@ $toc = $toc ?? [];
L["iterate in DB order"]
- L --> K{"rack_rate_name changed"}
- K -->|yes| B["open new bucket"]
- K -->|no| U["same bucket"]
- B --> P["append row to slab_rates array"]
- U --> P
- P --> G["store grid_master from row"]
-
-
-
-
- i
-
- When maintaining this helper, inspect the implementation for duplicate pushes on the first row of a new rack name;
- downstream code tolerates duplicate slab rows but it can confuse debugging of premium matches.
-
- get_familiy_composition
@@ -321,13 +294,122 @@ flowchart LR
(already grouped to one employee). Keys align with the JSON used in rack configuration (additional_relationship), except
either-parents-pil and elders_count which are stripped before comparison.
+
+ This function mainly:
+
+ - Reads all family members
+ - Normalizes relationship names
+ - Builds a summarized family composition object
+ - Maintains counts for:
+
+ - self
+ - spouse
+ - children
+ - parents
+ - parents-in-law
+
+
+
+
flowchart TD
- A["single pass over family_data rows"] --> B["slugify column 5 per row"]
- B --> C["bump self spouse childrens parents parents-in-law counters"]
- C --> D["return family_composition map"]
+
+ START([Start get_familiy_composition])
+
+ START --> INIT["Initialize family_composition array and slug service"]
+
+ INIT --> LOOP_MEMBERS{"Loop each family member"}
+
+ LOOP_MEMBERS --> GET_REL["Read relationship from row[5]"]
+
+ GET_REL --> SLUGIFY["Slugify relationship"]
+
+ %% SELF
+
+ SLUGIFY --> CHECK_SELF{"relationship == self"}
+
+ CHECK_SELF -->|Yes| SET_SELF_ONE["Set self = 1"]
+
+ CHECK_SELF -->|No| CHECK_SELF_EXISTS{"self key exists?"}
+
+ CHECK_SELF_EXISTS -->|No| SET_SELF_ZERO["Set self = 0"]
+
+ CHECK_SELF_EXISTS -->|Yes| CHECK_SPOUSE
+
+ SET_SELF_ONE --> CHECK_SPOUSE
+ SET_SELF_ZERO --> CHECK_SPOUSE
+
+ %% SPOUSE
+
+ CHECK_SPOUSE{"relationship == spouse"}
+
+ CHECK_SPOUSE -->|Yes| SET_SPOUSE_ONE["Set spouse = 1"]
+
+ CHECK_SPOUSE -->|No| CHECK_SPOUSE_EXISTS{"spouse key exists?"}
+
+ CHECK_SPOUSE_EXISTS -->|No| SET_SPOUSE_ZERO["Set spouse = 0"]
+
+ CHECK_SPOUSE_EXISTS -->|Yes| CHECK_CHILDREN
+
+ SET_SPOUSE_ONE --> CHECK_CHILDREN
+ SET_SPOUSE_ZERO --> CHECK_CHILDREN
+
+ %% CHILDREN
+
+ CHECK_CHILDREN{"relationship == son OR daughter"}
+
+ CHECK_CHILDREN -->|Yes| INC_CHILDREN["Increment childrens count"]
+
+ CHECK_CHILDREN -->|No| CHECK_CHILDREN_EXISTS{"childrens key exists?"}
+
+ CHECK_CHILDREN_EXISTS -->|No| SET_CHILDREN_ZERO["Set childrens = 0"]
+
+ CHECK_CHILDREN_EXISTS -->|Yes| CHECK_PARENTS
+
+ INC_CHILDREN --> CHECK_PARENTS
+ SET_CHILDREN_ZERO --> CHECK_PARENTS
+
+ %% PARENTS
+
+ CHECK_PARENTS{"relationship == father OR mother"}
+
+ CHECK_PARENTS -->|Yes| INC_PARENTS["Increment parents count"]
+
+ CHECK_PARENTS -->|No| CHECK_PARENTS_EXISTS{"parents key exists?"}
+
+ CHECK_PARENTS_EXISTS -->|No| SET_PARENTS_ZERO["Set parents = 0"]
+
+ CHECK_PARENTS_EXISTS -->|Yes| CHECK_INLAWS
+
+ INC_PARENTS --> CHECK_INLAWS
+ SET_PARENTS_ZERO --> CHECK_INLAWS
+
+ %% PARENTS IN LAW
+
+ CHECK_INLAWS{"relationship == father-in-law OR mother-in-law"}
+
+ CHECK_INLAWS -->|Yes| INC_INLAWS["Increment parents-in-law count"]
+
+ CHECK_INLAWS -->|No| CHECK_INLAW_EXISTS{"parents-in-law key exists?"}
+
+ CHECK_INLAW_EXISTS -->|No| SET_INLAW_ZERO["Set parents-in-law = 0"]
+
+ CHECK_INLAW_EXISTS -->|Yes| NEXT_MEMBER
+
+ INC_INLAWS --> NEXT_MEMBER
+ SET_INLAW_ZERO --> NEXT_MEMBER
+
+ %% LOOP
+
+ NEXT_MEMBER --> MORE_MEMBERS{"More family members?"}
+
+ MORE_MEMBERS -->|Yes| LOOP_MEMBERS
+
+ MORE_MEMBERS -->|No| RETURN_RESULT
+
+ RETURN_RESULT(["Return family_composition"])
@@ -348,12 +430,87 @@ flowchart TD
flowchart TD
- J["decode additional_relationship JSON"] --> U["strip either-parents-pil and elders_count"]
- U --> E{"non-NA rules exist"}
- E -->|no| F["rack not applicable"]
- E -->|yes| K["sequential AND each non-NA key"]
- K -->|incoming matches value or any| Y["rack applicable plus relationship tokens"]
- K -->|missing key or mismatch| X["rack not applicable"]
+
+ START([Start compare_incoming_family_slab_with_configured_slab])
+
+ START --> INIT_MAP["Initialize relationship mapping"]
+
+ INIT_MAP --> INIT_RESULT["Initialize result
+ is_applicable = false
+ applicable_members = []"]
+
+ INIT_RESULT --> READ_CONFIG["Read configured family composition from slab"]
+
+ READ_CONFIG --> REMOVE_KEYS["Remove ignored keys
+ either-parents-pil
+ elders_count"]
+
+ REMOVE_KEYS --> CHECK_CONFIG{"Configured composition has values?"}
+
+ %% EMPTY CONFIGURATION
+
+ CHECK_CONFIG -->|No| RESET_RESULT["Set result as not applicable"]
+
+ RESET_RESULT --> RETURN_RESULT
+
+ %% LOOP START
+
+ CHECK_CONFIG -->|Yes| LOOP_CONFIG{"Loop configured relationships"}
+
+ %% CHECK NA
+
+ LOOP_CONFIG --> CHECK_NA{"Value != NA ?"}
+
+ CHECK_NA -->|No| NEXT_RELATION
+
+ %% CHECK KEY EXISTS
+
+ CHECK_NA -->|Yes| CHECK_KEY_EXISTS{"Relationship exists in incoming composition?"}
+
+ CHECK_KEY_EXISTS -->|No| INVALID_RESULT_1["Set:
+ is_applicable = false
+ applicable_members = []"]
+
+ INVALID_RESULT_1 --> BREAK_LOOP
+
+ %% VALUE COMPARISON
+
+ CHECK_KEY_EXISTS -->|Yes| CHECK_MATCH{
+ Incoming count == configured count
+ OR
+ configured value == any
+ }
+
+ %% MATCH FOUND
+
+ CHECK_MATCH -->|Yes| SET_APPLICABLE["Set is_applicable = true"]
+
+ SET_APPLICABLE --> MERGE_MEMBERS["Merge mapped relationships into applicable_members"]
+
+ MERGE_MEMBERS --> NEXT_RELATION
+
+ %% MATCH FAILED
+
+ CHECK_MATCH -->|No| INVALID_RESULT_2["Set:
+ is_applicable = false
+ applicable_members = []"]
+
+ INVALID_RESULT_2 --> BREAK_LOOP
+
+ %% LOOP CONTROL
+
+ NEXT_RELATION --> MORE_RELATIONS{"More relationships?"}
+
+ MORE_RELATIONS -->|Yes| LOOP_CONFIG
+
+ MORE_RELATIONS -->|No| RETURN_RESULT
+
+ BREAK_LOOP --> RETURN_RESULT
+
+ %% RETURN
+
+ RETURN_RESULT(["Return result array"])
+
@@ -378,13 +535,60 @@ flowchart TD
flowchart TD
- A["applicable_members from compare"] --> B["scan family_data by index"]
- B --> C{"relationship slug in list"}
- C -->|yes| D["record index and age from DOB"]
- C -->|no| B
- D --> B
- B -->|done| E["max_count equals number of indexes"]
- E --> F["walk indexes in order first gets acting_self true remainder false"]
+
+ START([Start get_applicable_familiy_members])
+
+ START --> INIT["Initialize:
+ index = []
+ max_age = []
+ max_count = 0"]
+
+ INIT --> INIT_SLUG["Initialize slug service"]
+
+ INIT_SLUG --> LOOP_MEMBERS{"Loop each family member"}
+
+ %% READ RELATIONSHIP
+
+ LOOP_MEMBERS --> READ_REL["Read relationship from family_member[5]"]
+
+ READ_REL --> SLUGIFY["Slugify relationship"]
+
+ %% CHECK APPLICABLE
+
+ SLUGIFY --> CHECK_APPLICABLE{
+ Relationship exists in applicable_members?
+ }
+
+ %% MATCH FOUND
+
+ CHECK_APPLICABLE -->|Yes| STORE_INDEX["Add member index into result.index"]
+
+ STORE_INDEX --> CALCULATE_AGE["Calculate member age from DOB"]
+
+ CALCULATE_AGE --> STORE_AGE["Add age into result.max_age"]
+
+ STORE_AGE --> NEXT_MEMBER
+
+ %% NO MATCH
+
+ CHECK_APPLICABLE -->|No| NEXT_MEMBER
+
+ %% LOOP CONTROL
+
+ NEXT_MEMBER --> MORE_MEMBERS{"More family members?"}
+
+ MORE_MEMBERS -->|Yes| LOOP_MEMBERS
+
+ %% FINAL COUNT
+
+ MORE_MEMBERS -->|No| CALCULATE_COUNT["Set max_count =
+ count(result.index)"]
+
+ CALCULATE_COUNT --> RETURN_RESULT
+
+ %% RETURN
+
+ RETURN_RESULT(["Return result array"])
diff --git a/app/Views/docs/inception.php b/app/Views/docs/inception.php
new file mode 100644
index 00000000..ad406a78
--- /dev/null
+++ b/app/Views/docs/inception.php
@@ -0,0 +1,389 @@
+
+
+
+ Inception here means onboarding employees and dependents from an Excel upload
+ (files.action = inception or related actions like missed_inception,
+ addition, dependent_addition). The same three-step pipeline runs for those
+ actions; this page focuses on the inception path.
+
+
+
+ Manual policy inception (form UI under policy_tranction/inception) is a separate flow
+ in PolicyTransactionController — not covered by these three functions.
+
+
+Overview
+
+
+
+flowchart LR
+ A["Upload Excel on employee upload"] --> B["excelFileFormatValidation"]
+ B --> C["excelFileDataValidation"]
+ C --> D["employeesOnboardPreprocess"]
+ D --> E["employeesOnboardProcess plus policy_transaction"]
+ B -->|errors| F["files.status failed"]
+ C -->|errors| F
+ D -->|no families inserted| F
+ D -->|OK| G["files.status success"]
+
+ In short:
+
+ - Step 1 — Format: Headers, column count/order, per-cell type and mandatory rules.
+ - Step 2 — Data: Family-level checks (Self row, duplicates, policy terms, DB conflicts).
+ - Step 3 — Preprocess: Premium via rack rates, then insert employees and inception policy transaction.
+ - Large files (> 1 MB) run steps 1–3 as background jobs via
JobWorker.
+
+
+Key files and routes
+
+
+
+ | Area | Location |
|---|
+
+
+
+ | UI |
+ app/Views/employee_upload.php — client, branch, policy, action Inception, file upload |
+
+
+ | Upload handler |
+ EmployeeController::employeesUplodWithEvents |
+
+
+ | Pipeline logic |
+ EmployeeServiceController — the three functions on this page |
+
+
+ | Job dispatch |
+ app/Controllers/JobWorker.php — maps job names to EmployeeServiceController |
+
+
+ | Column / Excel helpers |
+ app/Helpers/excel_util_helper.php — check_columns_name, custom validators |
+
+
+ | Upload record |
+ files table via FileModel — status, action, reason |
+
+
+ | Premium |
+ EB rack rate calculation — calculate_premium_new, employeesOnboardProcess |
+
+
+
+
+Routes (group /employee, filter authMVC):
+
+ GET /employee/upload — upload screenPOST /employee/upload — upload + start validation (upload-action-type=inception)GET /employee/excel_error/{file_id} — returns files.reason JSON for the error modal
+
+
+ REST upload (mobile/HR): POST employeeRest/employeeUpload — same pipeline via
+ EmployeeRestController.
+
+
+
+ i
+
+ files.policy_id stores client policy id (client_policies.id),
+ not the insurer policy master id. Slab/rack lookups use this id with client_id.
+
+ Sync vs background jobs
+
+
+
+ | File size | Step 1 | Steps 2–3 |
|---|
+
+
+
+ | < 1 MB |
+ excelFileFormatValidation runs inline in the upload request |
+ Always queued: excelFileDataValidation → employeesOnboardPreprocess |
+
+
+ | ≥ 1 MB |
+ Job excelFileFormatValidation |
+ Same job chain after format passes |
+
+
+
+
+
+ After upload the UI usually shows files.status = inprogress until jobs finish.
+ Poll notifications or refresh the upload list; use /employee/excel_error/{id} when status is failed.
+
+
+Entry points
+
+Job chain for inception (and missed_inception / addition / dependent_addition):
+excelFileFormatValidation → excelFileDataValidation → employeesOnboardPreprocess
+
+
+
+Runs on the uploaded sheet before any DB business rules.
+
+
+ - Loads file from
writable/uploads/excel/{file_name}.
+ - Uses
$inception_excel_columns when action is inception (same column set for addition / dependent_addition / missed_inception).
+ - Checks policy has terms and slab rates configured — otherwise fails early.
+ - Validates each data row: mandatory (by action code
I), date/mobile formats, allowed lists, custom helpers (DOB, relationship, SI, mobile duplicate, etc.).
+ - Stops at first empty row (treated as end of data).
+
+
+
+
+
+
+ | Code | Meaning |
|---|
+
+
+ | 1 | Mandatory value missing |
+ | 2 | Wrong format (e.g. date, mobile) |
+ | 3 | Value not in allowed list |
+ | 4 | Custom validation failed (DOB, relationship, SI, etc.) |
+ | 5 | File / policy / slab configuration problem |
+ | 6 | Column headers wrong or out of order |
+
+
+
+On failure: files.status = failed, reason JSON with row/column errors; user notification via pull notification.
+
+Lead-policy branch: If inception file is for a policy created from leads (policy_entry_from == 3 and is_from_lead set), format validation queues compareMemberDataAndInceptionData instead of going straight to data validation.
+
+files.reason shape (debugging)
+
+Stored as JSON string on files.reason. Typical failure payload:
+{
+ "error_type": 1,
+ "error_summary": { "4": 2, "1": 1 },
+ "error_data": {
+ "3": {
+ "dob": { "error": ["Invalid date format"], "value": "01/01/1990" }
+ }
+ }
+}
+
+ error_type — 1 = format step, 2 = data steperror_summary — counts per error code (after aggregation)error_data — keyed by Excel row number (1-based, header is row 1)
+
+Step 2: excelFileDataValidation
+
+Runs after format passes. Groups rows by EMP ID (family) and applies business rules.
+
+
+
+flowchart TD
+ A["Group rows by emp_id"] --> B{"Self in family?"}
+ B -->|No| C["Error: Self not found"]
+ B -->|Yes| D{"Duplicate name in family?"}
+ D -->|Yes| E["Error: Twofold name"]
+ D -->|No| F{"Emp code already in DB?"}
+ F -->|Yes| G["Error: duplicate emp code"]
+ F -->|No| H{"Dependents match policy terms?"}
+ H -->|No| I["Dependent conflict errors"]
+ H -->|Yes| J["Row OK for this family"]
+
+ Typical inception checks:
+
+ - Self row required (unless GMC parents policy allows otherwise).
+ - No duplicate names within the same family in the file.
+ - Employee code must not already exist for inception / addition / enrollment.
+ - Dependent rules vs
policy_terms (family composition, LGBTQ flag, etc.).
+ - Name + emp id consistency vs database (
name_and_empid_check_in_db).
+
+
+On success for inception: queues job employeesOnboardPreprocess. Other actions queue different jobs (deletion, correction, etc.).
+
+Common data-validation error codes
+
+
+
+ | Code | Meaning |
|---|
+
+
+ | 7 | Duplicate name within same family in the Excel file |
+ | 9 | Record already exists in DB (inception / addition) |
+ | 10 | Record not found (used on deletion flows) |
+ | 14 | Self row missing in family |
+ | 26 | Duplicate employee code in file or DB |
+
+
+
+Step 3: employeesOnboardPreprocess
+
+Calculates premium and writes members to the database.
+
+
+ - Reload Excel; group by
emp_id.
+ - For each family:
calculate_premium_new() using policy terms + slab rates + rack config.
+ employeesOnboardProcess() — insert/update employees, employee_polices, create policy_transaction (inception).- If at least one family inserted →
files.status = success; else failed with rack-rate message.
+
+
+
+ Optional second path: client_policy_id without file_id — converts enrolled DB members
+ to inception (enrollment → inception), not from Excel.
+
+
+
+ TPA batch: When batch_file_id is present on the job payload, success also queues
+ updateEmployeeDataFromTpa, reconTpaApiDataWithEmployeepolicies, and
+ initializeDeletionProcessForTpaApiData (multi-file TPA reconcile flow).
+
+
+Inception Excel columns
+
+
+ Defined in EmployeeServiceController::$inception_excel_columns.
+ Header row must match exactly — 19 columns (A–S), row 1 only.
+ Dates use format d-M-Y (e.g. 4-Apr-1990).
+ One Self row per EMP ID; other rows are dependents.
+
+
+
+
+ | Col | Header | Required (inception) | Notes |
|---|
+
+
+ | A | S.No | Yes | |
+ | B | EMP ID | Yes | Family key |
+ | C | NAME OF EMP/DEP | Yes | |
+ | D | DOB | Yes | d-M-Y; age vs relationship checked |
+ | E | Gender | Yes | M / F (several casings allowed) |
+ | F | RELATIONSHIP | Yes | Self, Spouse, Son, Daughter, … |
+ | G | BASIC COVER SI | Conditional | Validated against slab when applicable |
+ | H | Date of Coverage | No | Mandatory for addition / DA only |
+ | I | DOJ | No | |
+ | J | Basic Pay | No | Used when policy terms need it |
+ | K | Band/Grade | No | |
+ | L | Designation | No | |
+ | M | Phone | No | Mobile format; duplicate check |
+ | N | Email | No | Duplicate check in file |
+ | O | PRE EXISTING AILMENTS | Yes | 0 or 1 |
+ | P | Change event | No | Not used for pure inception |
+ | Q | Date of exit | No | Deletion only |
+ | R | Reason for exit | No | Deletion only |
+ | S | Unit | No | Must match branch units when filled |
+
+
+
+Sample file: use the download link on the employee upload screen (environment-specific).
+
+Family row layout example
+
+
+ All rows with the same EMP ID (column B) are treated as one family.
+ Step 2 requires exactly one Self row in that group; dependents share the same EMP ID.
+ Step 3 runs premium and DB insert once per family.
+
+
+Example: one employee (EMP001) with spouse and son — three data rows plus header.
+
+
+
+
+ | Row |
+ S.No |
+ EMP ID |
+ NAME |
+ DOB |
+ Gender |
+ RELATIONSHIP |
+ BASIC COVER SI |
+ PED |
+
+
+
+ | 1 | Header row (all 19 columns A–S required in file) |
+
+ | 2 |
+ 1 |
+ EMP001 |
+ Raj Kumar |
+ 15-Jan-1985 |
+ M |
+ Self |
+ 500000 |
+ 0 |
+
+
+ | 3 |
+ 2 |
+ EMP001 |
+ Priya Kumar |
+ 20-Mar-1988 |
+ F |
+ Spouse |
+ 500000 |
+ 0 |
+
+
+ | 4 |
+ 3 |
+ EMP001 |
+ Arjun Kumar |
+ 10-Jun-2015 |
+ M |
+ Son |
+ 500000 |
+ 0 |
+
+
+
+
+Rules illustrated:
+
+ - Same EMP ID on rows 2–4 → one family processed in step 3.
+ - Self on row 2 only — row 3 without Self would fail with code 14.
+ - DOB uses
d-M-Y; ages are checked against relationship (e.g. Son vs Self).
+ - PED (PRE EXISTING AILMENTS) =
0 or 1 on every member for inception.
+ - BASIC COVER SI must match slab rules when the policy uses SI-based racks (often same amount across the family).
+ - Columns H–S can be blank for inception when not mandatory; phone/email must be unique in the file if filled.
+
+
+
+ A second employee in the same file uses a different EMP ID (e.g. EMP002) with its own Self row — each EMP ID is a separate family loop in preprocess.
+
+
+Developer steps
+
+
+ - Confirm policy has
policy_terms JSON and slab/rack rates for the client policy.
+ - Upload via
/employee/upload with action inception; note file_id in response or files table.
+ - If
status = failed, call GET /employee/excel_error/{file_id} or read files.reason.
+ - Map
error_data row keys back to Excel (row 1 = header).
+ - If format passes but preprocess fails with rack message, debug
calculate_premium_new (see rack-rate doc) and SI/slab config.
+ - For stuck
inprogress, check job queue / JobWorker logs for the three job names.
+
+
+Common pitfalls
+
+
+ - Policy not ready — missing
policy_terms or slab rates fails step 1 with code 5.
+ - Missing Self row — one Self per EMP ID in the file (code 14 in step 2).
+ - Wrong header row — column count or name mismatch (code 5 / 6).
+ - Rack rate / SI — preprocess succeeds only if
calculate_premium_new returns data for every family.
+ - File status — watch
files.reason JSON for row-level errors after failure.
+
diff --git a/app/Views/docs/non-eb-claims.php b/app/Views/docs/non-eb-claims.php
new file mode 100644
index 00000000..71aec5c5
--- /dev/null
+++ b/app/Views/docs/non-eb-claims.php
@@ -0,0 +1,488 @@
+
+
+
+ This page documents the Non-EB Claims web workflow: list and filter claims,
+ create and edit tickets, status-driven form sections, document uploads, manual email reply,
+ mail template CRUD, auto-mail on create/status change, and claim reports.
+
+
+
+ Scope: authenticated MVC routes under /non-eb-claim/* only.
+ Mobile/REST endpoints in Api\NonEbClaimApiController are not covered here.
+
+
+
+ Policy types are limited to policy_type.allocg IN ('Non-EB', 'Marine').
+ Claim records live in non_eb_ticket_master; claim files use ticket_type = 2
+ in claim_files.
+
+
+End-to-end flow
+
+
+
+flowchart TD
+ L["GET /non-eb-claim/list"] --> F["Filter sidebar → POST /list"]
+ F --> T["Table non_eb_claim_list.php"]
+ T --> A{"Action"}
+ A -->|Add| N["GET /non-eb-claim/new/50 or new/{policy_type_id}"]
+ N --> C["POST /non-eb-claim/create"]
+ C --> AM["sendAutoMailTrigger if template is_auto_mail=1"]
+ A -->|Row click / View| V["GET /non-eb-claim/view/{id}"]
+ V --> U["POST /non-eb-claim/update"]
+ U --> SC{"claim_status_id changed?"}
+ SC -->|yes| AM2["sendAutoMailTrigger"]
+ MT["GET /non-eb-claim/mail_template"] --> CRUD["POST crud_mail_template/1|2|3"]
+ R["GET /non-eb-claim/reports"] --> RP["POST /reports — UI only; see pitfalls"]
+
+ Typical user path:
+
+ - Open claim list (default: open claims excluding settled/closed/rejected/withdrawn).
+ - Add claim → form opens with canonical status policy type
50 — see why 50 is hardcoded.
+ - On save, optional auto-mail fires if a matching template has
is_auto_mail = 1.
+ - Open claim from list → edit view with history, messages, files, notes.
+ - Change status → allowed next statuses from
ticket_claim_status.allowed_status; section visibility updates.
+ - Configure templates at
/non-eb-claim/mail_template (direct URL; not in main Claims sidebar today).
+
+
+Why policy type 50 is hardcoded (read this before changing Non-EB Claims)
+
+
+
+ Non-EB has many real policy products (Fire, Marine, Liability, etc. — each row in
+ policy_type with allocg Non-EB or Marine). Claim status workflows are
+ not stored separately per product today. The team configured one canonical policy type,
+ id 50, in the database as the single source of status definitions. The application
+ assumes every Non-EB/Marine claim uses that same status set unless you deliberately change
+ backend and frontend.
+
+ Design assumption
+
+
+ Claim statuses live in ticket_claim_status, keyed by ticket_type (which equals
+ policy_type.id). Mail templates in ticket_mail_template also key off
+ ticket_type + trigger_type from that status row.
+
+
+Instead of maintaining duplicate status trees for every Non-EB product, developers assumed:
+
+
+
+ All Non-EB and Marine policy types share one identical claim status lifecycle.
+ That lifecycle is configured only under policy type 50 in
+ ticket_claim_status (and matching templates under ticket_type = 50).
+
+
+
+
+ New claims opened via the list Add button or New Non EB Claim menu therefore
+ pass 50 into the form URL. Status dropdowns, section visibility, and initial status resolution in
+ getClaimStatusForPolicyType($policy_type_id) all use that id on create — not the id of the policy
+ the user later picks from client_policy.
+
+
+Policy type 50 vs policy selected on the form
+
+On create (non_eb_claim_form.php):
+
+ - Hidden
policy_type_id is set from the URL segment (typically 50) and is not updated when the user selects a branch policy.
+ - The UI shows the real product name in
policy_type_display from the selected policy row (data-policy-type).
+ POST /non-eb-claim/create persists policy_type_id from that hidden field — so new tickets from Add often store policy_type_id = 50 even when the linked policy is Fire, Marine, etc.
+
+
+ On edit (non_eb_claim_edit.php), policy_type_id comes from
+ non_eb_ticket_master as saved. Status changes and templates use that stored id.
+
+
+Where 50 appears in code (change all if this design changes)
+
+
+
+
+ | Location | Usage |
|---|
+
+
+ app/Config/Routes.php | GET non-eb-claim/new → claimForm/50 |
+ app/Views/non_eb_claim_list.php | DataTable Add button → /non-eb-claim/new/50 |
+ app/Views/non_eb_claim_form.php | Hidden policy_type_id from route; status/section AJAX uses this value |
+ ticket_claim_status (DB) | Master status rows maintained with ticket_type = 50 |
+ ticket_mail_template (DB) | Non-EB auto-mail templates should use ticket_type = 50 if they follow the shared workflow |
+ Api\NonEbClaimApiController::listClaimStatuses() | API hardcodes where('ticket_type', 50) (out of scope for this page but same assumption) |
+
+
+ When a Non-EB product needs a different status set
+
+
+ If a new (or existing) policy type must have its own statuses, triggers, or allowed transitions
+ (not the shared tree under 50), you cannot only change the product row in
+ policy_type. You must update both backend and frontend:
+
+
+
+ - Database — Add full
ticket_claim_status rows with
+ ticket_type = <that policy_type.id> (claim_status, display_name, trigger_type,
+ allowed_status JSON). Add matching ticket_mail_template rows for that
+ ticket_type if auto-mail applies.
+ - Routes / entry URL — Stop routing every new claim through
50: e.g. change
+ claimForm/50, restore policy-type picker modal (commented in
+ non_eb_claim_search.php), or pass the correct policy_type_id per product.
+ - List Add button — Replace hardcoded
new/50 in
+ non_eb_claim_list.php with the correct id or dynamic selection.
+ - Create form — On policy selection, set hidden
#policy_type_id to the real
+ policy_type_id from getBranchAndPolicy (field p.policy_type_id is
+ already returned) so create/update and getVisibleSections use the right status tree.
+ - Controller logic — Ensure
getClaimStatusForPolicyType,
+ getTemplateDataByTicketID, and filters that assume a single Non-EB status catalog are tested for
+ the new ticket_type.
+ - API — Replace hardcoded
50 in listClaimStatuses() if mobile
+ clients need per-product statuses.
+
+
+
+ Until those steps are done, pointing Add at another id without cloning the full status + template set under
+ that id will produce empty status lists, wrong section visibility, or
+ missing auto-mail.
+
+
+Key files and routes
+
+
+
+ | Area | File / route |
|---|
+
+
+ | Controller | app/Controllers/NonEbClaimController.php |
+ | Model | app/Models/NonEbTicketMasterModel.php |
+ | List + filters | app/Views/non_eb_claim_search.php, non_eb_claim_list.php |
+ | New claim | app/Views/non_eb_claim_form.php |
+ | View / edit | app/Views/non_eb_claim_edit.php |
+ | Mail templates | app/Views/non_eb_claim_mail_template.php |
+ | Reports | app/Views/non_eb_claim_reports.php |
+ | Routes | app/Config/Routes.php — group /non-eb-claim, filter authMVC |
+ | ACL | app/Config/Acl.php — #^/non-eb-claim# (Claims team roles) |
+ | App menu | app/Views/layout/header.php — New / List only (EB mail template link is separate) |
+
+
+
+MVC route map
+
+
+
+
+ | Method | Route | Controller | Purpose |
|---|
+
+
+ | GET | /non-eb-claim/list | claimList | Search page + default open claims |
+ | POST | /non-eb-claim/list | claimList | Filter → HTML partial for DataTable |
+ | GET | /non-eb-claim/new | claimForm/50 | New claim (default policy type 50) |
+ | GET | /non-eb-claim/new/{policy_type_id} | claimForm | New claim for selected product |
+ | POST | /non-eb-claim/create | createClaim | Create ticket + assets + history + auto-mail |
+ | GET | /non-eb-claim/view/{id} | view_claim | Edit layout (non_eb_claim_edit) |
+ | POST | /non-eb-claim/update | updateClaim | Update; auto-mail on status change |
+ | GET | /non-eb-claim/remove?ticket_id= | removeClaim | Soft delete (is_active = 0) |
+ | GET | /non-eb-claim/mail_template | mailTemplate | Template list + modal CRUD UI |
+ | POST | /non-eb-claim/crud_mail_template/1 | crudTemplate | Save template |
+ | POST | /non-eb-claim/crud_mail_template/2 | crudTemplate | Fetch one template (edit) |
+ | POST | /non-eb-claim/crud_mail_template/3 | crudTemplate | Soft delete template |
+ | POST | /non-eb-claim/note/1 | crudNote | Get note |
+ | POST | /non-eb-claim/note/2 | crudNote | Save note |
+ | POST | /non-eb-claim/reply | saveReply | Manual outbound mail + message row |
+ | GET | /non-eb-claim/reports | claimReports | Reports UI shell |
+ | POST | /non-eb-claim/reports | claimReports | Not implemented in controller — see Reports |
+ | POST | /non-eb-claim/getBranchAndPolicy | getBranchAndPolicyByClientID | Branches, policies, contacts for client |
+ | POST | /non-eb-claim/getVisibleSections | getVisibleSectionsAjax | Section keys for status |
+ | POST | /non-eb-claim/getMoreInfo | getMoreInfo | Ticket row JSON |
+ | POST | /non-eb-claim/uploadFile | uploadFile | Claim docs (file or Drive URL) |
+ | POST | /non-eb-claim/getClaimFiles | getClaimFiles | List files for ticket |
+ | GET | /non-eb-claim/removeFile?id= | removeFile | Soft delete file |
+ | POST | /non-eb-claim/saveIRDocs | saveIRDocs | Persist required-docs JSON on ticket |
+ | GET | /non-eb-claim/testAutoMail/{id} | testAutoMailTrigger | Dev/test auto-mail (optional) |
+
+
+ Access control
+
+
+ All routes in the /non-eb-claim group use the authMVC filter.
+ Acl.php allows roles HEAD, ADMIN, MANAGER,
+ ACCOUNT_MANAGER on the Claims team.
+
+
+
+ List row actions (view / delete) render only for roles 1, 2, 5 in
+ non_eb_claim_list.php.
+
+
+List and filter
+
+GET /non-eb-claim/list loads non_eb_claim_search.php, which includes the table partial. Initial data comes from claimSearch(1): active tickets where status display name is not in Claim Settled, Claim Closed, Claim Rejected, Claim Withdrawn.
+
+Filter sidebar posts the same URL with criteria (at least one required):
+
+ policy_type_id, insurer_id, claim_number, nhance_claim_ref_noclient_id, claim_status_id (status options filtered by policy type in JS)date_type + start_date / end_date (created_date or updated_date)
+
+
+ Response is JSON { status: true, html: "…" }; JS replaces #claim_list_div
+ and re-initializes the DataTable. Row click navigates to /non-eb-claim/view/{id}.
+
+
+
+ Add button: window.location.href = '/non-eb-claim/new/50'.
+ Header menu uses /non-eb-claim/new (routes to claimForm/50).
+ See Policy type 50 for why this id is fixed and what to change if a product needs its own statuses.
+
+
+Create and edit claim
+
+Create
+
+
+ GET /non-eb-claim/new/{policy_type_id} → getFormData(): ACMs (role 3), clients, insurers, initial claim status for product, visible sections.- User selects client →
POST getBranchAndPolicy fills branch, policy (Non-EB/Marine only), branch contact.
+ - Status change →
POST getVisibleSections toggles accordion sections client-side.
+ POST /non-eb-claim/create — validation via getValidationRules(), sanitizeInputArrayAdvanced, date normalization, optional asset file upload.- Duplicate guard: same
client_id + loss_date + policy_no (if policy set) → HTTP 409-style JSON.
+ - On success: insert
non_eb_ticket_master, saveAssets(), history row, sendAutoMailTrigger(), redirect to list.
+
+
+View / edit
+
+
+ view_claim($id) loads ticket via NonEbTicketMasterModel::getTicketDataByTicketID(),
+ merges mail template preview (getTemplateDataByTicketID + placeholder replace),
+ messages, history, assets, and reuses the edit view non_eb_claim_edit.php.
+
+
+
+ POST /non-eb-claim/update mirrors create validation. If claim_status_id changes,
+ auto-mail runs again. remark_mode=append appends to closure_remark with a separator.
+
+
+Status-driven sections
+
+
+ $statusSectionVisibility in the controller maps each ticket_claim_status.claim_status
+ label to section keys: policy_account, loss_incident, intimation,
+ insured_contact, asset, documents, surveyor, settlement.
+
+
+
+ Allowed next statuses come from getClaimStatusForPolicyType(): current status plus IDs in
+ allowed_status JSON on the status row. Both create and edit forms call
+ getVisibleSectionsAjax when the user changes status.
+
+
+Auto-mail and placeholders
+
+Template lookup (NonEbTicketMasterModel::getTemplateDataByTicketID):
+
+ - Join
ticket_claim_status on ticket’s claim_status_id (or explicit status_id for tests).
+ - Join
ticket_mail_template where ticket_type = policy_type_id AND trigger_type = tcs.trigger_type.
+
+
+
+ sendAutoMailTrigger($ticket_id) sends only when the matched template has
+ is_auto_mail = 1. Mail goes to insured_contact_email from
+ constructMailContent(); from address claims@nhanceindia.in via MailHelper::send_email().
+ Successful sends insert a ticket_messages row via autoMessageInsertBasedOnMailResponse().
+
+
+Placeholders (subject/body):
+
+
+
+ | Token | Ticket field |
|---|
+
+ ((ACM)) | acm |
+ ((ACM_CONTACT)) | acm_mobile |
+ ((INSURED_NAME)) | insured_contact_name |
+ ((CORPORATE_NAME)) | client_name |
+ ((CLAIM_NO)) | claim_number |
+ ((POLICY_TYPE)) | policy_type_name |
+ ((NHANCE_REF_NO)) | nhance_claim_ref_no |
+ ((LOSS_DATE)) | loss_date |
+ ((LOSS_LOCATION)) | loss_location |
+ ((NATURE_OF_LOSS)) | nature_of_loss |
+
+
+
+ Edit screen also supports manual reply: POST /non-eb-claim/reply validates To/Subject,
+ inserts ticket_messages, sends via sendReplyMessage() with placeholder replacement.
+
+
+Mail template CRUD
+
+
+ Page: GET /non-eb-claim/mail_template. DataTable lists rows from
+ ticket_mail_template (is_active = 1). Tooltip on each row shows the
+ matching ticket_claim_status.claim_status for that policy type + trigger type.
+
+
+
+
+flowchart LR
+ UI["mail_template UI"] --> S1["POST crud_mail_template/1 Save"]
+ UI --> S2["POST crud_mail_template/2 Fetch"]
+ UI --> S3["POST crud_mail_template/3 Delete"]
+ S1 --> DB["ticket_mail_template"]
+ S2 --> DB
+ S3 --> DB
+
+ Template fields
+
+
+ template_name, ticket_type (policy type id), trigger_type (1–9)subject, mail_content (Jodit HTML)is_auto_mail — checkbox “Auto Mail” (1 = send on create / status change when matched)- Optional
id on save for update
+
+
+
+ Trigger ↔ status: Each ticket_claim_status row for a Non-EB/Marine
+ ticket_type has a trigger_type. The template’s trigger_type must match
+ that column for auto-mail and for the “Claim Status” readonly hint (tool_tip from server on fetch).
+
+
+UI actions
+
+
+
+
+ | Action | Endpoint | Body | Result |
|---|
+
+
+ | Add / Save | POST …/crud_mail_template/1 | Form fields + mail_content + is_auto_mail | { status: bool } → reload |
+ | Edit load | POST …/crud_mail_template/2 | id | { status, data } opens modal |
+ | Delete | POST …/crud_mail_template/3 | id | Soft delete (is_active = 0) |
+
+
+
+ Placeholder dropdown in the modal inserts tokens into subject (focused input) or Jodit body.
+ Validation errors return HTTP 400 with errors map (shown via toastr).
+
+
+Notes
+
+On the edit screen:
+
+ POST /non-eb-claim/note/1 — id (ticket), optional is_auto_query → fetch active note.POST /non-eb-claim/note/2 — save note (required 3–1000 chars) via TicketNoteModel.
+
+Documents and IR checklist
+
+
+ uploadFile — multi upload to writable/uploads/claim_files/ or Google Drive URLs (file_type 1 vs 2).getClaimFiles — lists rows; local files expose download URL downloadClaimFile/{id}.removeFile — soft delete by file id.saveIRDocs — stores JSON in non_eb_ticket_master.required_docs.- Asset spreadsheet on ticket:
asset_file under writable/uploads/non_eb_asset_files/; loss description required when file uploaded.
+
+
+Reports
+
+
+ GET /non-eb-claim/reports renders filters: policy type, ACM name, date range (default last 60 days).
+ generateReport() in the view POSTs to the same URL and expects
+ { status: true, data: [ rows ] } for DataTable columns (status, policy type, claim/ref, client, insurer, loss fields, surveyor, settlement, ACM, created date).
+
+
+
+ Gap: NonEbClaimController::claimReports() only handles GET (layout load).
+ There is no POST handler to return report data — Generate Report will fail until POST logic is added
+ (mirror EB ticket_reports or reuse claimSearch with report-specific selects).
+
+
+Data model (summary)
+
+
+ | Table | Role |
|---|
+
+ non_eb_ticket_master | Main claim ticket |
+ non_eb_claim_asset | Repeating asset lines per ticket |
+ ticket_claim_status | Statuses per ticket_type (policy type id); trigger_type, allowed_status |
+ ticket_mail_template | Templates; ticket_type = policy type id |
+ ticket_history | Field-level audit (status, ACM, priority, …) |
+ ticket_messages | Outbound mail log |
+ ticket_notes | User notes per ticket |
+ claim_files | Attachments; ticket_type = 2 for Non-EB |
+
+
+
+Controller reference
+
+
+
+ | Method | Used for |
|---|
+
+ claimList / claimSearch | List UI and filtered HTML |
+ claimForm / getFormData | New claim form bootstrap |
+ view_claim | Edit view |
+ createClaim / updateClaim | Persist ticket |
+ getClaimStatusForPolicyType / getVisibleSections* | Status dropdown + sections |
+ mailTemplate / crudTemplate | Template admin |
+ sendAutoMailTrigger / constructMailContent | Automated email |
+ saveReply / getTicketMessage | Manual email thread |
+ crudNote | Notes |
+ uploadFile / getClaimFiles / removeFile / saveIRDocs | Documents |
+ saveAssets / getAssets | Asset grid |
+ claimHistory / putHistoryAfterInsert | Audit trail |
+ getBranchAndPolicyByClientID | Client cascade |
+ claimReports | Reports page (GET only today) |
+ testAutoMailTrigger | Dev preview/send test |
+
+
+ Developer checklist
+
+
+ - Ensure
ticket_claim_status rows exist per Non-EB/Marine policy_type.id with correct trigger_type and allowed_status.
+ - Create mail templates at
/non-eb-claim/mail_template with matching ticket_type + trigger_type; enable Auto Mail only where intended.
+ - Verify insured email is present before relying on auto-mail.
+ - Before changing Add/new URLs: read Policy type 50 — clone statuses + templates in DB and update every hardcoded
50 if a product needs its own workflow.
+ - Implement POST branch in
claimReports() if reports Generate must work.
+ - Claim files: always set
ticket_type = 2 in new file-related code paths.
+ - ACL: extend
#^/non-eb-claim# if new roles need access.
+
+
+Common pitfalls
+
+
+ - Template mismatch: No row in
ticket_mail_template for policy type + status trigger_type → no auto-mail and empty reply preview.
+ - Reports POST missing: UI POSTs to
/non-eb-claim/reports but controller only loads view on GET.
+ - Duplicate claims: Same client + loss date + policy number blocked on create.
+ - Policy type 50 assumption: Shared status catalog under DB
ticket_type = 50; Add/new routes and hidden form field use 50 — not the policy picked on the form. Different per-product statuses require full backend + frontend changes — checklist.
+ - Menu vs Non-EB templates: Sidebar “Mail Template” points to EB
/ticket/mail_template, not Non-EB.
+ - Soft deletes: Remove claim/file/template sets
is_active = 0; list queries filter active only.
+ - Asset file: Upload without loss description fails validation on create/update.
+ - REST API separate: Mobile create/list under
employeeRest / Api\NonEbClaimApiController — different validation and flows.
+
diff --git a/app/Views/docs/non-eb-opportunities.php b/app/Views/docs/non-eb-opportunities.php
new file mode 100644
index 00000000..eb4e7576
--- /dev/null
+++ b/app/Views/docs/non-eb-opportunities.php
@@ -0,0 +1,638 @@
+
+
+
+ This page documents the Non-EB Opportunities workflow from the
+ Opportunities list (/leads/list). A user creates a Non-EB opportunity,
+ then progresses through RFQ → QCR → mail actions → placement — all from the list row action menu.
+
+
+
+ Non-EB rows are identified by leads.lead_form_type = 2 (EB = 1).
+ RFQ and QCR are managed in Google Sheets; sheet IDs are stored in
+ leads.misc JSON.
+
+
+End-to-end flow
+
+
+
+flowchart TD
+ A["/leads/list — Add → Non-EB"] --> B["Add form leads_non_eb.php"]
+ B --> C["POST /leads/create"]
+ C --> D["status: queued"]
+ D --> E["Action: RFQ"]
+ E --> F["GET /leads/createRfqSheet"]
+ F --> G["status: rfq_created"]
+ G --> H["Action: QCR"]
+ H --> I["GET /leads/createQcrSheet"]
+ I --> J["status: qcr_created"]
+ J --> K["Action: Send Internal Mail"]
+ K --> L["POST /leads/sendMail internal"]
+ L --> M["Action: Send Insurer Mail"]
+ M --> N["POST /leads/sendMail insurer → rfq_sent"]
+ N --> O["Action: Send Client Mail"]
+ O --> P["POST /leads/sendMail client → qcr_sent"]
+ P --> Q["Action: Placement"]
+ Q --> R["POST /leads/sendMail placement → won"]
+
+ Typical sequence from the list:
+
+ - Create opportunity (form submit) →
queued
+ - RFQ — create/open Google Sheet →
rfq_created
+ - QCR — copy RFQ sheet →
qcr_created
+ - Send Internal Mail — team mail with RFQ or QCR attachment (by current status)
+ - Send Insurer Mail — RFQ sheet attached →
rfq_sent
+ - Send Client Mail — QCR sheet attached →
qcr_sent
+ - Placement — placement sheet + policy/payment fields →
won
+
+
+
+ Edit is available at any stage from the same action menu and reuses the add form
+ with pre-filled data (getLeadNonEB + POST /leads/create with lead id).
+
+
+Key files
+
+
+
+ | Area | File |
|---|
+
+
+ | List + action dropdown | app/Views/leads_list.php |
+ | Non-EB add/edit form | app/Views/leads_non_eb.php |
+ | EB vs Non-EB form include | app/Views/leads_form_handler.php |
+ | All backend logic | app/Controllers/LeadsController.php |
+ | Google Sheets | GoogleSheetLib, Config\RfqConfig |
+
+
+
+Google Sheet config
+
+
+ Non-EB RFQ, QCR, and Placement sheets are Google Drive files created at runtime by
+ GoogleSheetLib using a service account. Only RFQ needs a pre-configured
+ template per product; QCR and Placement are copies of the lead’s RFQ/QCR sheets.
+
+
+App ↔ Google Drive flow
+
+
+
+flowchart TB
+ subgraph setup ["One-time / per product setup"]
+ T["Drive: master RFQ template per product"]
+ PT["policy_type.misc.rfq_template_sheet_id"]
+ ENV[".env RFQ_PARENT_FOLDER_ID"]
+ SA["Service account JSON + share folder/templates"]
+ end
+
+ subgraph rfq ["RFQ — createRfqSheet"]
+ R1["Read template ID from policy_type.misc"]
+ R1 --> C1["Drive copyTemplate → parent folder"]
+ C1 --> F1["Sheets find/replace placeholders"]
+ F1 --> P1["Drive applyPermissions viewers"]
+ P1 --> PR1["Sheets applyProtections"]
+ PR1 --> S1["Save leads.misc.rfq_sheet_id"]
+ end
+
+ subgraph qcr ["QCR — createQcrSheet"]
+ S1 --> C2["Drive copyTemplate from rfq_sheet_id"]
+ C2 --> P2["applyPermissions viewers"]
+ P2 --> S2["Save leads.misc.qcr_sheet_id"]
+ end
+
+ subgraph placement ["Placement — createAndDownloadPlacementSheet"]
+ S2 --> C3["Drive copyTemplate from qcr_sheet_id"]
+ C3 --> P3["applyPermissions viewers"]
+ P3 --> S3["Save leads.misc.placement_sheet_id"]
+ S3 --> X1["Drive export .xlsx → mail attachment"]
+ end
+
+ subgraph mail ["Mail — downloadFileFromGoogleSheet"]
+ S1 --> X2["Export RFQ or QCR as Excel"]
+ S2 --> X2
+ end
+
+ PT --> R1
+ ENV --> C1
+ T --> PT
+ SA --> C1
+
+ Library: app/Libraries/GoogleSheetLib.php — auth via service account JSON at
+{project-root}/nhance-ee8d1-e3c5269b1ec7.json, scopes DRIVE + SPREADSHEETS.
+
+What must be done before RFQ / QCR
+
+
+
+ | Step | Before | Why |
|---|
+
+
+
+ | 1 |
+ Google service account JSON present; account email shared on template folder + each template sheet |
+ GoogleSheetLib cannot copy or edit without Drive access |
+
+
+ | 2 |
+ RFQ_PARENT_FOLDER_ID set in .env |
+ Target folder for every copied RFQ/QCR/Placement file |
+
+
+ | 3 |
+ Master RFQ Google Sheet template created per product (Fire, Marine, GPA, etc.) with placeholder tokens |
+ RFQ copy source — one template per policy_type row |
+
+
+ | 4 |
+ policy_type.misc JSON updated with rfq_template_sheet_id for that product |
+ createRfqSheet() reads this; fails with “RFQ template not found” if missing |
+
+
+ | 5 |
+ Non-EB opportunity created with correct policy_type_id and rfq_qcr_viewers emails |
+ Lead must exist; viewers become sheet editors after copy |
+
+
+ | 6 |
+ Before QCR: RFQ action completed (leads.misc.rfq_sheet_id set) |
+ QCR copies the lead’s RFQ sheet, not the policy template |
+
+
+ | 7 |
+ Before Placement mail: QCR action completed (leads.misc.qcr_sheet_id set) |
+ Placement copies the QCR sheet |
+
+
+
+
+Where to configure sheet ID per product
+
+
+ Template sheet IDs are stored per product on the policy_type table —
+ one row per product (Fire, Marine, Burglary, etc.). The lead’s selected
+ policy_type_id determines which template is copied when RFQ is clicked.
+
+
+Database column: policy_type.misc (JSON text)
+
+{
+ "rfq_template_sheet_id": "1GXNDNXoWriClb5HCqPYd2GAY1T8aie_Hos0yAOoTaC0"
+}
+
+Example — set or update for policy type id 12:
+
+UPDATE policy_type
+SET misc = JSON_SET(COALESCE(misc, '{}'), '$.rfq_template_sheet_id', 'YOUR_GOOGLE_DRIVE_FILE_ID')
+WHERE id = 12;
+
+
+ i
+
+ There is no admin UI field for rfq_template_sheet_id today — configure via DB (or extend
+ MasterController::editPolicyType / policy_type_onboarding if you add a form field).
+ Model allow-list: app/Models/PolicyTypeModel.php includes misc.
+
+ How to find a template file ID:
+
+ - From the Google Sheet URL:
https://docs.google.com/spreadsheets/d/{FILE_ID}/edit
+ - CLI — list all sheets in the RFQ parent folder:
+
php public/index.php cli/list-sheet-folder-files {RFQ_PARENT_FOLDER_ID}
+ → writes sheetid.json with name + sheetId pairs
+ (GoogleSheetController::listFolderSheetFilesCli)
+
+
+QCR and Placement: no separate template ID per product. They always copy from the lead’s existing sheets:
+
+
+
+ | Stage | Copy source | Stored on lead |
|---|
+
+
+ | RFQ | policy_type.misc.rfq_template_sheet_id | leads.misc.rfq_sheet_id |
+ | QCR | leads.misc.rfq_sheet_id | leads.misc.qcr_sheet_id |
+ | Placement | leads.misc.qcr_sheet_id (filename: QCR → Placement) | leads.misc.placement_sheet_id |
+
+
+
+App-level config files
+
+
+
+ | Setting | Location | Purpose |
|---|
+
+
+
+ RFQ_PARENT_FOLDER_ID |
+ .env → Config\RfqConfig::$rfqParentFolderId |
+ Google Drive folder where copied RFQ/QCR/Placement files are created |
+
+
+ rfqPlaceholders |
+ app/Config/RfqConfig.php |
+ Maps template tokens like {{INSURED_NAME}} to lead field keys filled on RFQ create |
+
+
+ rfqClaimsPlaceholder |
+ app/Config/RfqConfig.php |
+ Default {{CLAIMS_DETAILS}} — multi-row claims table from fin_years_claims |
+
+
+ protections |
+ app/Config/RfqConfig.php |
+ Locked cell ranges on new RFQ sheets only (e.g. RFQ Page!B12:C12) |
+
+
+ | Service account key |
+ nhance-ee8d1-e3c5269b1ec7.json (project root) |
+ Google API authentication for all sheet operations |
+
+
+
+
+Placeholder tokens to embed in each product’s RFQ master template:
+
+
+
+ | Token in template | Filled from |
|---|
+
+
+ {{INSURED_NAME}} | Client name / short name |
+ {{COMMUNICATION_ADDRESS}} | Client or custom field address |
+ {{GST}} / {{PAN}} | Lead GST / PAN |
+ {{POLICY_PERIOD}} | Policy start – end dates |
+ {{OPPORTUNITY_TYPE}} | Fresh / Renewal label |
+ {{RISK_LOCATION}} / {{OCCUPANCY}} | Custom policy-type fields |
+ {{CLAIMS_DETAILS}} | Claim history table (renewal leads) |
+
+
+
+
+ After RFQ copy, editors are granted from the lead’s rfq_qcr_viewers JSON email list (selected on the create/edit form).
+ The same list is applied to QCR and Placement copies.
+
+
+Step 1 — Create opportunity
+
+From the list
+
+ - Open
/leads/list → click Add.
+ - Modal Select Opportunity Type → choose Non-EB (
lead_form_type=2).
+ - Redirect:
GET /util/getLeadNonEB/2/0.
+
+
+
+
+ - Sections: Opportunity Details, Client Information, Branch Information, Policy Details, Sales & Assignment.
+ - Policy types limited to
allocg = Non-EB or Marine.
+ - Policy type change →
GET /util/getPolicyTypeFields → dynamic fields in #appendArea.
+ - Renewal types may show claim history rows → stored as
fin_years_claims JSON.
+ rfq_qcr_viewers (emails) become Google Sheet editors later.- Submit → AJAX
POST /leads/create with lead_form_type=2.
+
+
+Controller: createLead()
+
+ prepareLeadData() → prepareSingleLeadData() (one lead row; EB uses multi-row).- Non-EB validation: policy type, DOC/DOE, claim-history rows when
claim_history=1.
+ insertNewLead() — no demography background job (EB-only).- Initial status:
queued (In-Queued).
+
+
+Edit flow
+
+From the list action menu → Edit (available for both EB and Non-EB):
+
+
+ - JS:
getLeadsDataForEdit(lead_id, lead_form_type, actual_lead_id)
+ - Redirect:
GET /util/getLeadNonEB/{lead_form_type}/{actual_lead_id}/{lead_id}
+ - Controller:
getLeadNonEB($type, $actual_lead_id, $id) (~line 4818)
+
+ - Loads master data (issuer, policy types, sales team, etc.)
+ - When
$id present: fetches lead_edit_data, files, custom fields, date formatting
+ - Builds dynamic policy HTML via
generateViewPageHtml()
+ - Renewal Non-EB: renders
rfq/claims_details_non_eb into claims_details_html
+ - Returns layout with
leads_form_handler → includes leads_non_eb.php when selected_lead_type != 1
+
+
+ - Form pre-fills client, branch, policy, files, viewers, status, lost reason, etc.
+ - Submit same endpoint:
POST /leads/create with hidden id → updateOldLead()
+
+
+Steps 2–7 — List table actions (Non-EB)
+
+
+ When lead_form_type === 2, the row action menu in
+ app/Views/leads_list.php (lines ~297–343) uses modal/AJAX flows instead of
+ navigating to /rfq/list/{id}/1|2 (EB behaviour).
+
+
+
+ i
+
+ Menu order on screen (after opportunity is created): Edit → RFQ → QCR →
+ Send Internal Mail → Send Insurer Mail → Send Client Mail → Placement → Email History.
+
+ Action → view handler → controller endpoint
+
+
+
+
+
+ | # |
+ Action |
+ Visible when |
+ View (JS) / handler class |
+ Controller endpoint(s) |
+ Status after |
+
+
+
+
+ | — |
+ Edit |
+ Always (EB + Non-EB) |
+ getLeadsDataForEdit() |
+
+ GET
+ /util/getLeadNonEB/{lead_form_type}/{actual_lead_id}/{lead_id}
+ POST
+ /leads/create (update when id posted)
+ |
+ User-selected on form |
+
+
+ | 1 |
+ RFQ |
+ lead_form_type === 2 only |
+ .btnRfqSheetList → createRfqSheetFromList() |
+
+ GET
+ /leads/createRfqSheet?lead_id={id}
+ LeadsController::createRfqSheet() — opens Google Sheet URL in new tab
+ |
+ rfq_created |
+
+
+ | 2 |
+ QCR |
+
+ Non-EB; status not queued or rfq_created;
+ role 1, 5, 2, 3 or Business Support team
+ |
+ .btnQcrSheetList → createQcrSheetFromList() |
+
+ GET
+ /leads/createQcrSheet?lead_id={id}
+ LeadsController::createQcrSheet()
+ |
+ qcr_created |
+
+
+ | 3 |
+ Send Internal Mail |
+ Non-EB; status != queued |
+ .btnInternalMailList → openInternalMailFromList() |
+
+ GET
+ /leads/mailTemplate?lead_id={id}&template_type=rfq
+ POST
+ /leads/sendMail — recipient_type=internal
+ |
+ — |
+
+
+ | 4 |
+ Send Insurer Mail |
+ Same as internal mail |
+ .btnInsurerMailList → openInsurerMailFromList() |
+
+ GET
+ /leads/mailTemplate?lead_id={id}&template_type=rfq
+ POST
+ /leads/sendMail — recipient_type=insurer (RFQ sheet attach)
+ |
+ rfq_sent |
+
+
+ | 5 |
+ Send Client Mail |
+ Same as internal mail |
+ .btnClientMailList → openClientMailFromList() |
+
+ GET
+ /leads/mailTemplate?lead_id={id}&template_type=qcr
+ POST
+ /leads/sendMail — recipient_type=client (QCR sheet attach)
+ |
+ qcr_sent |
+
+
+ | 6 |
+ Placement |
+ Same as internal mail |
+ .btnPlacementList → openPlacementFromList() |
+
+ GET
+ /rfq/placementData/{id}
+ GET
+ /leads/mailTemplate?lead_id={id}&template_type=placement
+ POST
+ /leads/sendMail — recipient_type=placement
+ |
+ won |
+
+
+ | — |
+ Email History |
+ Always (EB + Non-EB) |
+ .btnHistory → getLeadsDataForMailHistory() |
+
+ GET
+ /util/getLeadEmailHistory/{id} → getLeadEmailHistory()
+ |
+ — |
+
+
+
+ EB contrast (same menu, lead_form_type === 1): RFQ/QCR are links to
+/rfq/list/{id}/1 and /rfq/list/{id}/2; internal/insurer/client/placement mail items are not shown.
+
+Shared mail modal helpers (all in leads_list.php):
+
+ POST /leads/uploadLeadAttachment — optional extra files (lead_id, docs_name, file)constructURL_ForInternalMailSend(), insurer/client via constructURL_ForInsurerOrClientMailSend(), placement via constructURL_ForPlacementMailSend()- External CC disclaimer modal (
#external_cc_disclaimer_modal) before client/placement send to non-user emails
+
+
+Step 2 — RFQ (createRfqSheet())
+
+
+ - Load lead +
policy_type.misc.rfq_template_sheet_id.
+ - If
misc.rfq_sheet_id exists → return existing Google Sheet URL.
+ - Copy template via
GoogleSheetLib::copyTemplate() into RfqConfig::rfqParentFolderId.
+ - Fill placeholders (
buildRfqPlaceholderData()): client, GST, PAN, policy period, claims table.
+ - Grant editors from
leads.rfq_qcr_viewers email JSON.
+ - Save
misc.rfq_sheet_id; set status = rfq_created.
+ - UI opens sheet in a new browser tab.
+
+
+Step 3 — QCR (createQcrSheet())
+
+
+ - Requires
misc.rfq_sheet_id — returns 400 if RFQ not created yet.
+ - If
misc.qcr_sheet_id exists → return existing URL.
+ - Copy the RFQ sheet (not the policy template) with a QCR filename.
+ - Same editor permissions from
rfq_qcr_viewers.
+ - Save
misc.qcr_sheet_id; set status = qcr_created.
+
+
+Steps 4–6 — Mail actions
+
+Load template — getLeadMailTemplate()
+
+ Called before each mail modal opens. Query params:
+ lead_id + template_type (rfq | qcr | placement).
+ Returns subject, HTML body, and attachment checkbox HTML from lead_files.
+
+
+Send — sendMailWithAttachement()
+
+For Non-EB (lead_form_type == 2), the Excel attachment comes from Google Sheets:
+
+
+
+ | recipient_type | Sheet used | Status after send |
|---|
+
+
+
+ internal |
+ QCR if status is qcr_created/qcr_sent, else RFQ |
+ Unchanged |
+
+
+ insurer |
+ misc.rfq_sheet_id |
+ rfq_sent (unless already past that stage) |
+
+
+ client |
+ misc.qcr_sheet_id |
+ qcr_sent |
+
+
+ placement |
+ createAndDownloadPlacementSheet() — copies QCR sheet |
+ won + saves placement/payment/installment fields |
+
+
+
+
+Implementation detail: downloadFileFromGoogleSheet() exports the chosen sheet to a temp
+.xlsx under writable/tmp/ before MailHelper::send_email().
+
+Step 7 — Placement
+
+Opened from list action → openPlacementFromList(leadId):
+
+ GET /rfq/placementData/{id} — pre-fills policy dates, premium, CD, installments, contacts.GET /leads/mailTemplate?template_type=placement — subject/body/attachments.- User fills placement modal: dates, premium/CD/total, installment rows, To/CC, optional external CC.
+ POST /leads/sendMail with recipient_type=placement.- Backend copies QCR → placement Google Sheet, attaches Excel, updates lead to
won,
+ persists placement_date, premium_amount, cd_amount, installments, etc.
+
+
+Status lifecycle
+
+
+
+ | Status | Label | Set by |
|---|
+
+
+ queued | In-Queued | Create form (default) |
+ rfq_created | RFQ Created | createRfqSheet() |
+ rfq_sent | RFQ Sent | Insurer mail |
+ qcr_created | QCR Created | createQcrSheet() |
+ qcr_sent | QCR Sent | Client mail |
+ won | Won | Placement mail |
+ lost | Lost | User sets on edit form + lost reason |
+
+
+
+leads.misc JSON
+
+{
+ "rfq_sheet_id": "…",
+ "qcr_sheet_id": "…",
+ "placement_sheet_id": "…"
+}
+
+Controller reference (list flow)
+
+Methods in LeadsController.php used by the list Non-EB flow:
+
+
+
+ | Method | Triggered from |
|---|
+
+
+ createLead() | Form submit (create + edit) |
+ getLeadNonEB() | Add / Edit navigation |
+ getPolicyTypeFields() | Policy type change on form |
+ createRfqSheet() | RFQ action |
+ createQcrSheet() | QCR action |
+ getLeadMailTemplate() | All mail modals |
+ getPlacementData() | Placement modal pre-fill |
+ uploadLeadAttachment() | Attachment upload in mail modals |
+ sendMailWithAttachement() | All mail sends + placement |
+ downloadFileFromGoogleSheet() | Mail attachment (internal/insurer/client) |
+ createAndDownloadPlacementSheet() | Placement mail attachment |
+ getLeadEmailHistory() | Email History modal |
+ buildRfqPlaceholderData() | RFQ sheet placeholder fill (helper) |
+
+
+
+Developer checklist
+
+
+ - Complete Google Sheet config for each Non-EB/Marine
policy_type before first RFQ.
+ - Set
policy_type.misc.rfq_template_sheet_id per product (see sheet ID per product).
+ - Configure
RFQ_PARENT_FOLDER_ID in .env and share folder/templates with the service account.
+ - Ensure placeholders in master templates match
Config\RfqConfig::$rfqPlaceholders.
+ - Gate new list actions with
$isNonEb in leads_list.php.
+ - Respect sheet order: RFQ → QCR → mails → placement.
+ - QCR button: roles
[1, 5, 2, 3] or BUSINESS_SUPPORT_TEAM_ID in user team.
+
+
+Common pitfalls
+
+
+ - QCR before RFQ:
createQcrSheet fails if rfq_sheet_id is missing.
+ - Queued status: Mail and placement actions are hidden until status moves past
queued.
+ - Insurer mail needs RFQ sheet; client mail needs QCR sheet — create sheets before sending.
+ - Internal mail attachment picks RFQ or QCR based on current lead status.
+ - Edit vs create: same
POST /leads/create; presence of hidden id triggers update.
+
diff --git a/app/Views/docs/partials/docs_header.php b/app/Views/docs/partials/docs_header.php
index 2b8a8e6e..949ee16e 100644
--- a/app/Views/docs/partials/docs_header.php
+++ b/app/Views/docs/partials/docs_header.php
@@ -39,6 +39,7 @@ $base = base_url();
/* ─── TOKENS ─────────────────────────────── */
:root {
--sidebar-w : 260px;
+ --toc-w : 200px;
--topbar-h : 56px;
--bg : #ffffff;
--bg2 : #f7f8fa;
@@ -143,6 +144,8 @@ $base = base_url();
/* ─── LAYOUT WRAPPER ─────────────────────── */
.docs-layout {
display : flex;
+ width : 100%;
+ align-items: flex-start;
margin-top: var(--topbar-h);
min-height: calc(100vh - var(--topbar-h));
}
@@ -208,6 +211,15 @@ $base = base_url();
.callout.success { background: #f0fdf4; border-color: #4ade80; color: #15803d; }
/* ─── TABLES ─────────────────────────────── */
+ .docs-table-wrap {
+ overflow-x: auto;
+ -webkit-overflow-scrolling: touch;
+ margin: 20px 0;
+ border: 1px solid var(--border);
+ border-radius: 8px;
+ }
+ .docs-table-wrap table { margin: 0; min-width: 640px; }
+ .docs-table-wrap--fluid table { min-width: 0; width: 100%; }
table { width: 100%; border-collapse: collapse; margin: 20px 0; font-size: 13.5px; }
th {
background : var(--bg2);
diff --git a/app/Views/docs/partials/docs_main_open.php b/app/Views/docs/partials/docs_main_open.php
index 8e53fffe..b81630d2 100644
--- a/app/Views/docs/partials/docs_main_open.php
+++ b/app/Views/docs/partials/docs_main_open.php
@@ -27,10 +27,11 @@ $toc = $toc ?? [];
B["excelFileFormatValidation"]
+ B --> C["excelFileDataValidation"]
+ C --> D["employeesSIEnhanceProcess job"]
+ D --> E["Recalc premium plus pending SI endorsements"]
+ B -->|errors| F["files.status failed"]
+ C -->|errors| F
+ D -->|loop done| G["files.status success"]
+
+
+
+In short:
+
+ - Step 1 — Format: 5 columns (A–E); Augmented SI validated against slabs (
check_si).
+ - Step 2 — Data: Member must exist on active policy; code 10 if not found.
+ - Step 3 — SI enhance: Picks rack rate by relationship, recalculates premium, inserts 3 pending endorsements per member.
+ - One Excel row = one member SI change (not whole-family in one row).
+
+
+Key files and routes
+
+
+
+ | Area | Location |
|---|
+
+
+
+ | UI |
+ app/Views/employee_upload.php — action SI Enhancement |
+
+
+ | Upload |
+ EmployeeController::employeesUplodWithEvents |
+
+
+ | Validation |
+ excelFileFormatValidation, excelFileDataValidation |
+
+
+ | SI process |
+ employeesSIEnhanceProcess |
+
+
+ | Onboard SI path |
+ employeesSIEnhanceProcessWhileOnbboard — SI during dependent addition onboard (not Excel) |
+
+
+ | Job |
+ employeesSIEnhanceProcess in JobWorker.php |
+
+
+ | Helpers |
+ excel_util_helper.php — transform_si_excel_row_to_calculatable_format, premium_calculation_manager |
+
+
+
+
+Routes (group /employee, authMVC):
+
+ GET /employee/upload — upload screenPOST /employee/upload — upload-action-type=si_enhancementGET /employee/excel_error/{file_id} — validation errors
+
+
+ i
+
+ files.policy_id is the client policy id. Slab rates load via
+ getPolicySlabRatesForEmpOnboard(policy_id, client_id).
+
+ Sync vs background jobs
+
+
+
+ | Step | < 1 MB | ≥ 1 MB |
|---|
+
+
+ | Format validation | Inline on upload | Job excelFileFormatValidation |
+ | Data validation | Job excelFileDataValidation | Same |
+ | SI enhance | Job employeesSIEnhanceProcess | Same |
+
+
+
+
+
+
+ - Uses
$si_enhance_excel_columns — 5 columns (A–E).
+ - Action code
SI for mandatory rules.
+ - Augmented SI (D): custom
check_si against policy slabs (same helper as inception SI column).
+ - Date of SI Enhancement (E):
d-M-Y.
+ - Policy must have slab/rack configuration or format step fails early (code 5).
+
+
+
+
+
+
+ | Code | Meaning |
|---|
+
+
+ | 1 | Mandatory missing |
+ | 2 | Wrong format |
+ | 3 | Not in allowed list |
+ | 4 | Custom validation failed (e.g. invalid Augmented SI for slab) |
+ | 5 | File / policy / slab problem |
+ | 6 | Column headers wrong |
+
+
+
+Step 2: excelFileDataValidation
+
+name_and_empid_check_in_db for si_enhancement:
+
+ - Row must match active employee + active
employee_polices on the policy.
+ - Not found → error code 10 (“Record Not found”).
+
+
+On success → queues employeesSIEnhanceProcess.
+
+Step 3: employeesSIEnhanceProcess
+
+
+
+flowchart TD
+ A["Read row Augmented SI and date"] --> B["Match active employee and policy"]
+ B --> C{"Pending SI on basic_cover_si?"}
+ C -->|Yes| D["Skip row log error"]
+ C -->|No| E["Resolve rack rate by relationship"]
+ E --> F["premium_calculation_manager"]
+ F --> G["Insert 3 pending endorsements actions si"]
+
+ Per row:
+
+ - Strip number formatting from Augmented SI (
removeNumberFormatting).
+ - Load employee (emp code + name + branch) and active
employee_polices row.
+ - Find applicable slab/rack rate from member relationship (Son/Daughter → childrens, parents, etc.).
+ - Build calculatable member payload via
transform_si_excel_row_to_calculatable_format (uses family max age/count).
+ premium_calculation_manager → new premium for the augmented SI.- Insert pending endorsements on
employee_polices (actions = si):
+
+
+
+
+ | field_name | new_value source |
|---|
+
+
+ basic_cover_si | Excel Augmented SI (column D) |
+ premium | Recalculated premium from rack logic |
+ si_enhancement_date | Excel Date of SI Enhancement (column E) |
+
+
+
+
+ Sets files.status = success when the loop completes. Skipped rows (duplicate pending SI, missing member)
+ are logged only — the file still succeeds.
+
+
+SI Enhancement Excel columns
+
+
+
+ | Col | Header | Required | Notes |
|---|
+
+
+ | A | S.No | Yes | |
+ | B | EMP ID | Yes | |
+ | C | NAME OF EMP/DEP | Yes | Must match DB |
+ | D | Augmented SI | Yes | New SI; validated via check_si |
+ | E | Date of SI Enhancement | Yes | d-M-Y |
+
+
+
+Row layout examples
+
+Enhance Self SI — one row:
+
+
+
+ | EMP ID | NAME | Augmented SI | Date of SI Enhancement |
|---|
+
+
+ | EMP001 | Raj Kumar | 1000000 | 19-May-2026 |
+
+
+
+Enhance spouse only — separate row (premium uses that member’s relationship for rack selection):
+
+
+
+ | EMP ID | NAME | Augmented SI | Date of SI Enhancement |
|---|
+
+
+ | EMP001 | Priya Kumar | 500000 | 19-May-2026 |
+
+
+
+Developer steps
+
+
+ - Confirm slab/rack rates exist for the client policy (same as inception).
+ - Upload with
upload-action-type=si_enhancement; note file_id.
+ - On validation failure, check
/employee/excel_error/{file_id} — codes 4 (SI/slab) or 10 (member missing).
+ - After success, query
emp_endorsement where file_id = upload id, actions = 'si', status = 'pending' — expect up to 3 rows per member (same group_key).
+ - Compare
new_value on basic_cover_si and premium to Excel and rack expectations.
+
+
+Common pitfalls
+
+
+ - Slab / rack not configured — format step or premium calc fails; relationship must map to a non-zero rack key.
+ - Augmented SI vs slab —
check_si in step 1 must pass before the job runs.
+ - Pending SI already exists — duplicate upload for same member skipped until prior endorsement cleared.
+ - Per-member rows — enhancing whole family requires one row per member (unlike deletion Self = whole family).
+ - File success vs rows —
files.status = success does not guarantee every row created endorsements.
+ - Not live SI update —
employee_polices.basic_cover_si changes after endorsement processing.
+
+
+
+ Related:
+ Inception,
+ Correction,
+ EB rack rate calculation.
+
diff --git a/app/Views/employee_data_list.php b/app/Views/employee_data_list.php
index 9097d532..bc7408b2 100755
--- a/app/Views/employee_data_list.php
+++ b/app/Views/employee_data_list.php
@@ -361,6 +361,12 @@ $gst_total = 0;
Re-Generate E-Card
+
+ Initiate Wellness Onboard
+
+ Reset Wellness Onboard
+
+
|
diff --git a/app/Views/employee_list.php b/app/Views/employee_list.php
index a03e40e4..cb3e0ea8 100755
--- a/app/Views/employee_list.php
+++ b/app/Views/employee_list.php
@@ -81,7 +81,7 @@
-
@@ -90,7 +90,7 @@