@platform-modules/civil-aviation-authority 2.3.281 → 2.3.290

package/src/i18n/workflow-chat-message.builder.ts

@@ -11,6 +11,7 @@ export type BilingualText = { en: string; ar: string };
 export type WorkflowChatI18nCatalog = {
   workflowTemplates: Record<string, BilingualText>;
   chatTemplates: Record<string, BilingualText>;
+  notificationTemplates?: Record<string, BilingualText>;
   workflowStatusLabels: Record<string, string>;
   chatStatusLabels: Record<string, string>;
 };
@@ -41,6 +42,7 @@ export type WorkflowMessageAction =
 
 export type ChatMessageAction =
   | 'cancellation_submitted'
+  | 'request_submitted'
   | 'request_received'
   | 'approved'
   | 'rejected'
@@ -60,6 +62,7 @@ export type ChatMessageContext = BilingualActorNames & {
 
 const WORKFLOW_TEMPLATES = catalog.workflowTemplates as Record<string, BilingualText>;
 const CHAT_TEMPLATES = catalog.chatTemplates as Record<string, BilingualText>;
+const NOTIFICATION_TEMPLATES = (catalog as { notificationTemplates?: Record<string, BilingualText> }).notificationTemplates ?? {};
 const WORKFLOW_STATUS_LABELS = catalog.workflowStatusLabels as Record<string, string>;
 const CHAT_STATUS_LABELS = catalog.chatStatusLabels as Record<string, string>;
 
@@ -305,6 +308,16 @@ export function buildSynchronizedChatMessage(ctx: ChatMessageContext): Bilingual
         { userName: userAr, employeeId },
       );
     }
+    case 'request_submitted': {
+      const userEn = ctx.userName?.trim() || 'Unknown User';
+      const userAr = resolveBilingualName(userEn, ctx.userArabicName);
+      const employeeId = String(ctx.employeeId ?? 'N/A');
+      return chatTemplate(
+        'request_submitted_by',
+        { userName: userEn, employeeId },
+        { userName: userAr, employeeId },
+      );
+    }
     case 'request_received':
       return chatTemplate('request_received');
     case 'approved':
@@ -331,6 +344,61 @@ export function buildSynchronizedChatMessage(ctx: ChatMessageContext): Bilingual
 
 // ─── Backward-compatible aliases used by Cancellation pilot ───────────────────
 
