feat: 完成P10生产硬化与矩阵收口（P10E1-P10G1）

2026-02-10 11:25:18 +08:00
@@ -90,6 +90,29 @@ function getConfig() {
    ocrMaxAttempts: Number(process.env.OCR_MAX_ATTEMPTS ?? 3),
    ocrTimeoutMs: Number(process.env.OCR_TIMEOUT_MS ?? 5000),

+    invoiceVerificationEnabled: process.env.INVOICE_VERIFICATION_ENABLED === "true",
+    verificationProvider: process.env.VERIFICATION_PROVIDER ?? "mock",
+    verificationPollCron: process.env.VERIFICATION_POLL_CRON ?? "* * * * *",
+    verificationMaxAttempts: Number(process.env.VERIFICATION_MAX_ATTEMPTS ?? 3),
+    verificationRetryCooldownSeconds: Number(
+      process.env.VERIFICATION_RETRY_COOLDOWN_SECONDS ?? 60,
+    ),
+    verificationTimeoutMs: Number(process.env.VERIFICATION_TIMEOUT_MS ?? 5000),
+
+    budgetControlMode: process.env.BUDGET_CONTROL_MODE ?? "warn",
+
+    erpSyncEnabled: process.env.ERP_SYNC_ENABLED === "true",
+    erpSyncProvider: process.env.ERP_SYNC_PROVIDER ?? "mock",
+    erpSyncEndpoint: process.env.ERP_SYNC_ENDPOINT ?? "",
+    erpSyncTimeoutMs: Number(process.env.ERP_SYNC_TIMEOUT_MS ?? 5000),
+    erpSyncAuthToken: process.env.ERP_SYNC_AUTH_TOKEN ?? "",
+    travelSyncEnabled: process.env.TRAVEL_SYNC_ENABLED === "true",
+    imNotifierEnabled: process.env.IM_NOTIFIER_ENABLED === "true",
+    integrationOutboxCron: process.env.INTEGRATION_OUTBOX_CRON ?? "* * * * *",
+    integrationOutboxBatchSize: Number(process.env.INTEGRATION_OUTBOX_BATCH_SIZE ?? 20),
+    integrationOutboxMaxAttempts: Number(process.env.INTEGRATION_OUTBOX_MAX_ATTEMPTS ?? 5),
+    integrationOutboxRetrySeconds: Number(process.env.INTEGRATION_OUTBOX_RETRY_SECONDS ?? 120),
+
    invoiceArchiveCron: process.env.INVOICE_ARCHIVE_CRON ?? "30 2 * * *",
    invoiceArchiveUnusedDays: Number(process.env.INVOICE_ARCHIVE_UNUSED_DAYS ?? 90),
    invoiceArchiveBatchSize: Number(process.env.INVOICE_ARCHIVE_BATCH_SIZE ?? 200),
@@ -0,0 +1,124 @@
+const cron = require("node-cron");
+
+const {
+  fetchPendingOutboxEvents,
+  markOutboxFailed,
+  markOutboxProcessing,
+  markOutboxSucceeded,
+} = require("../services/integrations/outbox");
+const { dispatchOutboxEvent } = require("../services/integrations/dispatcher");
+
+async function runIntegrationOutboxOnce(prisma, config, logger) {
+  const items = await fetchPendingOutboxEvents(prisma, {
+    batchSize: config.integrationOutboxBatchSize,
+  });
+
+  let succeeded = 0;
+  let failed = 0;
+
+  for (const item of items) {
+    await markOutboxProcessing(prisma, item.id, null);
+
+    try {
+      await dispatchOutboxEvent({
+        config,
+        eventType: item.event_type,
+        payload: item.payload,
+      });
+      await markOutboxSucceeded(prisma, item.id, null);
+      succeeded += 1;
+    } catch (error) {
+      const retryable = typeof error?.retryable === "boolean" ? error.retryable : true;
+      await markOutboxFailed(prisma, config, item, error, null, { retryable });
+      failed += 1;
+      logger.error(
+        {
+          err: error,
+          retryable,
+          outboxId: item.id,
+          eventType: item.event_type,
+        },
+        "Integration outbox dispatch failed",
+      );
+    }
+  }
+
+  return {
+    total: items.length,
+    succeeded,
+    failed,
+  };
+}
+
+function startIntegrationOutboxJob(fastify) {
+  let running = false;
+
+  const task = cron.schedule(fastify.config.integrationOutboxCron, async () => {
+    if (running) {
+      return;
+    }
+
+    running = true;
+    try {
+      const result = await runIntegrationOutboxOnce(
+        fastify.prisma,
+        fastify.config,
+        fastify.log,
+      );
+      fastify.metrics?.jobRunsTotal?.inc?.({
+        job: "integration.outbox.dispatch",
+        driver: "cron",
+        outcome: "success",
+      });
+      if (result.succeeded > 0) {
+        fastify.metrics?.jobProcessedTotal?.inc?.(
+          {
+            job: "integration.outbox.dispatch",
+            driver: "cron",
+            kind: "succeeded",
+          },
+          result.succeeded,
+        );
+      }
+      if (result.failed > 0) {
+        fastify.metrics?.jobProcessedTotal?.inc?.(
+          {
+            job: "integration.outbox.dispatch",
+            driver: "cron",
+            kind: "failed",
+          },
+          result.failed,
+        );
+      }
+    } catch (error) {
+      fastify.log.error({ err: error }, "Integration outbox job failed");
+      fastify.metrics?.jobRunsTotal?.inc?.({
+        job: "integration.outbox.dispatch",
+        driver: "cron",
+        outcome: "failure",
+      });
+    } finally {
+      running = false;
+    }
+  });
+
+  fastify.addHook("onClose", async () => {
+    task.stop();
+    task.destroy();
+  });
+
+  fastify.log.info(
+    {
+      cron: fastify.config.integrationOutboxCron,
+      batchSize: fastify.config.integrationOutboxBatchSize,
+    },
+    "Integration outbox job scheduled",
+  );
+
+  return task;
+}
+
+module.exports = {
+  runIntegrationOutboxOnce,
+  startIntegrationOutboxJob,
+};
@@ -7,11 +7,14 @@ const { sendData } = require("../utils/reply");
 const { buildAuditLogData } = require("../utils/audit");
 const { compactDateString } = require("../utils/date");
 const { sha256Hex } = require("../utils/crypto");
-const { signPayload, verifyToken } = require("../utils/signedUrl");
 const { toMoneyString } = require("../utils/workflow");
 const { findActiveDelegationForDelegate } = require("../utils/delegation");
 const { isOcrEnabledForType } = require("../services/ocr");
-const { openReadStream, StorageNotFoundError, writeBuffer } = require("../services/storage");
+const { registerInvoiceVerificationRoutes } = require("./invoicePool/verification");
+const { registerInvoicePoolReadRoutes } = require("./invoicePool/read");
+const { normalizeInvoiceResponse } = require("./invoicePool/shared/mappers");
+const { buildInvoiceDetailSelect } = require("./invoicePool/shared/selects");
+const { writeBuffer } = require("../services/storage");

 const MIME_ALLOWLIST = new Set([
  "application/pdf",
@@ -52,13 +55,6 @@ const overrideDuplicateBodySchema = z
  })
  .strict();

-const invoiceListQuerySchema = z.object({
-  page: z.coerce.number().int().min(1).optional(),
-  pageSize: z.coerce.number().int().min(1).max(100).optional(),
-  status: z.enum(["pending_ocr", "ocr_failed", "available", "bound", "archived"]).optional(),
-  ownerScope: z.enum(["own", "all"]).optional(),
-});
-
 const DEDUP_CONSTRAINT_NAMES = new Set([
  "invoice_pool_file_sha256_dedup_ux",
  "invoice_pool_invoice_code_number_dedup_ux",
@@ -148,36 +144,6 @@ function isInvoiceDedupConflict(error) {
  return isFieldBasedDedup(fieldTokens);
 }

-function ensureInvoiceReadableByUser(request, invoice) {
-  const roleCodes = request.employee.roleCodes;
-  if (
-    roleCodes.includes("admin") ||
-    roleCodes.includes("finance") ||
-    roleCodes.includes("finance_mgr")
-  ) {
-    return true;
-  }
-
-  if (
-    invoice.owner_employee_id === request.employee.id ||
-    invoice.uploaded_by_employee_id === request.employee.id
-  ) {
-    return true;
-  }
-
-  if (invoice.linked_reimbursement) {
-    const reimbursement = invoice.linked_reimbursement;
-    if (
-      reimbursement.owner_id === request.employee.id ||
-      reimbursement.submitter_id === request.employee.id
-    ) {
-      return true;
-    }
-  }
-
-  return false;
-}
-
 function normalizeMoneyInput(value) {
  if (value == null) {
    return null;
@@ -218,205 +184,9 @@ function parseDateOnlyString(value) {
  return new Date(`${trimmed}T00:00:00.000Z`);
 }

-function sanitizeFilename(fileName) {
-  if (!fileName) return "file";
-  return fileName.replace(/[\r\n"]/g, "_");
-}
-
-function parseInvoiceListQuery(query) {
-  const parsed = invoiceListQuerySchema.safeParse(query ?? {});
-  if (!parsed.success) {
-    throw new AppError({
-      code: "VALID_001",
-      message: "参数校验失败",
-      statusCode: 400,
-      details: parsed.error.flatten(),
-    });
-  }
-
-  return {
-    page: parsed.data.page ?? 1,
-    pageSize: parsed.data.pageSize ?? 20,
-    status: parsed.data.status,
-    ownerScope: parsed.data.ownerScope,
-  };
-}
-
-function mapInvoiceSummary(item) {
-  return {
-    id: item.id,
-    status: item.status,
-    ocrType: item.ocr_type,
-    ocrProvider: item.ocr_provider,
-    ocrAttempts: item.ocr_attempts,
-    ocrLastError: item.ocr_last_error,
-    ocrCompletedAt: item.ocr_completed_at?.toISOString?.() ?? null,
-    invoiceCode: item.invoice_code,
-    invoiceNumber: item.invoice_number,
-    invoiceDate: item.invoice_date?.toISOString?.()?.slice(0, 10) ?? null,
-    amount: toMoneyString(item.amount),
-    taxAmount: toMoneyString(item.tax_amount),
-    totalAmount: toMoneyString(item.total_amount),
-    linkedReimbursementId: item.linked_reimbursement_id,
-    linkedItemId: item.linked_item_id,
-    originalName: item.original_name,
-    mimeType: item.mime_type,
-    fileSize: item.file_size,
-    owner: item.owner_employee
-      ? {
-          id: item.owner_employee.id,
-          employeeNo: item.owner_employee.employee_no,
-          name: item.owner_employee.name,
-        }
-      : null,
-    uploadedBy: item.uploaded_by_employee
-      ? {
-          id: item.uploaded_by_employee.id,
-          employeeNo: item.uploaded_by_employee.employee_no,
-          name: item.uploaded_by_employee.name,
-        }
-      : null,
-    createdAt: item.created_at?.toISOString?.() ?? null,
-    updatedAt: item.updated_at?.toISOString?.() ?? null,
-  };
-}
-
-function normalizeInvoiceResponse(invoice) {
-  return {
-    id: invoice.id,
-    status: invoice.status,
-    archivedReason: invoice.archived_reason ?? null,
-    archivedAt: invoice.archived_at?.toISOString?.() ?? null,
-    ownerEmployeeId: invoice.owner_employee_id,
-    uploadedByEmployeeId: invoice.uploaded_by_employee_id,
-    originalName: invoice.original_name ?? null,
-    mimeType: invoice.mime_type ?? null,
-    fileSize: invoice.file_size ?? null,
-    fileSha256: invoice.file_sha256 ?? null,
-    remarks: invoice.remarks ?? null,
-    ocrType: invoice.ocr_type,
-    ocrProvider: invoice.ocr_provider,
-    ocrAttempts: invoice.ocr_attempts,
-    ocrLastRequestedAt: invoice.ocr_last_requested_at?.toISOString?.() ?? null,
-    ocrLastError: invoice.ocr_last_error,
-    ocrCompletedAt: invoice.ocr_completed_at?.toISOString?.() ?? null,
-    invoiceCode: invoice.invoice_code,
-    invoiceNumber: invoice.invoice_number,
-    invoiceDate: invoice.invoice_date ? invoice.invoice_date.toISOString().slice(0, 10) : null,
-    sellerName: invoice.seller_name ?? null,
-    buyerName: invoice.buyer_name ?? null,
-    amount: toMoneyString(invoice.amount),
-    taxAmount: toMoneyString(invoice.tax_amount),
-    totalAmount: toMoneyString(invoice.total_amount),
-    linkedReimbursementId: invoice.linked_reimbursement_id,
-    linkedItemId: invoice.linked_item_id,
-    isDuplicateOverride: invoice.is_duplicate_override ?? false,
-    overrideRefFormNumber: invoice.override_ref_form_number ?? null,
-    overrideReason: invoice.override_reason ?? null,
-    overriddenBy: invoice.overridden_by ?? null,
-    createdAt: invoice.created_at?.toISOString?.() ?? null,
-    updatedAt: invoice.updated_at?.toISOString?.() ?? null,
-  };
-}
-
 async function invoicePoolRoutes(fastify) {

-  fastify.get(
-    "/invoice-pool",
-    {
-      preHandler: fastify.authenticate,
-    },
-    async (request, reply) => {
-      const query = parseInvoiceListQuery(request.query);
-
-      const canViewOwn = fastify.hasPermission(request.employee, "invoice.view_own");
-      const canManage = fastify.hasPermission(request.employee, "invoice.manage");
-
-      if (!canViewOwn && !canManage) {
-        throw new AppError({
-          code: "PERM_001",
-          message: "无权限",
-          statusCode: 403,
-        });
-      }
-
-      const ownerScope = query.ownerScope ?? (canManage ? "all" : "own");
-      if (ownerScope === "all" && !canManage) {
-        throw new AppError({
-          code: "PERM_001",
-          message: "无权限",
-          statusCode: 403,
-        });
-      }
-
-      const skip = (query.page - 1) * query.pageSize;
-      const where = {
-        ...(query.status ? { status: query.status } : {}),
-        ...(ownerScope === "all"
-          ? {}
-          : {
-              OR: [
-                { owner_employee_id: request.employee.id },
-                { uploaded_by_employee_id: request.employee.id },
-                {
-                  linked_reimbursement: {
-                    OR: [
-                      { owner_id: request.employee.id },
-                      { submitter_id: request.employee.id },
-                    ],
-                  },
-                },
-              ],
-            }),
-      };
-
-      const [items, total] = await Promise.all([
-        fastify.prisma.invoicePool.findMany({
-          where,
-          orderBy: { created_at: "desc" },
-          skip,
-          take: query.pageSize,
-          select: {
-            id: true,
-            status: true,
-            ocr_type: true,
-            ocr_provider: true,
-            ocr_attempts: true,
-            ocr_last_error: true,
-            ocr_completed_at: true,
-            invoice_code: true,
-            invoice_number: true,
-            invoice_date: true,
-            amount: true,
-            tax_amount: true,
-            total_amount: true,
-            linked_reimbursement_id: true,
-            linked_item_id: true,
-            original_name: true,
-            mime_type: true,
-            file_size: true,
-            created_at: true,
-            updated_at: true,
-            owner_employee: {
-              select: { id: true, employee_no: true, name: true },
-            },
-            uploaded_by_employee: {
-              select: { id: true, employee_no: true, name: true },
-            },
-          },
-        }),
-        fastify.prisma.invoicePool.count({ where }),
-      ]);
-
-      return sendData(reply, request, {
-        page: query.page,
-        pageSize: query.pageSize,
-        total,
-        ownerScope,
-        items: items.map(mapInvoiceSummary),
-      });
-    },
-  );
+  registerInvoicePoolReadRoutes(fastify);

  fastify.post(
    "/invoice-pool/upload",
@@ -626,107 +396,7 @@ async function invoicePoolRoutes(fastify) {
    },
  );

-  fastify.get(
-    "/invoice-pool/:id",
-    {
-      preHandler: fastify.authenticate,
-    },
-    async (request, reply) => {
-      const parsedInvoiceId = z.string().uuid().safeParse(request.params?.id);
-      if (!parsedInvoiceId.success) {
-        throw new AppError({
-          code: "VALID_001",
-          message: "参数校验失败",
-          statusCode: 400,
-          details: { id: "invalid_uuid" },
-        });
-      }
-
-      const invoice = await fastify.prisma.invoicePool.findUnique({
-        where: { id: parsedInvoiceId.data },
-        select: {
-          id: true,
-          status: true,
-          archived_reason: true,
-          archived_at: true,
-          owner_employee_id: true,
-          uploaded_by_employee_id: true,
-          original_name: true,
-          mime_type: true,
-          file_size: true,
-          file_sha256: true,
-          remarks: true,
-          ocr_type: true,
-          ocr_provider: true,
-          ocr_attempts: true,
-          ocr_last_requested_at: true,
-          ocr_last_error: true,
-          ocr_completed_at: true,
-          invoice_code: true,
-          invoice_number: true,
-          invoice_date: true,
-          seller_name: true,
-          buyer_name: true,
-          amount: true,
-          tax_amount: true,
-          total_amount: true,
-          linked_reimbursement_id: true,
-          linked_item_id: true,
-          is_duplicate_override: true,
-          override_ref_form_number: true,
-          override_reason: true,
-          overridden_by: true,
-          created_at: true,
-          updated_at: true,
-          linked_reimbursement: {
-            select: {
-              owner_id: true,
-              submitter_id: true,
-            },
-          },
-        },
-      });
-
-      if (!invoice) {
-        throw new AppError({
-          code: "SYS_404",
-          message: "Not Found",
-          statusCode: 404,
-        });
-      }
-
-      let canAccess = ensureInvoiceReadableByUser(request, invoice);
-      if (!canAccess && invoice.linked_reimbursement_id) {
-        const pendingTask = await fastify.prisma.workflowTask.findFirst({
-          where: {
-            status: "pending",
-            workflow_instance: {
-              entity_type: "reimbursement",
-              entity_id: invoice.linked_reimbursement_id,
-              current_status: "pending",
-            },
-            OR: [
-              { assignee_id: request.employee.id },
-              { assignee_role: { in: request.employee.roleCodes } },
-            ],
-          },
-          select: { id: true },
-        });
-
-        canAccess = Boolean(pendingTask);
-      }
-
-      if (!canAccess) {
-        throw new AppError({
-          code: "PERM_001",
-          message: "无权限",
-          statusCode: 403,
-        });
-      }
-
-      return sendData(reply, request, normalizeInvoiceResponse(invoice));
-    },
-  );
+  registerInvoiceVerificationRoutes(fastify);

  fastify.patch(
    "/invoice-pool/:id",
@@ -783,41 +453,7 @@ async function invoicePoolRoutes(fastify) {

        const current = await tx.invoicePool.findUnique({
          where: { id: invoiceId },
-          select: {
-            id: true,
-            status: true,
-            archived_reason: true,
-            archived_at: true,
-            owner_employee_id: true,
-            uploaded_by_employee_id: true,
-            original_name: true,
-            mime_type: true,
-            file_size: true,
-            file_sha256: true,
-            remarks: true,
-            ocr_type: true,
-            ocr_provider: true,
-            ocr_attempts: true,
-            ocr_last_requested_at: true,
-            ocr_last_error: true,
-            ocr_completed_at: true,
-            invoice_code: true,
-            invoice_number: true,
-            invoice_date: true,
-            seller_name: true,
-            buyer_name: true,
-            amount: true,
-            tax_amount: true,
-            total_amount: true,
-            linked_reimbursement_id: true,
-            linked_item_id: true,
-            is_duplicate_override: true,
-            override_ref_form_number: true,
-            override_reason: true,
-            overridden_by: true,
-            created_at: true,
-            updated_at: true,
-          },
+          select: buildInvoiceDetailSelect(),
        });

        if (!current) {
@@ -955,41 +591,7 @@ async function invoicePoolRoutes(fastify) {
        const updated = await tx.invoicePool.update({
          where: { id: invoiceId },
          data: updateData,
-          select: {
-            id: true,
-            status: true,
-            archived_reason: true,
-            archived_at: true,
-            owner_employee_id: true,
-            uploaded_by_employee_id: true,
-            original_name: true,
-            mime_type: true,
-            file_size: true,
-            file_sha256: true,
-            remarks: true,
-            ocr_type: true,
-            ocr_provider: true,
-            ocr_attempts: true,
-            ocr_last_requested_at: true,
-            ocr_last_error: true,
-            ocr_completed_at: true,
-            invoice_code: true,
-            invoice_number: true,
-            invoice_date: true,
-            seller_name: true,
-            buyer_name: true,
-            amount: true,
-            tax_amount: true,
-            total_amount: true,
-            linked_reimbursement_id: true,
-            linked_item_id: true,
-            is_duplicate_override: true,
-            override_ref_form_number: true,
-            override_reason: true,
-            overridden_by: true,
-            created_at: true,
-            updated_at: true,
-          },
+          select: buildInvoiceDetailSelect(),
        });

        const changes = {};
@@ -1128,41 +730,7 @@ async function invoicePoolRoutes(fastify) {
        if (current.status === "archived" && current.archived_reason === "manual") {
          return tx.invoicePool.findUnique({
            where: { id: invoiceId },
-            select: {
-              id: true,
-              status: true,
-              archived_reason: true,
-              archived_at: true,
-              owner_employee_id: true,
-              uploaded_by_employee_id: true,
-              original_name: true,
-              mime_type: true,
-              file_size: true,
-              file_sha256: true,
-              remarks: true,
-              ocr_type: true,
-              ocr_provider: true,
-              ocr_attempts: true,
-              ocr_last_requested_at: true,
-              ocr_last_error: true,
-              ocr_completed_at: true,
-              invoice_code: true,
-              invoice_number: true,
-              invoice_date: true,
-              seller_name: true,
-              buyer_name: true,
-              amount: true,
-              tax_amount: true,
-              total_amount: true,
-              linked_reimbursement_id: true,
-              linked_item_id: true,
-              is_duplicate_override: true,
-              override_ref_form_number: true,
-              override_reason: true,
-              overridden_by: true,
-              created_at: true,
-              updated_at: true,
-            },
+            select: buildInvoiceDetailSelect(),
          });
        }

@@ -1184,41 +752,7 @@ async function invoicePoolRoutes(fastify) {
            archived_at: now,
            updated_by: request.employee.id,
          },
-          select: {
-            id: true,
-            status: true,
-            archived_reason: true,
-            archived_at: true,
-            owner_employee_id: true,
-            uploaded_by_employee_id: true,
-            original_name: true,
-            mime_type: true,
-            file_size: true,
-            file_sha256: true,
-            remarks: true,
-            ocr_type: true,
-            ocr_provider: true,
-            ocr_attempts: true,
-            ocr_last_requested_at: true,
-            ocr_last_error: true,
-            ocr_completed_at: true,
-            invoice_code: true,
-            invoice_number: true,
-            invoice_date: true,
-            seller_name: true,
-            buyer_name: true,
-            amount: true,
-            tax_amount: true,
-            total_amount: true,
-            linked_reimbursement_id: true,
-            linked_item_id: true,
-            is_duplicate_override: true,
-            override_ref_form_number: true,
-            override_reason: true,
-            overridden_by: true,
-            created_at: true,
-            updated_at: true,
-          },
+          select: buildInvoiceDetailSelect(),
        });

        await tx.auditLog.create({
@@ -1330,41 +864,7 @@ async function invoicePoolRoutes(fastify) {
            linked_item_id: null,
            updated_by: request.employee.id,
          },
-          select: {
-            id: true,
-            status: true,
-            archived_reason: true,
-            archived_at: true,
-            owner_employee_id: true,
-            uploaded_by_employee_id: true,
-            original_name: true,
-            mime_type: true,
-            file_size: true,
-            file_sha256: true,
-            remarks: true,
-            ocr_type: true,
-            ocr_provider: true,
-            ocr_attempts: true,
-            ocr_last_requested_at: true,
-            ocr_last_error: true,
-            ocr_completed_at: true,
-            invoice_code: true,
-            invoice_number: true,
-            invoice_date: true,
-            seller_name: true,
-            buyer_name: true,
-            amount: true,
-            tax_amount: true,
-            total_amount: true,
-            linked_reimbursement_id: true,
-            linked_item_id: true,
-            is_duplicate_override: true,
-            override_ref_form_number: true,
-            override_reason: true,
-            overridden_by: true,
-            created_at: true,
-            updated_at: true,
-          },
+          select: buildInvoiceDetailSelect(),
        });
      });

@@ -1491,41 +991,7 @@ async function invoicePoolRoutes(fastify) {
            ocr_lock_owner: null,
            updated_by: request.employee.id,
          },
-          select: {
-            id: true,
-            status: true,
-            archived_reason: true,
-            archived_at: true,
-            owner_employee_id: true,
-            uploaded_by_employee_id: true,
-            original_name: true,
-            mime_type: true,
-            file_size: true,
-            file_sha256: true,
-            remarks: true,
-            ocr_type: true,
-            ocr_provider: true,
-            ocr_attempts: true,
-            ocr_last_requested_at: true,
-            ocr_last_error: true,
-            ocr_completed_at: true,
-            invoice_code: true,
-            invoice_number: true,
-            invoice_date: true,
-            seller_name: true,
-            buyer_name: true,
-            amount: true,
-            tax_amount: true,
-            total_amount: true,
-            linked_reimbursement_id: true,
-            linked_item_id: true,
-            is_duplicate_override: true,
-            override_ref_form_number: true,
-            override_reason: true,
-            overridden_by: true,
-            created_at: true,
-            updated_at: true,
-          },
+          select: buildInvoiceDetailSelect(),
        });

        await tx.auditLog.create({
@@ -1702,41 +1168,7 @@ async function invoicePoolRoutes(fastify) {
            overridden_by: request.employee.id,
            updated_by: request.employee.id,
          },
-          select: {
-            id: true,
-            status: true,
-            archived_reason: true,
-            archived_at: true,
-            owner_employee_id: true,
-            uploaded_by_employee_id: true,
-            original_name: true,
-            mime_type: true,
-            file_size: true,
-            file_sha256: true,
-            remarks: true,
-            ocr_type: true,
-            ocr_provider: true,
-            ocr_attempts: true,
-            ocr_last_requested_at: true,
-            ocr_last_error: true,
-            ocr_completed_at: true,
-            invoice_code: true,
-            invoice_number: true,
-            invoice_date: true,
-            seller_name: true,
-            buyer_name: true,
-            amount: true,
-            tax_amount: true,
-            total_amount: true,
-            linked_reimbursement_id: true,
-            linked_item_id: true,
-            is_duplicate_override: true,
-            override_ref_form_number: true,
-            override_reason: true,
-            overridden_by: true,
-            created_at: true,
-            updated_at: true,
-          },
+          select: buildInvoiceDetailSelect(),
        });

        await tx.auditLog.create({
@@ -1760,214 +1192,6 @@ async function invoicePoolRoutes(fastify) {
    },
  );

-  fastify.post(
-    "/invoice-pool/:id/signed-url",
-    {
-      preHandler: fastify.authenticate,
-    },
-    async (request, reply) => {
-      const parsedInvoiceId = z.string().uuid().safeParse(request.params?.id);
-      if (!parsedInvoiceId.success) {
-        throw new AppError({
-          code: "VALID_001",
-          message: "参数校验失败",
-          statusCode: 400,
-          details: { id: "invalid_uuid" },
-        });
-      }
-
-      const invoice = await fastify.prisma.invoicePool.findUnique({
-        where: { id: parsedInvoiceId.data },
-        select: {
-          id: true,
-          owner_employee_id: true,
-          uploaded_by_employee_id: true,
-          linked_reimbursement_id: true,
-          linked_reimbursement: {
-            select: {
-              owner_id: true,
-              submitter_id: true,
-            },
-          },
-        },
-      });
-
-      if (!invoice) {
-        throw new AppError({
-          code: "SYS_404",
-          message: "Not Found",
-          statusCode: 404,
-        });
-      }
-
-      let canAccess = ensureInvoiceReadableByUser(request, invoice);
-
-      if (!canAccess && invoice.linked_reimbursement_id) {
-        const pendingTask = await fastify.prisma.workflowTask.findFirst({
-          where: {
-            status: "pending",
-            workflow_instance: {
-              entity_type: "reimbursement",
-              entity_id: invoice.linked_reimbursement_id,
-              current_status: "pending",
-            },
-            OR: [
-              { assignee_id: request.employee.id },
-              { assignee_role: { in: request.employee.roleCodes } },
-            ],
-          },
-          select: { id: true },
-        });
-
-        canAccess = Boolean(pendingTask);
-      }
-
-      if (!canAccess) {
-        throw new AppError({
-          code: "PERM_001",
-          message: "无权限",
-          statusCode: 403,
-        });
-      }
-
-      const expiresAt = Date.now() + fastify.config.signedUrlTtlSeconds * 1000;
-      const token = signPayload(
-        {
-          invoiceId: invoice.id,
-          actorId: request.employee.id,
-          exp: expiresAt,
-        },
-        fastify.config.jwtSecret,
-      );
-
-      const origin =
-        fastify.config.appOrigin ||
-        `${request.protocol}://${request.headers.host ?? "localhost:3000"}`;
-      const signedUrl = `${origin}/api/invoice-pool/${invoice.id}/file?token=${encodeURIComponent(token)}`;
-
-      await fastify.prisma.auditLog.create({
-        data: buildAuditLogData(request, {
-          actorId: request.employee.id,
-          action: "INVOICE_SIGNED_URL_ISSUED",
-          targetType: "invoice_pool",
-          targetId: invoice.id,
-          extra: {
-            invoiceId: invoice.id,
-            expiresAt,
-          },
-        }),
-      });
-
-      return sendData(reply, request, {
-        signedUrl,
-        expiresAt: new Date(expiresAt).toISOString(),
-      });
-    },
-  );
-
-  fastify.get("/invoice-pool/:id/file", async (request, reply) => {
-    const parsedInvoiceId = z.string().uuid().safeParse(request.params?.id);
-    const token = request.query?.token;
-    if (!parsedInvoiceId.success || typeof token !== "string") {
-      throw new AppError({
-        code: "PERM_001",
-        message: "无权限",
-        statusCode: 403,
-      });
-    }
-
-    const verified = verifyToken(token, fastify.config.jwtSecret);
-    if (!verified.ok) {
-      throw new AppError({
-        code: "PERM_001",
-        message: "无权限",
-        statusCode: 403,
-      });
-    }
-
-    const payload = verified.payload;
-    const parsedActorId = z.string().uuid().safeParse(payload?.actorId);
-    if (
-      payload?.invoiceId !== parsedInvoiceId.data ||
-      typeof payload?.exp !== "number" ||
-      payload.exp <= Date.now() ||
-      !parsedActorId.success
-    ) {
-      throw new AppError({
-        code: "PERM_001",
-        message: "无权限",
-        statusCode: 403,
-      });
-    }
-
-    const actorId = parsedActorId.data;
-
-    const invoice = await fastify.prisma.invoicePool.findUnique({
-      where: { id: parsedInvoiceId.data },
-      select: {
-        storage_path: true,
-        mime_type: true,
-        original_name: true,
-      },
-    });
-
-    if (!invoice) {
-      throw new AppError({
-        code: "SYS_404",
-        message: "Not Found",
-        statusCode: 404,
-      });
-    }
-
-    let stream = null;
-    try {
-      const opened = await openReadStream({
-        config: fastify.config,
-        storagePath: invoice.storage_path,
-      });
-      stream = opened.stream;
-    } catch (error) {
-      if (error instanceof StorageNotFoundError) {
-        throw new AppError({
-          code: "SYS_404",
-          message: "Not Found",
-          statusCode: 404,
-        });
-      }
-
-      throw new AppError({
-        code: "SYS_001",
-        message: "服务器内部错误",
-        statusCode: 500,
-        details: {},
-      });
-    }
-
-    try {
-      await fastify.prisma.auditLog.create({
-        data: buildAuditLogData(request, {
-          actorId,
-          action: "INVOICE_FILE_DOWNLOADED",
-          targetType: "invoice_pool",
-          targetId: parsedInvoiceId.data,
-          extra: {
-            invoiceId: parsedInvoiceId.data,
-            exp: payload.exp,
-          },
-        }),
-      });
-    } catch (error) {
-      fastify.log.error({ err: error, invoiceId: parsedInvoiceId.data }, "Audit log write failed");
-    }
-
-    reply.type(invoice.mime_type || "application/octet-stream");
-    reply.header(
-      "content-disposition",
-      `inline; filename=\"${sanitizeFilename(invoice.original_name)}\"`,
-    );
-    return reply.send(stream);
-  });
-
  fastify.post(
    "/invoice-pool/:id/bind",
    {
@@ -0,0 +1,413 @@
+const { z } = require("zod");
+
+const { AppError } = require("../../utils/AppError");
+const { sendData } = require("../../utils/reply");
+const { buildAuditLogData } = require("../../utils/audit");
+const { signPayload, verifyToken } = require("../../utils/signedUrl");
+const { openReadStream, StorageNotFoundError } = require("../../services/storage");
+const {
+  mapInvoiceSummary,
+  normalizeInvoiceResponse,
+} = require("./shared/mappers");
+const {
+  buildInvoiceDetailSelect,
+  buildInvoiceSummarySelect,
+} = require("./shared/selects");
+
+const invoiceListQuerySchema = z.object({
+  page: z.coerce.number().int().min(1).optional(),
+  pageSize: z.coerce.number().int().min(1).max(100).optional(),
+  status: z.enum(["pending_ocr", "ocr_failed", "available", "bound", "archived"]).optional(),
+  ownerScope: z.enum(["own", "all"]).optional(),
+});
+
+function sanitizeFilename(fileName) {
+  if (!fileName) return "file";
+  return fileName.replace(/[\r\n"]/g, "_");
+}
+
+function parseInvoiceListQuery(query) {
+  const parsed = invoiceListQuerySchema.safeParse(query ?? {});
+  if (!parsed.success) {
+    throw new AppError({
+      code: "VALID_001",
+      message: "参数校验失败",
+      statusCode: 400,
+      details: parsed.error.flatten(),
+    });
+  }
+
+  return {
+    page: parsed.data.page ?? 1,
+    pageSize: parsed.data.pageSize ?? 20,
+    status: parsed.data.status,
+    ownerScope: parsed.data.ownerScope,
+  };
+}
+
+function ensureInvoiceReadableByUser(request, invoice) {
+  const roleCodes = request.employee.roleCodes;
+  if (
+    roleCodes.includes("admin") ||
+    roleCodes.includes("finance") ||
+    roleCodes.includes("finance_mgr")
+  ) {
+    return true;
+  }
+
+  if (
+    invoice.owner_employee_id === request.employee.id ||
+    invoice.uploaded_by_employee_id === request.employee.id
+  ) {
+    return true;
+  }
+
+  if (invoice.linked_reimbursement) {
+    const reimbursement = invoice.linked_reimbursement;
+    if (
+      reimbursement.owner_id === request.employee.id ||
+      reimbursement.submitter_id === request.employee.id
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+async function hasPendingTaskAccess(fastify, request, linkedReimbursementId) {
+  if (!linkedReimbursementId) {
+    return false;
+  }
+
+  const pendingTask = await fastify.prisma.workflowTask.findFirst({
+    where: {
+      status: "pending",
+      workflow_instance: {
+        entity_type: "reimbursement",
+        entity_id: linkedReimbursementId,
+        current_status: "pending",
+      },
+      OR: [
+        { assignee_id: request.employee.id },
+        { assignee_role: { in: request.employee.roleCodes } },
+      ],
+    },
+    select: { id: true },
+  });
+
+  return Boolean(pendingTask);
+}
+
+function registerInvoicePoolReadRoutes(fastify) {
+  fastify.get(
+    "/invoice-pool",
+    {
+      preHandler: fastify.authenticate,
+    },
+    async (request, reply) => {
+      const query = parseInvoiceListQuery(request.query);
+
+      const canViewOwn = fastify.hasPermission(request.employee, "invoice.view_own");
+      const canManage = fastify.hasPermission(request.employee, "invoice.manage");
+
+      if (!canViewOwn && !canManage) {
+        throw new AppError({
+          code: "PERM_001",
+          message: "无权限",
+          statusCode: 403,
+        });
+      }
+
+      const ownerScope = query.ownerScope ?? (canManage ? "all" : "own");
+      if (ownerScope === "all" && !canManage) {
+        throw new AppError({
+          code: "PERM_001",
+          message: "无权限",
+          statusCode: 403,
+        });
+      }
+
+      const skip = (query.page - 1) * query.pageSize;
+      const where = {
+        ...(query.status ? { status: query.status } : {}),
+        ...(ownerScope === "all"
+          ? {}
+          : {
+              OR: [
+                { owner_employee_id: request.employee.id },
+                { uploaded_by_employee_id: request.employee.id },
+                {
+                  linked_reimbursement: {
+                    OR: [
+                      { owner_id: request.employee.id },
+                      { submitter_id: request.employee.id },
+                    ],
+                  },
+                },
+              ],
+            }),
+      };
+
+      const [items, total] = await Promise.all([
+        fastify.prisma.invoicePool.findMany({
+          where,
+          orderBy: { created_at: "desc" },
+          skip,
+          take: query.pageSize,
+          select: buildInvoiceSummarySelect(),
+        }),
+        fastify.prisma.invoicePool.count({ where }),
+      ]);
+
+      return sendData(reply, request, {
+        page: query.page,
+        pageSize: query.pageSize,
+        total,
+        ownerScope,
+        items: items.map(mapInvoiceSummary),
+      });
+    },
+  );
+
+  fastify.get(
+    "/invoice-pool/:id",
+    {
+      preHandler: fastify.authenticate,
+    },
+    async (request, reply) => {
+      const parsedInvoiceId = z.string().uuid().safeParse(request.params?.id);
+      if (!parsedInvoiceId.success) {
+        throw new AppError({
+          code: "VALID_001",
+          message: "参数校验失败",
+          statusCode: 400,
+          details: { id: "invalid_uuid" },
+        });
+      }
+
+      const invoice = await fastify.prisma.invoicePool.findUnique({
+        where: { id: parsedInvoiceId.data },
+        select: buildInvoiceDetailSelect({ includeLinkedReimbursement: true }),
+      });
+
+      if (!invoice) {
+        throw new AppError({
+          code: "SYS_404",
+          message: "Not Found",
+          statusCode: 404,
+        });
+      }
+
+      let canAccess = ensureInvoiceReadableByUser(request, invoice);
+      if (!canAccess) {
+        canAccess = await hasPendingTaskAccess(fastify, request, invoice.linked_reimbursement_id);
+      }
+
+      if (!canAccess) {
+        throw new AppError({
+          code: "PERM_001",
+          message: "无权限",
+          statusCode: 403,
+        });
+      }
+
+      return sendData(reply, request, normalizeInvoiceResponse(invoice));
+    },
+  );
+
+  fastify.post(
+    "/invoice-pool/:id/signed-url",
+    {
+      preHandler: fastify.authenticate,
+    },
+    async (request, reply) => {
+      const parsedInvoiceId = z.string().uuid().safeParse(request.params?.id);
+      if (!parsedInvoiceId.success) {
+        throw new AppError({
+          code: "VALID_001",
+          message: "参数校验失败",
+          statusCode: 400,
+          details: { id: "invalid_uuid" },
+        });
+      }
+
+      const invoice = await fastify.prisma.invoicePool.findUnique({
+        where: { id: parsedInvoiceId.data },
+        select: {
+          id: true,
+          owner_employee_id: true,
+          uploaded_by_employee_id: true,
+          linked_reimbursement_id: true,
+          linked_reimbursement: {
+            select: {
+              owner_id: true,
+              submitter_id: true,
+            },
+          },
+        },
+      });
+
+      if (!invoice) {
+        throw new AppError({
+          code: "SYS_404",
+          message: "Not Found",
+          statusCode: 404,
+        });
+      }
+
+      let canAccess = ensureInvoiceReadableByUser(request, invoice);
+      if (!canAccess) {
+        canAccess = await hasPendingTaskAccess(fastify, request, invoice.linked_reimbursement_id);
+      }
+
+      if (!canAccess) {
+        throw new AppError({
+          code: "PERM_001",
+          message: "无权限",
+          statusCode: 403,
+        });
+      }
+
+      const expiresAt = Date.now() + fastify.config.signedUrlTtlSeconds * 1000;
+      const token = signPayload(
+        {
+          invoiceId: invoice.id,
+          actorId: request.employee.id,
+          exp: expiresAt,
+        },
+        fastify.config.jwtSecret,
+      );
+
+      const origin =
+        fastify.config.appOrigin ||
+        `${request.protocol}://${request.headers.host ?? "localhost:3000"}`;
+      const signedUrl = `${origin}/api/invoice-pool/${invoice.id}/file?token=${encodeURIComponent(token)}`;
+
+      await fastify.prisma.auditLog.create({
+        data: buildAuditLogData(request, {
+          actorId: request.employee.id,
+          action: "INVOICE_SIGNED_URL_ISSUED",
+          targetType: "invoice_pool",
+          targetId: invoice.id,
+          extra: {
+            invoiceId: invoice.id,
+            expiresAt,
+          },
+        }),
+      });
+
+      return sendData(reply, request, {
+        signedUrl,
+        expiresAt: new Date(expiresAt).toISOString(),
+      });
+    },
+  );
+
+  fastify.get("/invoice-pool/:id/file", async (request, reply) => {
+    const parsedInvoiceId = z.string().uuid().safeParse(request.params?.id);
+    const token = request.query?.token;
+    if (!parsedInvoiceId.success || typeof token !== "string") {
+      throw new AppError({
+        code: "PERM_001",
+        message: "无权限",
+        statusCode: 403,
+      });
+    }
+
+    const verified = verifyToken(token, fastify.config.jwtSecret);
+    if (!verified.ok) {
+      throw new AppError({
+        code: "PERM_001",
+        message: "无权限",
+        statusCode: 403,
+      });
+    }
+
+    const payload = verified.payload;
+    const parsedActorId = z.string().uuid().safeParse(payload?.actorId);
+    if (
+      payload?.invoiceId !== parsedInvoiceId.data ||
+      typeof payload?.exp !== "number" ||
+      payload.exp <= Date.now() ||
+      !parsedActorId.success
+    ) {
+      throw new AppError({
+        code: "PERM_001",
+        message: "无权限",
+        statusCode: 403,
+      });
+    }
+
+    const actorId = parsedActorId.data;
+
+    const invoice = await fastify.prisma.invoicePool.findUnique({
+      where: { id: parsedInvoiceId.data },
+      select: {
+        storage_path: true,
+        mime_type: true,
+        original_name: true,
+      },
+    });
+
+    if (!invoice) {
+      throw new AppError({
+        code: "SYS_404",
+        message: "Not Found",
+        statusCode: 404,
+      });
+    }
+
+    let stream = null;
+    try {
+      const opened = await openReadStream({
+        config: fastify.config,
+        storagePath: invoice.storage_path,
+      });
+      stream = opened.stream;
+    } catch (error) {
+      if (error instanceof StorageNotFoundError) {
+        throw new AppError({
+          code: "SYS_404",
+          message: "Not Found",
+          statusCode: 404,
+        });
+      }
+
+      throw new AppError({
+        code: "SYS_001",
+        message: "服务器内部错误",
+        statusCode: 500,
+        details: {},
+      });
+    }
+
+    try {
+      await fastify.prisma.auditLog.create({
+        data: buildAuditLogData(request, {
+          actorId,
+          action: "INVOICE_FILE_DOWNLOADED",
+          targetType: "invoice_pool",
+          targetId: parsedInvoiceId.data,
+          extra: {
+            invoiceId: parsedInvoiceId.data,
+            exp: payload.exp,
+          },
+        }),
+      });
+    } catch (error) {
+      fastify.log.error({ err: error, invoiceId: parsedInvoiceId.data }, "Audit log write failed");
+    }
+
+    reply.type(invoice.mime_type || "application/octet-stream");
+    reply.header(
+      "content-disposition",
+      `inline; filename=\"${sanitizeFilename(invoice.original_name)}\"`,
+    );
+    return reply.send(stream);
+  });
+}
+
+module.exports = {
+  registerInvoicePoolReadRoutes,
+};
@@ -0,0 +1,58 @@
+const { pushPaidReimbursementToErp } = require("./erp");
+
+class IntegrationDispatchError extends Error {
+  constructor({ code, message, retryable, statusCode, response }) {
+    super(message || code || "integration_dispatch_failed");
+    this.name = "IntegrationDispatchError";
+    this.code = code || "integration_dispatch_failed";
+    this.retryable = typeof retryable === "boolean" ? retryable : true;
+    this.statusCode = Number.isFinite(statusCode) ? Number(statusCode) : null;
+    this.response = response ?? null;
+  }
+}
+
+function toDispatchError(result) {
+  return new IntegrationDispatchError({
+    code: result?.code,
+    message: result?.message,
+    retryable: result?.retryable,
+    statusCode: result?.httpStatus,
+    response: result?.response,
+  });
+}
+
+async function dispatchOutboxEvent({ config, eventType, payload }) {
+  if (eventType === "erp.reimbursement.paid") {
+    const result = await pushPaidReimbursementToErp(config, payload);
+    if (!result.ok) {
+      throw toDispatchError(result);
+    }
+
+    return {
+      channel: "erp",
+      code: result.code,
+      response: result.response ?? null,
+    };
+  }
+
+  if (eventType === "notification.im") {
+    return {
+      channel: "im",
+      code: "mock_sent",
+      response: {
+        channelType: payload.channelType,
+      },
+    };
+  }
+
+  throw new IntegrationDispatchError({
+    code: "unsupported_outbox_event",
+    message: `unsupported_outbox_event:${eventType}`,
+    retryable: false,
+  });
+}
+
+module.exports = {
+  IntegrationDispatchError,
+  dispatchOutboxEvent,
+};
@@ -0,0 +1,157 @@
+function buildErpPayload(input) {
+  return {
+    reimbursementId: input.reimbursement.id,
+    formNumber: input.reimbursement.form_number,
+    ownerEmployeeId: input.reimbursement.owner_id,
+    submitterEmployeeId: input.reimbursement.submitter_id,
+    totalAmount: input.reimbursement.total_amount?.toString?.() ?? null,
+    paymentVoucherNo: input.reimbursement.payment_voucher_no ?? null,
+    paymentDate: input.reimbursement.payment_date
+      ? new Date(input.reimbursement.payment_date).toISOString().slice(0, 10)
+      : null,
+    paidAt: input.reimbursement.paid_at ? new Date(input.reimbursement.paid_at).toISOString() : null,
+  };
+}
+
+function normalizeProvider(config) {
+  return String(config.erpSyncProvider ?? "mock").trim().toLowerCase() || "mock";
+}
+
+function buildAuthHeaders(config) {
+  const token = String(config.erpSyncAuthToken ?? "").trim();
+  if (!token) {
+    return {};
+  }
+
+  return {
+    authorization: `Bearer ${token}`,
+  };
+}
+
+async function postToErpHttp(config, payload) {
+  const endpoint = String(config.erpSyncEndpoint ?? "").trim();
+  if (!endpoint) {
+    return {
+      ok: false,
+      code: "erp_sync_endpoint_missing",
+      message: "ERP sync endpoint missing",
+      retryable: false,
+    };
+  }
+
+  const timeoutMs = Math.max(100, Number(config.erpSyncTimeoutMs ?? 5000));
+  const controller = new AbortController();
+  const timer = setTimeout(() => {
+    controller.abort();
+  }, timeoutMs);
+
+  try {
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...buildAuthHeaders(config),
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+
+    let responseBody = null;
+    const contentType = response.headers.get("content-type") || "";
+    if (contentType.includes("application/json")) {
+      try {
+        responseBody = await response.json();
+      } catch {
+        responseBody = null;
+      }
+    } else {
+      try {
+        responseBody = await response.text();
+      } catch {
+        responseBody = null;
+      }
+    }
+
+    if (response.ok) {
+      return {
+        ok: true,
+        code: "http_synced",
+        message: "ERP synced",
+        response: {
+          status: response.status,
+          body: responseBody,
+        },
+      };
+    }
+
+    const retryable = response.status >= 500;
+    return {
+      ok: false,
+      code: retryable ? "erp_sync_http_5xx" : "erp_sync_http_4xx",
+      message: `ERP sync HTTP ${response.status}`,
+      retryable,
+      httpStatus: response.status,
+      response: {
+        status: response.status,
+        body: responseBody,
+      },
+    };
+  } catch (error) {
+    if (error?.name === "AbortError") {
+      return {
+        ok: false,
+        code: "erp_sync_timeout",
+        message: `ERP sync timeout (${timeoutMs}ms)`,
+        retryable: true,
+      };
+    }
+
+    return {
+      ok: false,
+      code: "erp_sync_network_error",
+      message: String(error?.message ?? error ?? "ERP sync network error"),
+      retryable: true,
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function pushPaidReimbursementToErp(config, payload) {
+  if (!config.erpSyncEnabled) {
+    return {
+      ok: false,
+      code: "erp_sync_disabled",
+      message: "ERP sync disabled",
+      retryable: false,
+    };
+  }
+
+  const provider = normalizeProvider(config);
+  if (provider === "mock") {
+    return {
+      ok: true,
+      code: "mock_synced",
+      message: "mock ERP synced",
+      response: {
+        externalId: `ERP-${payload.formNumber ?? payload.reimbursementId}`,
+      },
+    };
+  }
+
+  if (provider === "http") {
+    return postToErpHttp(config, payload);
+  }
+
+  return {
+    ok: false,
+    code: "erp_sync_provider_invalid",
+    message: `Unsupported ERP sync provider: ${provider}`,
+    retryable: false,
+  };
+}
+
+module.exports = {
+  buildErpPayload,
+  pushPaidReimbursementToErp,
+};
@@ -0,0 +1,161 @@
+const OUTBOX_STATUSES = {
+  pending: "pending",
+  processing: "processing",
+  succeeded: "succeeded",
+  failed: "failed",
+  dead_letter: "dead_letter",
+};
+
+function nextRetryAt(config, attempts) {
+  const waitSeconds = Math.max(30, Number(config.integrationOutboxRetrySeconds ?? 120));
+  const backoff = waitSeconds * Math.max(1, attempts);
+  return new Date(Date.now() + backoff * 1000);
+}
+
+function formatDispatchError(error) {
+  const code = error?.code ? String(error.code) : null;
+  const statusCode = Number.isFinite(error?.statusCode) ? Number(error.statusCode) : null;
+  const message = String(error?.message ?? error ?? "integration_outbox_error").trim();
+
+  const parts = [];
+  if (code) {
+    parts.push(code);
+  }
+  if (statusCode != null) {
+    parts.push(`HTTP ${statusCode}`);
+  }
+  if (message) {
+    parts.push(message);
+  }
+
+  if (!parts.length) {
+    return "integration_outbox_error";
+  }
+
+  return parts.join(" | ");
+}
+
+async function enqueueIntegrationEvent(prisma, input) {
+  const dedupeKey = input.dedupeKey ?? null;
+
+  const existed =
+    dedupeKey != null
+      ? await prisma.integrationOutbox.findUnique({
+          where: {
+            event_type_dedupe_key: {
+              event_type: input.eventType,
+              dedupe_key: dedupeKey,
+            },
+          },
+          select: { id: true, status: true },
+        })
+      : null;
+
+  if (existed) {
+    return {
+      id: existed.id,
+      status: existed.status,
+      duplicated: true,
+    };
+  }
+
+  const created = await prisma.integrationOutbox.create({
+    data: {
+      event_type: input.eventType,
+      status: OUTBOX_STATUSES.pending,
+      payload: input.payload,
+      dedupe_key: dedupeKey,
+      max_attempts: input.maxAttempts,
+      created_by: input.actorId ?? null,
+      updated_by: input.actorId ?? null,
+    },
+    select: {
+      id: true,
+      status: true,
+    },
+  });
+
+  return {
+    id: created.id,
+    status: created.status,
+    duplicated: false,
+  };
+}
+
+async function fetchPendingOutboxEvents(prisma, options) {
+  const batchSize = Math.max(1, Number(options.batchSize ?? 20));
+  const now = new Date();
+
+  return prisma.integrationOutbox.findMany({
+    where: {
+      status: {
+        in: [OUTBOX_STATUSES.pending, OUTBOX_STATUSES.failed],
+      },
+      OR: [{ next_retry_at: null }, { next_retry_at: { lte: now } }],
+    },
+    orderBy: [{ created_at: "asc" }],
+    take: batchSize,
+  });
+}
+
+async function markOutboxProcessing(prisma, id, actorId) {
+  return prisma.integrationOutbox.update({
+    where: { id },
+    data: {
+      status: OUTBOX_STATUSES.processing,
+      updated_by: actorId ?? null,
+    },
+  });
+}
+
+async function markOutboxSucceeded(prisma, id, actorId) {
+  return prisma.integrationOutbox.update({
+    where: { id },
+    data: {
+      status: OUTBOX_STATUSES.succeeded,
+      processed_at: new Date(),
+      last_error: null,
+      updated_by: actorId ?? null,
+    },
+  });
+}
+
+async function markOutboxFailed(prisma, config, item, error, actorId, options = {}) {
+  const attempts = Number(item.attempts ?? 0) + 1;
+  const maxAttempts = Math.max(
+    1,
+    Number(item.max_attempts ?? config.integrationOutboxMaxAttempts ?? 5),
+  );
+
+  const retryable =
+    typeof options.retryable === "boolean"
+      ? options.retryable
+      : typeof error?.retryable === "boolean"
+        ? error.retryable
+        : true;
+
+  const deadByAttempts = retryable && attempts >= maxAttempts;
+  const deadByPolicy = !retryable;
+  const dead = deadByPolicy || deadByAttempts;
+
+  return prisma.integrationOutbox.update({
+    where: { id: item.id },
+    data: {
+      attempts,
+      status: dead ? OUTBOX_STATUSES.dead_letter : OUTBOX_STATUSES.failed,
+      dead_letter_at: dead ? new Date() : null,
+      next_retry_at: dead ? null : nextRetryAt(config, attempts),
+      last_error: formatDispatchError(error).slice(0, 500),
+      updated_by: actorId ?? null,
+    },
+  });
+}
+
+module.exports = {
+  OUTBOX_STATUSES,
+  enqueueIntegrationEvent,
+  fetchPendingOutboxEvents,
+  markOutboxProcessing,
+  markOutboxSucceeded,
+  markOutboxFailed,
+};