@platform-modules/foreign-ministry 1.3.334 → 1.3.336

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

@@ -0,0 +1,1405 @@
+/**
+ * FM standard bilingual workflow/chat message builder.
+ *
+ * All services MUST use these helpers (never hardcode message strings).
+ * Templates live in workflow-chat-i18n.json; dynamic values use parallel EN/AR params.
+ */
+import catalog from './workflow-chat-i18n.json';
+
+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>;
+};
+
+/** Master-data fields with English + Arabic columns (roles, departments, sections, users). */
+export type BilingualActorNames = {
+  roleName?: string | null;
+  roleArabicName?: string | null;
+  deptName?: string | null;
+  deptArabicName?: string | null;
+  sectionName?: string | null;
+  sectionArabicName?: string | null;
+  userName?: string | null;
+  userArabicName?: string | null;
+  employeeId?: string | number | null;
+};
+
+export type WorkflowMessageAction =
+  | 'request_submitted'
+  | 'notification_sent_pending'
+  | 'notification_sent_successfully'
+  | 'approval_in_progress'
+  | 'approval_pending'
+  | 'approved'
+  | 'rejected'
+  | 'returned_for_modification'
+  | 'approval_pending_update';
+
+export type ChatMessageAction =
+  | 'cancellation_submitted'
+  | 'request_submitted'
+  | 'request_received'
+  | 'approved'
+  | 'rejected'
+  | 'returned_for_modification';
+
+export type WorkflowMessageContext = BilingualActorNames & {
+  action: WorkflowMessageAction;
+  /** First human approval step → "in progress"; later steps → "pending". */
+  isFirstApprovalStep?: boolean;
+  comment?: string | null;
+};
+
+export type ChatMessageContext = BilingualActorNames & {
+  action: ChatMessageAction;
+  comment?: string | null;
+};
+
+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>;
+
+export function getWorkflowChatI18nCatalog(): WorkflowChatI18nCatalog {
+  return catalog as WorkflowChatI18nCatalog;
+}
+
+function interpolate(template: string, params: Record<string, string> = {}): string {
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key: string) => params[key] ?? '');
+}
+
+/** Arabic DB column preferred; English fallback so AR keeps identical structure to EN. */
+export function resolveBilingualName(
+  englishName?: string | null,
+  arabicName?: string | null,
+): string {
+  const ar = arabicName?.trim();
+  if (ar) return ar;
+  return englishName?.trim() || '';
+}
+
+export function pickLocalizedName(
+  englishName?: string | null,
+  arabicName?: string | null,
+  fallback = '',
+): string {
+  return resolveBilingualName(englishName, arabicName) || fallback;
+}
+
+/** @deprecated Use resolveBilingualName */
+export function pickArabicName(arabicName?: string | null): string {
+  return arabicName?.trim() || '';
+}
+
+function joinLabels(...parts: Array<string | null | undefined>): string {
+  return parts.map((p) => p?.trim()).filter(Boolean).join(' - ');
+}
+
+/** Build parallel EN / AR actor label from role OR dept+section. */
+export function resolveActorDisplayNames(actors: BilingualActorNames): { en: string; ar: string } {
+  if (actors.roleName?.trim()) {
+    const en = actors.roleName.trim();
+    return { en, ar: resolveBilingualName(en, actors.roleArabicName) };
+  }
+  const en = joinLabels(actors.deptName, actors.sectionName);
+  const ar = joinLabels(
+    resolveBilingualName(actors.deptName, actors.deptArabicName),
+    resolveBilingualName(actors.sectionName, actors.sectionArabicName),
+  );
+  return { en, ar };
+}
+
+/** @deprecated Use resolveActorDisplayNames */
+export function joinDeptSectionBilingualLabels(
+  deptEn?: string | null,
+  deptAr?: string | null,
+  sectEn?: string | null,
+  sectAr?: string | null,
+): { en: string; ar: string } {
+  return resolveActorDisplayNames({
+    deptName: deptEn,
+    deptArabicName: deptAr,
+    sectionName: sectEn,
+    sectionArabicName: sectAr,
+  });
+}
+
+/** @deprecated Use resolveActorDisplayNames */
+export function joinDeptSectionArabicLabels(
+  deptArabic?: string | null,
+  sectionArabic?: string | null,
+): string {
+  return joinLabels(deptArabic, sectionArabic);
+}
+
+export function formatWorkflowCommentSuffix(comment?: string | null): string {
+  const text = comment?.trim();
+  return text ? `: ${text}` : '';
+}
+
+export function formatChatCommentSuffix(comment?: string | null): string {
+  const text = comment?.trim();
+  return text ? ` - ${text}` : '';
+}
+
+/** Core renderer — always pass explicit EN and AR param objects with the same keys. */
+export function renderSynchronizedWorkflowMessage(
+  templateKey: string,
+  enParams: Record<string, string>,
+  arParams: Record<string, string>,
+): BilingualText {
+  const tpl = WORKFLOW_TEMPLATES[templateKey];
+  if (!tpl) return { en: templateKey, ar: templateKey };
+  return {
+    en: interpolate(tpl.en, enParams),
+    ar: interpolate(tpl.ar, arParams),
+  };
+}
+
+export function renderSynchronizedChatMessage(
+  templateKey: string,
+  enParams: Record<string, string>,
+  arParams: Record<string, string>,
+): BilingualText {
+  const tpl = CHAT_TEMPLATES[templateKey];
+  if (!tpl) return { en: templateKey, ar: templateKey };
+  return {
+    en: interpolate(tpl.en, enParams),
+    ar: interpolate(tpl.ar, arParams),
+  };
+}
+
+export function buildBilingualFromTemplate(
+  templateCatalog: Record<string, BilingualText>,
+  key: string,
+  params: Record<string, string> = {},
+  arParams?: Record<string, string>,
+): BilingualText {
+  const tpl = templateCatalog[key];
+  if (!tpl) return { en: key, ar: key };
+  const arabicParams = arParams ?? params;
+  return {
+    en: interpolate(tpl.en, params),
+    ar: interpolate(tpl.ar, arabicParams),
+  };
+}
+
+export function workflowTemplate(
+  key: string,
+  params: Record<string, string> = {},
+  arParams?: Record<string, string>,
+): BilingualText {
+  return buildBilingualFromTemplate(WORKFLOW_TEMPLATES, key, params, arParams);
+}
+
+export function chatTemplate(
+  key: string,
+  params: Record<string, string> = {},
+  arParams?: Record<string, string>,
+): BilingualText {
+  return buildBilingualFromTemplate(CHAT_TEMPLATES, key, params, arParams);
+}
+
+/**
+ * Standard entry point for workflow `content` + `content_ar`.
+ * Use for every workflow log insert/update across all CAA modules.
+ */
+export function buildSynchronizedWorkflowMessage(ctx: WorkflowMessageContext): BilingualText {
+  const commentWf = formatWorkflowCommentSuffix(ctx.comment);
+  const { en: actorEn, ar: actorAr } = resolveActorDisplayNames(ctx);
+
+  switch (ctx.action) {
+    case 'request_submitted':
+      return workflowTemplate('request_submitted');
+    case 'notification_sent_pending':
+      return workflowTemplate('notification_sent_pending');
+    case 'notification_sent_successfully':
+      return workflowTemplate('notification_sent_successfully');
+    case 'approval_in_progress':
+      return actorEn
+        ? renderSynchronizedWorkflowMessage(
+            'request_approval_in_progress_from',
+            { name: actorEn },
+            { name: actorAr },
+          )
+        : workflowTemplate('request_approval_in_progress');
+    case 'approval_pending':
+      return actorEn
+        ? renderSynchronizedWorkflowMessage(
+            'request_approval_pending_from',
+            { name: actorEn },
+            { name: actorAr },
+          )
+        : workflowTemplate('request_approval_pending');
+    case 'approved':
+      return actorEn
+        ? renderSynchronizedWorkflowMessage(
+            'request_approved_by',
+            { name: actorEn, comment: commentWf },
+            { name: actorAr, comment: commentWf },
+          )
+        : renderSynchronizedWorkflowMessage(
+            'request_approved',
+            { comment: commentWf },
+            { comment: commentWf },
+          );
+    case 'rejected':
+      return actorEn
+        ? renderSynchronizedWorkflowMessage(
+            'request_rejected_by',
+            { name: actorEn, comment: commentWf },
+            { name: actorAr, comment: commentWf },
+          )
+        : renderSynchronizedWorkflowMessage(
+            'request_rejected',
+            { comment: commentWf },
+            { comment: commentWf },
+          );
+    case 'returned_for_modification':
+      return actorEn
+        ? renderSynchronizedWorkflowMessage(
+            'request_returned_for_modification_by',
+            { name: actorEn, comment: commentWf },
+            { name: actorAr, comment: commentWf },
+          )
+        : renderSynchronizedWorkflowMessage(
+            'request_returned_for_modification',
+            { comment: commentWf },
+            { comment: commentWf },
+          );
+    case 'approval_pending_update':
+      return actorEn
+        ? renderSynchronizedWorkflowMessage(
+            'request_approval_pending_from',
+            { name: actorEn, comment: commentWf },
+            { name: actorAr, comment: commentWf },
+          )
+        : renderSynchronizedWorkflowMessage(
+            'request_approval_pending',
+            { comment: commentWf },
+            { comment: commentWf },
+          );
+    default:
+      return workflowTemplate('request_submitted');
+  }
+}
+
+/**
+ * Standard entry point for chat `message` + `message_ar`.
+ * Use for every chat insert/update across all CAA modules.
+ */
+export function buildSynchronizedChatMessage(ctx: ChatMessageContext): BilingualText {
+  const commentChat = formatChatCommentSuffix(ctx.comment);
+
+  switch (ctx.action) {
+    case 'cancellation_submitted': {
+      const userEn = ctx.userName?.trim() || 'Unknown User';
+      const userAr = resolveBilingualName(userEn, ctx.userArabicName);
+      const employeeId = String(ctx.employeeId ?? 'N/A');
+      return chatTemplate(
+        'cancellation_submitted_by',
+        { userName: userEn, employeeId },
+        { 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':
+    case 'rejected':
+    case 'returned_for_modification': {
+      const roleEn = ctx.roleName?.trim() || 'Unknown Role';
+      const roleAr = resolveBilingualName(roleEn, ctx.roleArabicName);
+      const key =
+        ctx.action === 'approved'
+          ? 'request_approved_by_role'
+          : ctx.action === 'rejected'
+            ? 'request_rejected_by_role'
+            : 'request_returned_for_modification_by_role';
+      return renderSynchronizedChatMessage(
+        key,
+        { roleName: roleEn, comment: commentChat },
+        { roleName: roleAr, comment: commentChat },
+      );
+    }
+    default:
+      return chatTemplate('request_received');
+  }
+}
+
+// ─── 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 (message column). */
+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),
+  };
+}
+
+/** Bilingual chat insert fields for models using `content` column (Leave, Financial, etc.). */
+export function toContentChatPersistFields(
+  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: resolveChatStatusAr(status),
+  };
+}
+
+export function buildApprovalWorkflowContent(params: {
+  status: 'Approved' | 'Rejected' | 'Returned for Modification' | 'Pending' | string;
+  roleName?: string | null;
+  roleArabicName?: string | null;
+  comment?: string | null;
+}): BilingualText {
+  const status = params.status;
+  let action: WorkflowMessageAction;
+  if (status === 'Approved') action = 'approved';
+  else if (status === 'Rejected') action = 'rejected';
+  else if (status === 'Returned for Modification') action = 'returned_for_modification';
+  else action = 'approval_pending_update';
+
+  return buildSynchronizedWorkflowMessage({
+    action,
+    roleName: params.roleName,
+    roleArabicName: params.roleArabicName,
+    comment: params.comment,
+  });
+}
+
+export function buildHumanApprovalWorkflowContent(params: {
+  isFirst: boolean;
+  roleName?: string | null;
+  roleArabicName?: string | null;
+  deptName?: string | null;
+  deptArabicName?: string | null;
+  sectionName?: string | null;
+  sectionArabicName?: string | null;
+}): BilingualText {
+  return buildSynchronizedWorkflowMessage({
+    action: params.isFirst ? 'approval_in_progress' : 'approval_pending',
+    roleName: params.roleName,
+    roleArabicName: params.roleArabicName,
+    deptName: params.deptName,
+    deptArabicName: params.deptArabicName,
+    sectionName: params.sectionName,
+    sectionArabicName: params.sectionArabicName,
+  });
+}
+
+export function buildApprovalChatMessage(params: {
+  status: 'Approved' | 'Rejected' | 'Returned for Modification' | string;
+  roleName?: string | null;
+  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';
+
+  return buildSynchronizedChatMessage({
+    action,
+    roleName: params.roleName,
+    roleArabicName: params.roleArabicName,
+    comment: params.comment,
+  });
+}
+
+// ─── 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 });
+}
+
+function formatNotificationCommentSuffix(comment?: string | null): string {
+  const text = comment?.trim();
+  return text ? `. Reason: ${text}` : '';
+}
+
+function formatNotificationCommentSuffixAr(comment?: string | null): string {
+  const text = comment?.trim();
+  return text ? `. السبب: ${text}` : '';
+}
+
+/** Standard FM notification title + body for workflow events. */
+export function buildFmNotificationContent(params: {
+  event:
+    | 'submitted'
+    | 'received_for_approval'
+    | 'approved'
+    | 'approved_intermediate'
+    | 'rejected'
+    | 'approval_required';
+  serviceLabel: string;
+  serviceLabelAr?: string | null;
+  requestId: number | string;
+  level?: number | string | null;
+  pendingCount?: number | string | null;
+  comment?: string | null;
+}): { title: BilingualText; body: BilingualText } {
+  const serviceLabel = params.serviceLabel?.trim() || 'Request';
+  const serviceLabelAr = params.serviceLabelAr?.trim() || serviceLabel;
+  const requestId = String(params.requestId);
+  const level = String(params.level ?? '');
+  const pendingCount = String(params.pendingCount ?? '0');
+  const commentEn = formatNotificationCommentSuffix(params.comment);
+  const commentAr = formatNotificationCommentSuffixAr(params.comment);
+
+  switch (params.event) {
+    case 'submitted':
+      return {
+        title: renderSynchronizedNotificationMessage('fm_request_submitted_title', {}, {}),
+        body: renderSynchronizedNotificationMessage(
+          'fm_request_submitted_body',
+          { serviceLabel, requestId },
+          { serviceLabelAr, requestId },
+        ),
+      };
+    case 'received_for_approval':
+      return {
+        title: renderSynchronizedNotificationMessage('fm_request_received_title', {}, {}),
+        body: renderSynchronizedNotificationMessage(
+          'fm_request_received_body',
+          { serviceLabel, requestId },
+          { serviceLabelAr, requestId },
+        ),
+      };
+    case 'approved':
+      return {
+        title: renderSynchronizedNotificationMessage('fm_request_approved_title', {}, {}),
+        body: renderSynchronizedNotificationMessage(
+          'fm_request_approved_body',
+          { serviceLabel, requestId, comment: commentEn },
+          { serviceLabelAr, requestId, comment: commentAr },
+        ),
+      };
+    case 'approved_intermediate':
+      return {
+        title: renderSynchronizedNotificationMessage(
+          'fm_level_approved_title',
+          { level },
+          { level },
+        ),
+        body: renderSynchronizedNotificationMessage(
+          'fm_request_approved_intermediate_body',
+          { serviceLabel, requestId, level, pendingCount, comment: commentEn },
+          { serviceLabelAr, requestId, level, pendingCount, comment: commentAr },
+        ),
+      };
+    case 'rejected':
+      return {
+        title: renderSynchronizedNotificationMessage('fm_request_rejected_title', {}, {}),
+        body: renderSynchronizedNotificationMessage(
+          'fm_request_rejected_body',
+          { serviceLabel, requestId, comment: commentEn },
+          { serviceLabelAr, requestId, comment: commentAr },
+        ),
+      };
+    case 'approval_required':
+    default:
+      return {
+        title: level
+          ? renderSynchronizedNotificationMessage(
+              'fm_approval_required_level_title',
+              { level },
+              { level },
+            )
+          : renderSynchronizedNotificationMessage('fm_approval_required_title', {}, {}),
+        body: renderSynchronizedNotificationMessage(
+          'fm_approval_required_body',
+          { serviceLabel, requestId, level },
+          { serviceLabelAr, requestId, level },
+        ),
+      };
+  }
+}
+
+/** Build FM notification `content` JSON with bilingual title/data fields. */
+export function buildFmNotificationPayload(params: {
+  event:
+    | 'submitted'
+    | 'received_for_approval'
+    | 'approved'
+    | 'approved_intermediate'
+    | 'rejected'
+    | 'approval_required';
+  serviceLabel: string;
+  serviceLabelAr?: string | null;
+  requestId: number | string;
+  requestType: string;
+  status: string;
+  level?: number | string | null;
+  pendingCount?: number | string | null;
+  comment?: string | null;
+  bypassedLevels?: string | null;
+  extra?: Record<string, unknown>;
+}): Record<string, unknown> {
+  const bilingual = buildFmNotificationContent(params);
+  return {
+    title: bilingual.title.en,
+    title_ar: bilingual.title.ar,
+    data: bilingual.body.en,
+    data_ar: bilingual.body.ar,
+    requestId: params.requestId,
+    requestType: params.requestType,
+    status: params.status,
+    level: params.level ?? null,
+    comment: params.comment ?? '',
+    bypassedLevels: params.bypassedLevels ?? null,
+    timestamp: new Date().toISOString(),
+    ...(params.extra ?? {}),
+  };
+}
+
+// ─── Status labels ───────────────────────────────────────────────────────────
+
+export function resolveWorkflowStatusAr(status: string | null | undefined): string | null {
+  if (status == null || status === '') return null;
+  return WORKFLOW_STATUS_LABELS[status] ?? status;
+}
+
+export function resolveChatStatusAr(status: string | null | undefined): string | null {
+  if (status == null || status === '') return null;
+  return CHAT_STATUS_LABELS[status] ?? status;
+}
+
+// ─── Legacy row enrichment (read API) ────────────────────────────────────────
+
+/** 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();
+
+  for (const tpl of Object.values(WORKFLOW_TEMPLATES)) {
+    if (tpl.en === normalized) return tpl.ar;
+  }
+
+  const commentIdx = normalized.indexOf(': ');
+  if (commentIdx > 0) {
+    const baseEn = normalized.slice(0, commentIdx).trim();
+    const commentText = normalized.slice(commentIdx + 2).trim();
+    const commentSuffix = formatWorkflowCommentSuffix(commentText);
+
+    for (const tpl of Object.values(WORKFLOW_TEMPLATES)) {
+      if (!tpl.en.includes('{{comment}}')) continue;
+      const withoutComment = tpl.en.replace('{{comment}}', '');
+      if (withoutComment.includes('{{name}}')) {
+        const staticPrefix = withoutComment.replace('{{name}}', '').trim();
+        if (baseEn.startsWith(staticPrefix)) {
+          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 });
+      }
+    }
+  }
+
+  const inProgressPrefix = WORKFLOW_TEMPLATES.request_approval_in_progress_from?.en.split('{{name}}')[0].trim();
+  if (inProgressPrefix && normalized.startsWith(inProgressPrefix)) {
+    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 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,
+  actors?: BilingualActorNames,
+): string | null {
+  if (message == null || message.trim() === '') return null;
+  const normalized = message.trim();
+
+  for (const tpl of Object.values(CHAT_TEMPLATES)) {
+    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(' - ');
+    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;
+}
+
+/** Generic workflow log enricher — use in all module repositories. */
+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, actors),
+    status_ar: log.status_ar ?? resolveWorkflowStatusAr(status),
+  };
+}
+
+/** Generic chat enricher — use in all module repositories. Handles `message` or `content` column. */
+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)
+      : chat.content != null
+        ? String(chat.content)
+        : null;
+  const actors = extractBilingualActorsFromRecord(chat);
+  const resolvedAr = chat.message_ar ?? chat.content_ar ?? resolveChatMessageAr(message, actors);
+  return {
+    ...chat,
+    message_ar: chat.message_ar ?? (chat.message != null ? resolvedAr : chat.message_ar),
+    content_ar: chat.content_ar ?? (chat.content != null ? resolvedAr : chat.content_ar),
+    status_ar: chat.status_ar ?? resolveChatStatusAr(status),
+  };
+}
+
+/** @deprecated Use enrichWorkflowLog */
+export const enrichCancellationWorkflowLog = enrichWorkflowLog;
+
+/** @deprecated Use enrichChatMessage */
+export const enrichCancellationChatMessage = enrichChatMessage;