+/** Standard workflow log UPDATE fields for all CAA module repositories. */
+export function buildWorkflowLogUpdateFields(params: {
+  approvalStatus: string;
+  workflowStatus: string;
+  roleName?: string | null;
+  roleArabicName?: string | null;
+  comment?: string | null;
+}): { content: string; content_ar: string; status: string; status_ar: string | null } {
+  let action: WorkflowMessageAction;
+  if (params.approvalStatus === 'Approved') action = 'approved';
+  else if (params.approvalStatus === 'Rejected') action = 'rejected';
+  else if (params.approvalStatus === 'Returned for Modification') action = 'returned_for_modification';
+  else action = 'approval_pending_update';
+
+  const bilingual = buildSynchronizedWorkflowMessage({
+    action,
+    roleName: params.roleName,
+    roleArabicName: params.roleArabicName,
+    comment: params.comment,
+  });
+
+  return {
+    content: bilingual.en,
+    content_ar: bilingual.ar,
+    status: params.workflowStatus,
+    status_ar: resolveWorkflowStatusAr(params.workflowStatus),
+  };
+}
+
+/** Bilingual workflow insert fields from builder output. */
+export function toWorkflowPersistFields(
+  bilingual: BilingualText,
+  status: string,
+): { content: string; content_ar: string; status: string; status_ar: string | null } {
+  return {
+    content: bilingual.en,
+    content_ar: bilingual.ar,
+    status,
+    status_ar: resolveWorkflowStatusAr(status),
+  };
+}
+
+/** Bilingual chat insert fields from builder output. */
+export function toChatPersistFields(
+  bilingual: BilingualText,
+  status: string,
+): { message: string; message_ar: string; status: string; status_ar: string | null } {
+  return {
+    message: bilingual.en,
+    message_ar: bilingual.ar,
+    status,
+    status_ar: resolveChatStatusAr(status),
+  };
+}
+
 export function buildApprovalWorkflowContent(params: {
   status: 'Approved' | 'Rejected' | 'Returned for Modification' | 'Pending' | string;
   roleName?: string | null;
@@ -378,6 +446,22 @@ export function buildApprovalChatMessage(params: {
   roleArabicName?: string | null;
   comment?: string | null;
 }): BilingualText {
+  if (params.status === 'Closed') {
+    return buildClosedChatMessage({
+      roleName: params.roleName,
+      roleArabicName: params.roleArabicName,
+      comment: params.comment,
+    });
+  }
+  if (params.status === 'Request For Change' || params.status === 'RFC') {
+    return buildRequestForChangeChatMessage({
+      roleName: params.roleName,
+      roleArabicName: params.roleArabicName,
+      comment: params.comment,
+      variant: 'by',
+    });
+  }
+
   let action: ChatMessageAction = 'approved';
   if (params.status === 'Rejected') action = 'rejected';
   else if (params.status === 'Returned for Modification') action = 'returned_for_modification';
@@ -390,6 +474,589 @@ export function buildApprovalChatMessage(params: {
   });
 }
 
+// ─── Specialized chat/workflow builders ─────────────────────────────────────
+
+function formatDotCommentSuffix(comment?: string | null): string {
+  const text = comment?.trim();
+  return text ? `. Comment: ${text}` : '';
+}
+
+function formatColonCommentSuffix(comment?: string | null): string {
+  const text = comment?.trim();
+  return text ? `: ${text}` : '';
+}
+
+function formatReassignCommentSuffix(comment?: string | null): string {
+  const text = comment?.trim();
+  return text ? `:${text}` : '';
+}
+
+export function buildClosedChatMessage(params: {
+  roleName?: string | null;
+  roleArabicName?: string | null;
+  comment?: string | null;
+}): BilingualText {
+  const roleEn = params.roleName?.trim() || 'Unknown Role';
+  const roleAr = resolveBilingualName(roleEn, params.roleArabicName);
+  const comment = formatDotCommentSuffix(params.comment);
+  return renderSynchronizedChatMessage(
+    'request_closed_by_role',
+    { roleName: roleEn, comment },
+    { roleName: roleAr, comment },
+  );
+}
+
+export function buildClosedWorkflowMessage(params: {
+  roleName?: string | null;
+  roleArabicName?: string | null;
+  comment?: string | null;
+}): BilingualText {
+  const comment = formatWorkflowCommentSuffix(params.comment);
+  const roleEn = params.roleName?.trim();
+  if (roleEn) {
+    const roleAr = resolveBilingualName(roleEn, params.roleArabicName);
+    return renderSynchronizedWorkflowMessage(
+      'request_closed_by',
+      { name: roleEn, comment },
+      { name: roleAr, comment },
+    );
+  }
+  return renderSynchronizedWorkflowMessage('request_closed', { comment }, { comment });
+}
+
+export function buildRequestForChangeChatMessage(params: {
+  roleName?: string | null;
+  roleArabicName?: string | null;
+  comment?: string | null;
+  variant?: 'by' | 'requested_by';
+}): BilingualText {
+  const roleEn = params.roleName?.trim() || 'Unknown Role';
+  const roleAr = resolveBilingualName(roleEn, params.roleArabicName);
+  const comment =
+    params.variant === 'requested_by'
+      ? formatChatCommentSuffix(params.comment)
+      : formatColonCommentSuffix(params.comment);
+  const key =
+    params.variant === 'requested_by'
+      ? 'request_for_change_requested_by_role'
+      : 'request_for_change_by_role';
+  return renderSynchronizedChatMessage(key, { roleName: roleEn, comment }, { roleName: roleAr, comment });
+}
+
+export function buildAttachmentUploadedChatMessage(fileName: string): BilingualText {
+  const name = fileName?.trim() || 'file';
+  return renderSynchronizedChatMessage('attachment_uploaded', { fileName: name }, { fileName: name });
+}
+
+/** User-typed chat text, or bilingual [Attachment] placeholder when empty. */
+export function buildUserOrAttachmentChatMessage(userMessage?: string | null): BilingualText {
+  const text = userMessage?.trim();
+  if (text) return { en: text, ar: text };
+  return chatTemplate('attachment_placeholder');
+}
+
+export function buildTaskInProgressChatMessage(params: {
+  roleName?: string | null;
+  roleArabicName?: string | null;
+}): BilingualText {
+  const roleEn = params.roleName?.trim() || 'Employee';
+  const roleAr = resolveBilingualName(roleEn, params.roleArabicName);
+  return renderSynchronizedChatMessage(
+    'task_status_in_progress_by_role',
+    { roleName: roleEn },
+    { roleName: roleAr },
+  );
+}
+
+export function buildTaskCompletedChatMessage(params: {
+  roleName?: string | null;
+  roleArabicName?: string | null;
+  comment?: string | null;
+}): BilingualText {
+  const roleEn = params.roleName?.trim() || 'Employee';
+  const roleAr = resolveBilingualName(roleEn, params.roleArabicName);
+  const comment = formatDotCommentSuffix(params.comment);
+  return renderSynchronizedChatMessage(
+    'task_completed_by_role',
+    { roleName: roleEn, comment },
+    { roleName: roleAr, comment },
+  );
+}
+
+export function buildTaskStatusUpdatedChatMessage(status: string, statusAr?: string | null): BilingualText {
+  const statusEn = status?.trim() || 'Updated';
+  const statusArResolved = statusAr?.trim() || resolveChatStatusAr(statusEn) || statusEn;
+  return renderSynchronizedChatMessage(
+    'task_status_updated',
+    { status: statusEn },
+    { status: statusArResolved },
+  );
+}
+
+export function buildItHelpdeskAssignedChatMessage(params: {
+  level: number;
+  assignedRoleName?: string | null;
+  assignedRoleArabicName?: string | null;
+  assignedUserName?: string | null;
+  assignedUserArabicName?: string | null;
+  comment?: string | null;
+}): BilingualText {
+  const assignedRoleEn = params.assignedRoleName?.trim() || 'Role';
+  const assignedRoleAr = resolveBilingualName(assignedRoleEn, params.assignedRoleArabicName);
+  const assignedUserEn = params.assignedUserName?.trim() || 'User';
+  const assignedUserAr = resolveBilingualName(assignedUserEn, params.assignedUserArabicName);
+  const comment = params.comment?.trim() ? ` - ${params.comment.trim()}` : '';
+  const templateKey = params.level === 1 ? 'it_helpdesk_hos_assigned' : 'it_helpdesk_technician_assigned';
+  const enParams: Record<string, string> = {
+    assignedRoleName: assignedRoleEn,
+    assignedUserName: assignedUserEn,
+    comment,
+  };
+  const arParams: Record<string, string> = {
+    assignedRoleName: assignedRoleAr,
+    assignedUserName: assignedUserAr,
+    comment,
+  };
+  if (params.level !== 1) {
+    enParams.level = String(params.level);
+    arParams.level = String(params.level);
+  }
+  return renderSynchronizedChatMessage(templateKey, enParams, arParams);
+}
+
+export function buildItHelpdeskReassignedChatMessage(params: {
+  level: number;
+  approverRoleName?: string | null;
+  approverRoleArabicName?: string | null;
+  reassignedRoleName?: string | null;
+  reassignedRoleArabicName?: string | null;
+  comment?: string | null;
+}): BilingualText {
+  const approverEn = params.approverRoleName?.trim() || 'Role';
+  const approverAr = resolveBilingualName(approverEn, params.approverRoleArabicName);
+  const comment = formatReassignCommentSuffix(params.comment);
+  if (params.level === 1) {
+    const reassignedEn = params.reassignedRoleName?.trim() || 'Role';
+    const reassignedAr = resolveBilingualName(reassignedEn, params.reassignedRoleArabicName);
+    return renderSynchronizedChatMessage(
+      'it_helpdesk_reassigned_to_role',
+      { approverRoleName: approverEn, reassignedRoleName: reassignedEn, comment },
+      { approverRoleName: approverAr, reassignedRoleName: reassignedAr, comment },
+    );
+  }
+  if (params.level === 2) {
+    return renderSynchronizedChatMessage(
+      'it_helpdesk_reassigned_to_l3',
+      { approverRoleName: approverEn, comment },
+      { approverRoleName: approverAr, comment },
+    );
+  }
+  const level = String(params.level);
+  return renderSynchronizedChatMessage(
+    'it_helpdesk_reassigned_generic',
+    { approverRoleName: approverEn, level, comment },
+    { approverRoleName: approverAr, level, comment },
+  );
+}
+
+export function buildRequestSubmittedWithRefChatMessage(params: {
+  requestLabel: string;
+  requestLabelAr?: string | null;
+  requestId: number | string;
+  userName?: string | null;
+  userArabicName?: string | null;
+  employeeId?: string | number | null;
+}): BilingualText {
+  const userEn = params.userName?.trim() || 'Unknown User';
+  const userAr = resolveBilingualName(userEn, params.userArabicName);
+  const labelEn = params.requestLabel?.trim() || 'Request';
+  const labelAr = params.requestLabelAr?.trim() || labelEn;
+  const requestId = String(params.requestId);
+  const employeeId = String(params.employeeId ?? 'N/A');
+  return renderSynchronizedChatMessage(
+    'request_submitted_with_ref',
+    { requestLabel: labelEn, requestId, userName: userEn, employeeId },
+    { requestLabel: labelAr, requestId, userName: userAr, employeeId },
+  );
+}
+
+export function buildSecurityAccessApprovalChatMessage(params: {
+  productLabel: string;
+  productLabelAr?: string | null;
+  requestId: number | string;
+  approvalLevel: number | string;
+  decision: 'approve' | 'reject';
+  comment?: string | null;
+}): BilingualText {
+  const statusWord = params.decision === 'approve' ? 'approved' : 'rejected';
+  const statusWordAr = params.decision === 'approve' ? 'الموافقة على' : 'رفض';
+  const comment = params.comment?.trim() ? ` Comment: ${params.comment.trim()}` : '';
+  const labelEn = params.productLabel?.trim() || 'Security Access';
+  const labelAr = params.productLabelAr?.trim() || labelEn;
+  return renderSynchronizedChatMessage(
+    'security_access_approval_step',
+    {
+      productLabel: labelEn,
+      requestId: String(params.requestId),
+      statusWord,
+      approvalLevel: String(params.approvalLevel),
+      comment,
+      statusWordAr,
+    },
+    {
+      productLabel: labelAr,
+      requestId: String(params.requestId),
+      statusWord,
+      approvalLevel: String(params.approvalLevel),
+      comment,
+      statusWordAr,
+    },
+  );
+}
+
+function renderSynchronizedNotificationMessage(
+  templateKey: string,
+  enParams: Record<string, string>,
+  arParams: Record<string, string>,
+): BilingualText {
+  const tpl = NOTIFICATION_TEMPLATES[templateKey];
+  if (!tpl) return { en: templateKey, ar: templateKey };
+  return {
+    en: interpolate(tpl.en, enParams),
+    ar: interpolate(tpl.ar, arParams),
+  };
+}
+
+function normalizeDisplayValue(value: unknown): string {
+  if (value === undefined || value === null || String(value).trim() === '') return 'Not specified';
+  return String(value);
+}
+
+function normalizeDisplayDate(value: unknown): string {
+  if (value === undefined || value === null || String(value).trim() === '') return 'Not specified';
+  const d = new Date(value as string | number | Date);
+  if (!isNaN(d.getTime())) return d.toISOString().slice(0, 10);
+  return String(value);
+}
+
+export function buildItHelpdeskReassignModifiers(params: {
+  sectionFrom?: number | null;
+  sectionTo?: number | null;
+  departmentFrom?: number | null;
+  departmentTo?: number | null;
+}): { en: string; ar: string } {
+  let en = '';
+  let ar = '';
+  if (
+    params.sectionFrom != null &&
+    params.sectionTo != null &&
+    params.sectionFrom !== params.sectionTo
+  ) {
+    en += ` (Section modified from ${params.sectionFrom} to ${params.sectionTo})`;
+    ar += ` (تم تعديل القسم من ${params.sectionFrom} إلى ${params.sectionTo})`;
+  }
+  if (
+    params.departmentFrom != null &&
+    params.departmentTo != null &&
+    params.departmentFrom !== params.departmentTo
+  ) {
+    en += ` (Department modified from ${params.departmentFrom} to ${params.departmentTo})`;
+    ar += ` (تم تعديل الإدارة من ${params.departmentFrom} إلى ${params.departmentTo})`;
+  }
+  return { en, ar };
+}
+
+export type ItHelpdeskMuscatWorkflowParams =
+  | {
+      variant: 'hos_assigned';
+      approverRoleName: string;
+      approverRoleArabicName?: string | null;
+      assignedRoleName: string;
+      assignedRoleArabicName?: string | null;
+      comment?: string | null;
+    }
+  | {
+      variant: 'technician_assigned';
+      level: number;
+      approverRoleName: string;
+      approverRoleArabicName?: string | null;
+      comment?: string | null;
+    }
+  | {
+      variant: 'reassigned_technician' | 'reassigned_l3' | 'reassigned_generic';
+      approverRoleName: string;
+      approverRoleArabicName?: string | null;
+      level?: number;
+      comment?: string | null;
+      modifiers?: { en: string; ar: string };
+    }
+  | {
+      variant: 'closed_level1' | 'closed_level2';
+      approverRoleName: string;
+      approverRoleArabicName?: string | null;
+      comment?: string | null;
+    }
+  | {
+      variant: 'l3_approved' | 'l3_rejected';
+      roleName: string;
+      roleArabicName?: string | null;
+      userName: string;
+      userArabicName?: string | null;
+      comment?: string | null;
+    }
+  | {
+      variant: 'level_approved';
+      level: number;
+      approverRoleName: string;
+      approverRoleArabicName?: string | null;
+      comment?: string | null;
+    }
+  | {
+      variant: 'rejected' | 'l3_step_rejected';
+      approverRoleName: string;
+      approverRoleArabicName?: string | null;
+      comment?: string | null;
+    }
+  | {
+      variant: 'generic_status';
+      approverRoleName: string;
+      approverRoleArabicName?: string | null;
+      status: string;
+      comment?: string | null;
+    }
+  | {
+      variant: 'technician_completed' | 'routing_rejected';
+      roleName: string;
+      roleArabicName?: string | null;
+      comment?: string | null;
+    }
+  | { variant: 'routing_resolved' };
+
+export function buildItHelpdeskMuscatWorkflowLog(params: ItHelpdeskMuscatWorkflowParams): BilingualText {
+  const comment = formatColonCommentSuffix(
+    'comment' in params ? params.comment : undefined,
+  );
+  const modifiers = 'modifiers' in params && params.modifiers ? params.modifiers : { en: '', ar: '' };
+
+  switch (params.variant) {
+    case 'hos_assigned': {
+      const approverEn = params.approverRoleName.trim();
+      const approverAr = resolveBilingualName(approverEn, params.approverRoleArabicName);
+      const assignedEn = params.assignedRoleName.trim();
+      const assignedAr = resolveBilingualName(assignedEn, params.assignedRoleArabicName);
+      return renderSynchronizedWorkflowMessage(
+        'it_helpdesk_wf_hos_assigned',
+        { approverRoleName: approverEn, assignedRoleName: assignedEn, comment },
+        { approverRoleName: approverAr, assignedRoleName: assignedAr, comment },
+      );
+    }
+    case 'technician_assigned': {
+      const approverEn = params.approverRoleName.trim();
+      const approverAr = resolveBilingualName(approverEn, params.approverRoleArabicName);
+      return renderSynchronizedWorkflowMessage(
+        'it_helpdesk_wf_technician_assigned',
+        { level: String(params.level), approverRoleName: approverEn, comment },
+        { level: String(params.level), approverRoleName: approverAr, comment },
+      );
+    }
+    case 'reassigned_technician': {
+      const approverEn = params.approverRoleName.trim();
+      const approverAr = resolveBilingualName(approverEn, params.approverRoleArabicName);
+      return renderSynchronizedWorkflowMessage(
+        'it_helpdesk_wf_reassigned_technician',
+        { approverRoleName: approverEn, comment, modifiers: modifiers.en },
+        { approverRoleName: approverAr, comment, modifiers: modifiers.ar },
+      );
+    }
+    case 'reassigned_l3': {
+      const approverEn = params.approverRoleName.trim();
+      const approverAr = resolveBilingualName(approverEn, params.approverRoleArabicName);
+      return renderSynchronizedWorkflowMessage(
+        'it_helpdesk_wf_reassigned_l3',
+        { approverRoleName: approverEn, comment, modifiers: modifiers.en },
+        { approverRoleName: approverAr, comment, modifiers: modifiers.ar },
+      );
+    }
+    case 'reassigned_generic': {
+      const approverEn = params.approverRoleName.trim();
+      const approverAr = resolveBilingualName(approverEn, params.approverRoleArabicName);
+      const level = String(params.level ?? '');
+      return renderSynchronizedWorkflowMessage(
+        'it_helpdesk_wf_reassigned_generic',
+        { approverRoleName: approverEn, level, comment, modifiers: modifiers.en },
+        { approverRoleName: approverAr, level, comment, modifiers: modifiers.ar },
+      );
+    }
+    case 'closed_level1': {
+      const approverEn = params.approverRoleName.trim();
+      const approverAr = resolveBilingualName(approverEn, params.approverRoleArabicName);
+      return renderSynchronizedWorkflowMessage(
+        'it_helpdesk_wf_closed_request',
+        { approverRoleName: approverEn, comment },
+        { approverRoleName: approverAr, comment },
+      );
+    }
+    case 'closed_level2': {
+      const approverEn = params.approverRoleName.trim();
+      const approverAr = resolveBilingualName(approverEn, params.approverRoleArabicName);
+      return renderSynchronizedWorkflowMessage(
+        'it_helpdesk_wf_closed_request_cap',
+        { approverRoleName: approverEn, comment },
+        { approverRoleName: approverAr, comment },
+      );
+    }
+    case 'l3_approved': {
+      const roleEn = params.roleName.trim();
+      const roleAr = resolveBilingualName(roleEn, params.roleArabicName);
+      const userEn = params.userName.trim();
+      const userAr = resolveBilingualName(userEn, params.userArabicName);
+      return renderSynchronizedWorkflowMessage(
+        'it_helpdesk_wf_l3_approved_by',
+        { roleName: roleEn, userName: userEn, comment },
+        { roleName: roleAr, userName: userAr, comment },
+      );
+    }
+    case 'l3_rejected': {
+      const roleEn = params.roleName.trim();
+      const roleAr = resolveBilingualName(roleEn, params.roleArabicName);
+      const userEn = params.userName.trim();
+      const userAr = resolveBilingualName(userEn, params.userArabicName);
+      return renderSynchronizedWorkflowMessage(
+        'it_helpdesk_wf_l3_rejected_by',
+        { roleName: roleEn, userName: userEn, comment },
+        { roleName: roleAr, userName: userAr, comment },
+      );
+    }
+    case 'level_approved': {
+      const approverEn = params.approverRoleName.trim();
+      const approverAr = resolveBilingualName(approverEn, params.approverRoleArabicName);
+      return renderSynchronizedWorkflowMessage(
+        'it_helpdesk_wf_level_approved',
+        { level: String(params.level), approverRoleName: approverEn, comment },
+        { level: String(params.level), approverRoleName: approverAr, comment },
+      );
+    }
+    case 'rejected':
+    case 'l3_step_rejected': {
+      const key =
+        params.variant === 'l3_step_rejected'
+          ? 'it_helpdesk_wf_l3_step_rejected'
+          : 'it_helpdesk_wf_rejected';
+      const roleEn = params.approverRoleName.trim();
+      const roleAr = resolveBilingualName(roleEn, params.approverRoleArabicName);
+      return renderSynchronizedWorkflowMessage(
+        key,
+        { approverRoleName: roleEn, roleName: roleEn, comment },
+        { approverRoleName: roleAr, roleName: roleAr, comment },
+      );
+    }
+    case 'generic_status': {
+      const approverEn = params.approverRoleName.trim();
+      const approverAr = resolveBilingualName(approverEn, params.approverRoleArabicName);
+      const statusEn = params.status.toLowerCase();
+      const statusAr = resolveChatStatusAr(params.status) ?? statusEn;
+      return renderSynchronizedWorkflowMessage(
+        'it_helpdesk_wf_status_by_role',
+        { status: statusEn, statusAr, approverRoleName: approverEn, comment },
+        { status: statusEn, statusAr, approverRoleName: approverAr, comment },
+      );
+    }
+    case 'technician_completed': {
+      const roleEn = params.roleName.trim();
+      const roleAr = resolveBilingualName(roleEn, params.roleArabicName);
+      return renderSynchronizedWorkflowMessage(
+        'it_helpdesk_wf_technician_completed',
+        { roleName: roleEn, comment },
+        { roleName: roleAr, comment },
+      );
+    }
+    case 'routing_rejected':
+      return renderSynchronizedWorkflowMessage(
+        'it_helpdesk_wf_routing_rejected',
+        { comment },
+        { comment },
+      );
+    case 'routing_resolved':
+      return workflowTemplate('it_helpdesk_wf_routing_resolved');
+    default:
+      return workflowTemplate('request_submitted');
+  }
+}
+
+export type LogisticsActualReturnParams = {
+  requestId?: number | string | null;
+  requestTypeLabel?: string | null;
+  actual_return_date?: string | Date | null;
+  actual_vehicle_return_time?: string | null;
+  reason?: string | null;
+};
+
+export function buildLogisticsActualReturnChatMessage(params: {
+  roleName: string;
+  roleArabicName?: string | null;
+  returnDetails: LogisticsActualReturnParams;
+}): BilingualText {
+  const roleEn = params.roleName.trim() || 'Unknown Role';
+  const roleAr = resolveBilingualName(roleEn, params.roleArabicName);
+  const date = normalizeDisplayDate(params.returnDetails.actual_return_date);
+  const time = normalizeDisplayValue(params.returnDetails.actual_vehicle_return_time);
+  const reason = normalizeDisplayValue(params.returnDetails.reason);
+  return renderSynchronizedChatMessage(
+    'logistics_actual_return_updated',
+    { roleName: roleEn, date, time, reason },
+    { roleName: roleAr, date, time, reason },
+  );
+}
+
+export function buildLogisticsActualReturnNotificationBody(
+  params: LogisticsActualReturnParams,
+): BilingualText {
+  const requestLabel = params.requestTypeLabel
+    ? `${params.requestTypeLabel} Request`
+    : 'Vehicle Request';
+  const requestLabelAr = params.requestTypeLabel
+    ? `طلب ${params.requestTypeLabel}`
+    : 'طلب المركبة';
+  const requestId = normalizeDisplayValue(params.requestId);
+  const en = [
+    `${requestLabel} #${requestId}`,
+    `Actual Return Date: ${normalizeDisplayDate(params.actual_return_date)}`,
+    `Actual Return Time: ${normalizeDisplayValue(params.actual_vehicle_return_time)}`,
+    `Reason: ${normalizeDisplayValue(params.reason)}`,
+  ].join('\n');
+  const ar = [
+    `${requestLabelAr} رقم ${requestId}`,
+    `تاريخ الإرجاع الفعلي: ${normalizeDisplayDate(params.actual_return_date)}`,
+    `وقت الإرجاع الفعلي: ${normalizeDisplayValue(params.actual_vehicle_return_time)}`,
+    `السبب: ${normalizeDisplayValue(params.reason)}`,
+  ].join('\n');
+  return { en, ar };
+}
+
+export function buildLogisticsActualReturnNotificationTitle(
+  params: LogisticsActualReturnParams,
+): BilingualText {
+  const requestLabel = params.requestTypeLabel || 'Vehicle';
+  const requestId = String(params.requestId ?? '');
+  return renderSynchronizedNotificationMessage(
+    'logistics_actual_return_title',
+    { requestLabel, requestId },
+    { requestLabel, requestId },
+  );
+}
+
+export function buildItHelpdeskCloseNotificationMessage(params: {
+  requestId: number | string;
+  status: 'Approved' | 'Rejected';
+}): BilingualText {
+  const requestId = String(params.requestId);
+  const key =
+    params.status === 'Rejected'
+      ? 'it_helpdesk_notif_request_rejected'
+      : 'it_helpdesk_notif_request_closed';
+  return renderSynchronizedNotificationMessage(key, { requestId }, { requestId });
+}
+
 // ─── Status labels ───────────────────────────────────────────────────────────
 
 export function resolveWorkflowStatusAr(status: string | null | undefined): string | null {
@@ -404,7 +1071,61 @@ export function resolveChatStatusAr(status: string | null | undefined): string |
 
 // ─── Legacy row enrichment (read API) ────────────────────────────────────────
 
-export function resolveWorkflowContentAr(content: string | null | undefined): string | null {
+/** Pull bilingual actor fields from joined relations on workflow/chat rows. */
+export function extractBilingualActorsFromRecord(
+  record: Record<string, unknown>,
+): BilingualActorNames {
+  const role = (record.approver_role ?? record.role) as Record<string, unknown> | undefined;
+  const user = (record.approver_user ?? record.user) as Record<string, unknown> | undefined;
+  const dept = (record.approver_department ?? record.department) as Record<string, unknown> | undefined;
+  const section = (record.approver_section ?? record.section) as Record<string, unknown> | undefined;
+
+  return {
+    roleName: role?.name != null ? String(role.name) : null,
+    roleArabicName: role?.arabic_name != null ? String(role.arabic_name) : null,
+    deptName: dept?.department_name != null ? String(dept.department_name) : null,
+    deptArabicName: dept?.department_arabic_name != null ? String(dept.department_arabic_name) : null,
+    sectionName: section?.section_name != null ? String(section.section_name) : null,
+    sectionArabicName: section?.section_arabic_name != null ? String(section.section_arabic_name) : null,
+    userName: user?.employee_name != null ? String(user.employee_name) : null,
+    userArabicName: user?.employee_arabic_name != null ? String(user.employee_arabic_name) : null,
+    employeeId: user?.employee_id != null ? String(user.employee_id) : null,
+  };
+}
+
+/** Arabic actor label for workflow templates (role, dept+section, or user). */
+function resolveArabicWorkflowActorName(
+  actors: BilingualActorNames | undefined,
+  parsedEnglishName?: string,
+): string {
+  if (actors) {
+    const { ar } = resolveActorDisplayNames(actors);
+    if (ar) return ar;
+    if (actors.userName?.trim()) {
+      return resolveBilingualName(actors.userName, actors.userArabicName);
+    }
+  }
+  return parsedEnglishName?.trim() || '';
+}
+
+/** Arabic role/user label for chat templates. */
+function resolveArabicChatRoleName(
+  actors: BilingualActorNames | undefined,
+  parsedEnglishRole?: string,
+): string {
+  if (actors?.roleName?.trim()) {
+    return resolveBilingualName(actors.roleName, actors.roleArabicName);
+  }
+  if (actors?.userName?.trim()) {
+    return resolveBilingualName(actors.userName, actors.userArabicName);
+  }
+  return resolveBilingualName(parsedEnglishRole, actors?.roleArabicName);
+}
+
+export function resolveWorkflowContentAr(
+  content: string | null | undefined,
+  actors?: BilingualActorNames,
+): string | null {
   if (content == null || content.trim() === '') return null;
   const normalized = content.trim();
 
@@ -424,8 +1145,9 @@ export function resolveWorkflowContentAr(content: string | null | undefined): st
       if (withoutComment.includes('{{name}}')) {
         const staticPrefix = withoutComment.replace('{{name}}', '').trim();
         if (baseEn.startsWith(staticPrefix)) {
-          const namePart = baseEn.slice(staticPrefix.length).trim();
-          return interpolate(tpl.ar, { name: namePart, comment: commentSuffix });
+          const namePartEn = baseEn.slice(staticPrefix.length).trim();
+          const nameAr = resolveArabicWorkflowActorName(actors, namePartEn);
+          return interpolate(tpl.ar, { name: nameAr, comment: commentSuffix });
         }
       } else if (withoutComment.trim() === baseEn) {
         return interpolate(tpl.ar, { comment: commentSuffix });
@@ -435,19 +1157,24 @@ export function resolveWorkflowContentAr(content: string | null | undefined): st
 
   const inProgressPrefix = WORKFLOW_TEMPLATES.request_approval_in_progress_from?.en.split('{{name}}')[0].trim();
   if (inProgressPrefix && normalized.startsWith(inProgressPrefix)) {
-    const namePart = normalized.slice(inProgressPrefix.length).trim();
-    return interpolate(WORKFLOW_TEMPLATES.request_approval_in_progress_from.ar, { name: namePart });
+    const namePartEn = normalized.slice(inProgressPrefix.length).trim();
+    const nameAr = resolveArabicWorkflowActorName(actors, namePartEn);
+    return interpolate(WORKFLOW_TEMPLATES.request_approval_in_progress_from.ar, { name: nameAr });
   }
   const pendingPrefix = WORKFLOW_TEMPLATES.request_approval_pending_from?.en.split('{{name}}')[0].trim();
   if (pendingPrefix && normalized.startsWith(pendingPrefix)) {
-    const namePart = normalized.slice(pendingPrefix.length).trim();
-    return interpolate(WORKFLOW_TEMPLATES.request_approval_pending_from.ar, { name: namePart });
+    const namePartEn = normalized.slice(pendingPrefix.length).trim();
+    const nameAr = resolveArabicWorkflowActorName(actors, namePartEn);
+    return interpolate(WORKFLOW_TEMPLATES.request_approval_pending_from.ar, { name: nameAr });
   }
 
   return null;
 }
 
-export function resolveChatMessageAr(message: string | null | undefined): string | null {
+export function resolveChatMessageAr(
+  message: string | null | undefined,
+  actors?: BilingualActorNames,
+): string | null {
   if (message == null || message.trim() === '') return null;
   const normalized = message.trim();
 
@@ -455,19 +1182,33 @@ export function resolveChatMessageAr(message: string | null | undefined): string
     if (tpl.en === normalized) return tpl.ar;
   }
 
+  for (const tplKey of ['request_submitted_by', 'cancellation_submitted_by'] as const) {
+    const submittedTpl = CHAT_TEMPLATES[tplKey];
+    if (!submittedTpl) continue;
+    const prefix = submittedTpl.en.split('{{userName}}')[0];
+    if (!normalized.startsWith(prefix)) continue;
+    const afterPrefix = normalized.slice(prefix.length);
+    const parenMatch = afterPrefix.match(/^(.+?) \((.+)\)$/);
+    if (parenMatch) {
+      const userEn = parenMatch[1].trim();
+      const employeeId = parenMatch[2].trim();
+      const userAr = actors?.userName?.trim()
+        ? resolveBilingualName(actors.userName, actors.userArabicName)
+        : resolveBilingualName(userEn, actors?.userArabicName);
+      return interpolate(submittedTpl.ar, { userName: userAr, employeeId });
+    }
+  }
+
   for (const tpl of Object.values(CHAT_TEMPLATES)) {
     if (!tpl.en.includes('{{roleName}}')) continue;
     const prefix = tpl.en.split('{{roleName}}')[0];
     if (!normalized.startsWith(prefix)) continue;
     const rest = normalized.slice(prefix.length);
     const commentIdx = rest.lastIndexOf(' - ');
-    if (commentIdx >= 0) {
-      return interpolate(tpl.ar, {
-        roleName: rest.slice(0, commentIdx),
-        comment: rest.slice(commentIdx),
-      });
-    }
-    return interpolate(tpl.ar, { roleName: rest, comment: '' });
+    const roleNameEn = commentIdx >= 0 ? rest.slice(0, commentIdx) : rest;
+    const commentSuffix = commentIdx >= 0 ? rest.slice(commentIdx) : '';
+    const roleNameAr = resolveArabicChatRoleName(actors, roleNameEn.trim());
+    return interpolate(tpl.ar, { roleName: roleNameAr, comment: commentSuffix });
   }
 
   return null;
@@ -477,9 +1218,10 @@ export function resolveChatMessageAr(message: string | null | undefined): string
 export function enrichWorkflowLog(log: Record<string, unknown>): Record<string, unknown> {
   const status = log.status != null ? String(log.status) : null;
   const content = log.content != null ? String(log.content) : null;
+  const actors = extractBilingualActorsFromRecord(log);
   return {
     ...log,
-    content_ar: log.content_ar ?? resolveWorkflowContentAr(content),
+    content_ar: log.content_ar ?? resolveWorkflowContentAr(content, actors),
     status_ar: log.status_ar ?? resolveWorkflowStatusAr(status),
   };
 }
@@ -488,9 +1230,10 @@ export function enrichWorkflowLog(log: Record<string, unknown>): Record<string,
 export function enrichChatMessage(chat: Record<string, unknown>): Record<string, unknown> {
   const status = chat.status != null ? String(chat.status) : null;
   const message = chat.message != null ? String(chat.message) : null;
+  const actors = extractBilingualActorsFromRecord(chat);
   return {
     ...chat,
-    message_ar: chat.message_ar ?? resolveChatMessageAr(message),
+    message_ar: chat.message_ar ?? resolveChatMessageAr(message, actors),
     status_ar: chat.status_ar ?? resolveChatStatusAr(status),
   };
 }