H1-H10 优化OCR实时体验闭环

2026-05-09 11:48:57 +08:00
@@ -73,8 +73,10 @@ const travelAuthorizationsRoutes = require("./routes/travelAuthorizations");
 const travelTransactionsRoutes = require("./routes/travelTransactions");
 const travelReconciliationRoutes = require("./routes/travelReconciliation");
 const aiRoutes = require("./routes/ai");
+const eventsRoutes = require("./routes/events");
 const { startJobs } = require("./jobs/jobSystem");
 const { initMetrics } = require("./observability");
+const { createAppEventBus } = require("./services/events");
 const { AppError } = require("./utils/AppError");
 const { buildDataEnvelopeSchema, buildErrorEnvelopeSchema } = require("./utils/openapi");

@@ -122,6 +124,7 @@ async function buildApp() {
  });

  app.decorate("config", config);
+  app.decorate("appEvents", createAppEventBus());
  await fs.mkdir(config.storageDir, { recursive: true });

  await app.register(cookie);
@@ -332,6 +335,7 @@ async function buildApp() {

  await app.register(authRoutes, { prefix: "/api/auth" });
  await app.register(wecomAuthRoutes, { prefix: "/api/auth" });
+  await app.register(eventsRoutes, { prefix: "/api" });
  await app.register(meRoutes, { prefix: "/api" });
  await app.register(reimbursementRoutes, { prefix: "/api" });
  await app.register(invoicePoolRoutes, { prefix: "/api" });
@@ -1,6 +1,7 @@
 const cron = require("node-cron");

 const { buildMissingRequiredOcrError, runOcrForInvoice } = require("../services/ocr");
+const { publishInvoiceUpdated } = require("../services/events");
 const { resolveInvoiceDedupBlocker } = require("../services/invoiceGovernance");
 const { readFileBuffer } = require("../services/storage");

@@ -70,7 +71,30 @@ async function claimPendingInvoices(prisma, config, workerId) {
        ocr_lock_owner = ${workerId}
    FROM candidates
    WHERE i.id = candidates.id
-    RETURNING i.id, i.owner_employee_id, i.file_sha256, i.ocr_provider, i.ocr_type, i.storage_path, i.mime_type, i.ocr_attempts
+    RETURNING i.id, i.owner_employee_id, i.uploaded_by_employee_id, i.file_sha256, i.ocr_provider, i.ocr_type, i.storage_path, i.mime_type, i.ocr_attempts
+  `;
+}
+
+async function claimPendingInvoiceById(prisma, config, workerId, invoiceId) {
+  const lockTtlSeconds = Math.max(60, Number(config.ocrLockTtlSeconds || 300));
+
+  return prisma.$queryRaw`
+    WITH candidates AS (
+      SELECT id
+      FROM "invoice_pool"
+      WHERE id = ${invoiceId}::uuid
+        AND status = 'pending_ocr'
+        AND (ocr_locked_at IS NULL OR ocr_locked_at < NOW() - make_interval(secs => ${lockTtlSeconds}))
+      ORDER BY created_at ASC
+      LIMIT 1
+      FOR UPDATE SKIP LOCKED
+    )
+    UPDATE "invoice_pool" AS i
+    SET ocr_locked_at = NOW(),
+        ocr_lock_owner = ${workerId}
+    FROM candidates
+    WHERE i.id = candidates.id
+    RETURNING i.id, i.owner_employee_id, i.uploaded_by_employee_id, i.file_sha256, i.ocr_provider, i.ocr_type, i.storage_path, i.mime_type, i.ocr_attempts
  `;
 }

@@ -226,11 +250,12 @@ async function markInvoiceAsFailed(prisma, claimedInvoice, errorMessage, config)
  const now = new Date();
  const nextAttempts = Number(claimedInvoice.ocr_attempts || 0) + 1;
  const isTerminal = nextAttempts >= config.ocrMaxAttempts;
+  const nextStatus = isTerminal ? "ocr_failed" : "pending_ocr";

  await prisma.invoicePool.update({
    where: { id: claimedInvoice.id },
    data: {
-      status: isTerminal ? "ocr_failed" : "pending_ocr",
+      status: nextStatus,
      ocr_provider: getEffectiveOcrProvider(config),
      ocr_attempts: nextAttempts,
      ocr_last_error: errorMessage,
@@ -239,6 +264,8 @@ async function markInvoiceAsFailed(prisma, claimedInvoice, errorMessage, config)
      ocr_lock_owner: null,
    },
  });
+
+  return nextStatus;
 }

 async function processClaimedInvoice(prisma, config, claimedInvoice, workerId, logger) {
@@ -276,7 +303,7 @@ async function processClaimedInvoice(prisma, config, claimedInvoice, workerId, l
        },
        "OCR invoice marked as failed for missing required fields",
      );
-      return { outcome: "failed" };
+      return { outcome: "failed", status: "ocr_failed" };
    }

    const duplicate = await resolveInvoiceDedupBlocker(
@@ -302,14 +329,14 @@ async function processClaimedInvoice(prisma, config, claimedInvoice, workerId, l
        },
        "OCR invoice marked as duplicate",
      );
-      return { outcome: "duplicate" };
+      return { outcome: "duplicate", status: "ocr_failed" };
    }

    await markInvoiceAsAvailable(prisma, config, claimedInvoice.id, normalized, ocrResultId);
-    return { outcome: "available" };
+    return { outcome: "available", status: "available" };
  } catch (error) {
    const message = trimErrorMessage(error);
-    await markInvoiceAsFailed(prisma, claimedInvoice, message, config);
+    const status = await markInvoiceAsFailed(prisma, claimedInvoice, message, config);
    logger.error(
      {
        err: error,
@@ -320,12 +347,11 @@ async function processClaimedInvoice(prisma, config, claimedInvoice, workerId, l
      },
      "OCR processing failed",
    );
-    return { outcome: "failed" };
+    return { outcome: "failed", status };
  }
 }

-async function runOcrOnce(prisma, config, logger, workerId = `ocr:${process.pid}`) {
-  const claimed = await claimPendingInvoices(prisma, config, workerId);
+async function processClaimedInvoices(prisma, config, logger, workerId, claimed, options = {}) {
  if (!claimed.length) {
    return { claimed: 0, available: 0, duplicate: 0, failed: 0 };
  }
@@ -341,11 +367,31 @@ async function runOcrOnce(prisma, config, logger, workerId = `ocr:${process.pid}
    } else if (result?.outcome === "failed") {
      stats.failed += 1;
    }
+
+    if (typeof options.onInvoiceProcessed === "function") {
+      await options.onInvoiceProcessed({
+        invoiceId: item.id,
+        status: result?.status ?? item.status ?? null,
+        outcome: result?.outcome ?? null,
+        ownerEmployeeId: item.owner_employee_id ?? null,
+        uploadedByEmployeeId: item.uploaded_by_employee_id ?? null,
+      });
+    }
  }

  return stats;
 }

+async function runOcrOnce(prisma, config, logger, workerId = `ocr:${process.pid}`, options = {}) {
+  const claimed = await claimPendingInvoices(prisma, config, workerId);
+  return processClaimedInvoices(prisma, config, logger, workerId, claimed, options);
+}
+
+async function runOcrForInvoiceId(prisma, config, logger, invoiceId, workerId = `ocr:${process.pid}`, options = {}) {
+  const claimed = await claimPendingInvoiceById(prisma, config, workerId, invoiceId);
+  return processClaimedInvoices(prisma, config, logger, workerId, claimed, options);
+}
+
 function startOcrJob(fastify) {
  if (!["tencent", "mock"].includes(fastify.config.ocrProvider)) {
    fastify.log.info({ provider: fastify.config.ocrProvider }, "OCR job disabled");
@@ -359,6 +405,12 @@ function startOcrJob(fastify) {

  let running = false;
  const workerId = `ocr-worker:${process.pid}`;
+  const onInvoiceProcessed = (event) =>
+    publishInvoiceUpdated(fastify, {
+      invoiceId: event.invoiceId,
+      status: event.status,
+      audienceEmployeeIds: [event.ownerEmployeeId, event.uploadedByEmployeeId],
+    });

  const task = cron.schedule(fastify.config.ocrPollCron, async () => {
    if (running) {
@@ -367,7 +419,9 @@ function startOcrJob(fastify) {

    running = true;
    try {
-      const result = await runOcrOnce(fastify.prisma, fastify.config, fastify.log, workerId);
+      const result = await runOcrOnce(fastify.prisma, fastify.config, fastify.log, workerId, {
+        onInvoiceProcessed,
+      });
      fastify.metrics?.jobRunsTotal?.inc?.({
        job: "ocr.tick",
        driver: "cron",
@@ -423,9 +477,11 @@ function startOcrJob(fastify) {

 module.exports = {
  OCR_DUPLICATE_ERROR,
+  claimPendingInvoiceById,
  claimPendingInvoices,
  getEffectiveOcrProvider,
  markInvoiceAsQualityFailed,
+  runOcrForInvoiceId,
  runOcrOnce,
  startOcrJob,
 };
@@ -2,16 +2,18 @@ const PgBoss = require("pg-boss");

 const { revokeExpiredDelegations } = require("./delegationRevokeJob");
 const { archiveUnusedInvoices } = require("./invoiceArchiveJob");
-const { runOcrOnce } = require("./ocrJob");
+const { runOcrForInvoiceId, runOcrOnce } = require("./ocrJob");
 const { runVerificationForRecord } = require("./verificationJob");
 const { runIntegrationOutboxOnce } = require("./integrationOutboxJob");
 const { runErpMasterDataSyncOnce } = require("./erpMasterDataSyncJob");
+const { publishInvoiceUpdated } = require("../services/events");
 const {
  FEATURE_FLAG_KEYS,
  evaluateFeatureFlag,
 } = require("../services/featureFlags");

 const JOB_OCR_TICK = "ocr.tick";
+const JOB_OCR_INVOICE = "ocr.invoice";
 const JOB_DELEGATION_REVOKE = "delegation.revoke-expired";
 const JOB_INVOICE_ARCHIVE = "invoice.archive-unused";
 const JOB_INVOICE_VERIFY = "invoice.verify";
@@ -43,6 +45,7 @@ async function startPgBossJobs(fastify) {
  });

  await boss.createQueue(JOB_OCR_TICK);
+  await boss.createQueue(JOB_OCR_INVOICE);
  await boss.createQueue(JOB_DELEGATION_REVOKE);
  await boss.createQueue(JOB_INVOICE_ARCHIVE);
  await boss.createQueue(JOB_INVOICE_VERIFY);
@@ -51,6 +54,13 @@ async function startPgBossJobs(fastify) {
    await boss.createQueue(JOB_ERP_MASTER_DATA_SYNC);
  }

+  const onOcrInvoiceProcessed = (event) =>
+    publishInvoiceUpdated(fastify, {
+      invoiceId: event.invoiceId,
+      status: event.status,
+      audienceEmployeeIds: [event.ownerEmployeeId, event.uploadedByEmployeeId],
+    });
+
  await boss.work(JOB_DELEGATION_REVOKE, { batchSize: 1 }, async (jobs) => {
    const job = jobs?.[0];
    try {
@@ -122,7 +132,9 @@ async function startPgBossJobs(fastify) {
    const job = jobs?.[0];
    const workerId = `pgboss:ocr:${process.pid}`;
    try {
-      const stats = await runOcrOnce(fastify.prisma, fastify.config, fastify.log, workerId);
+      const stats = await runOcrOnce(fastify.prisma, fastify.config, fastify.log, workerId, {
+        onInvoiceProcessed: onOcrInvoiceProcessed,
+      });
      fastify.metrics?.jobRunsTotal?.inc?.({
        job: JOB_OCR_TICK,
        driver: "pgboss",
@@ -164,6 +176,67 @@ async function startPgBossJobs(fastify) {
    }
  });

+  await boss.work(JOB_OCR_INVOICE, { batchSize: 1 }, async (jobs) => {
+    if (!["tencent", "mock"].includes(fastify.config.ocrProvider)) {
+      return;
+    }
+
+    const job = jobs?.[0];
+    const invoiceId = job?.data?.invoiceId;
+    if (!invoiceId) {
+      return;
+    }
+
+    const workerId = `pgboss:ocr-invoice:${process.pid}`;
+    try {
+      const stats = await runOcrForInvoiceId(
+        fastify.prisma,
+        fastify.config,
+        fastify.log,
+        invoiceId,
+        workerId,
+        { onInvoiceProcessed: onOcrInvoiceProcessed },
+      );
+      fastify.metrics?.jobRunsTotal?.inc?.({
+        job: JOB_OCR_INVOICE,
+        driver: "pgboss",
+        outcome: "success",
+      });
+      if (stats.available > 0) {
+        fastify.metrics?.jobProcessedTotal?.inc?.(
+          { job: JOB_OCR_INVOICE, driver: "pgboss", kind: "available" },
+          stats.available,
+        );
+      }
+      if (stats.duplicate > 0) {
+        fastify.metrics?.jobProcessedTotal?.inc?.(
+          { job: JOB_OCR_INVOICE, driver: "pgboss", kind: "duplicate" },
+          stats.duplicate,
+        );
+      }
+      if (stats.failed > 0) {
+        fastify.metrics?.jobProcessedTotal?.inc?.(
+          { job: JOB_OCR_INVOICE, driver: "pgboss", kind: "failed" },
+          stats.failed,
+        );
+      }
+      if (stats.claimed > 0) {
+        fastify.log.info(
+          { jobId: job?.id, invoiceId, workerId, ...stats },
+          "pg-boss OCR invoice job processed",
+        );
+      }
+    } catch (error) {
+      fastify.metrics?.jobRunsTotal?.inc?.({
+        job: JOB_OCR_INVOICE,
+        driver: "pgboss",
+        outcome: "failure",
+      });
+      fastify.log.error({ err: error, jobId: job?.id, invoiceId }, "pg-boss OCR invoice job failed");
+      throw error;
+    }
+  });
+
  await boss.work(JOB_INVOICE_VERIFY, { batchSize: 1 }, async (jobs) => {
    const job = jobs?.[0];
    const recordId = job?.data?.recordId;
@@ -301,7 +374,7 @@ async function startPgBossJobs(fastify) {
    await boss.schedule(JOB_OCR_TICK, fastify.config.ocrPollCron, null, {
      tz: fastify.config.appTimezone,
      singletonKey: JOB_OCR_TICK,
-      singletonSeconds: 55,
+      singletonSeconds: 1,
    });
  } else {
    await boss.unschedule(JOB_OCR_TICK).catch(() => {});
@@ -359,12 +432,27 @@ async function startPgBossJobs(fastify) {
  return boss;
 }

+async function enqueueOcrInvoice(fastify, invoiceId) {
+  if (
+    fastify?.config?.jobDriver === "pgboss" &&
+    fastify.boss &&
+    ["tencent", "mock"].includes(fastify.config.ocrProvider)
+  ) {
+    await fastify.boss.send(JOB_OCR_INVOICE, { invoiceId });
+    return { mode: "queued" };
+  }
+
+  return { mode: "fallback" };
+}
+
 module.exports = {
+  JOB_OCR_INVOICE,
  JOB_OCR_TICK,
  JOB_DELEGATION_REVOKE,
  JOB_INVOICE_ARCHIVE,
  JOB_INVOICE_VERIFY,
  JOB_INTEGRATION_OUTBOX,
  JOB_ERP_MASTER_DATA_SYNC,
+  enqueueOcrInvoice,
  startPgBossJobs,
 };
@@ -0,0 +1,52 @@
+const { canReceiveEvent, toClientEvent } = require("../services/events");
+
+const HEARTBEAT_INTERVAL_MS = 25_000;
+
+function writeSseEvent(raw, event) {
+  const clientEvent = toClientEvent(event);
+  if (!clientEvent) {
+    return;
+  }
+
+  raw.write(`id: ${clientEvent.id}\n`);
+  raw.write(`event: ${clientEvent.type}\n`);
+  raw.write(`data: ${JSON.stringify(clientEvent)}\n\n`);
+}
+
+async function eventsRoutes(fastify) {
+  fastify.get(
+    "/events",
+    {
+      preHandler: fastify.authenticate,
+    },
+    async (request, reply) => {
+      const canManageInvoice = fastify.hasPermission(request.employee, "invoice.manage");
+      reply.hijack();
+      reply.raw.writeHead(200, {
+        "content-type": "text/event-stream; charset=utf-8",
+        "cache-control": "no-cache, no-transform",
+        "connection": "keep-alive",
+        "x-accel-buffering": "no",
+      });
+      reply.raw.write(": connected\n\n");
+
+      const unsubscribe = fastify.appEvents.subscribe((event) => {
+        if (!canReceiveEvent(request.employee, event, { canManageInvoice })) {
+          return;
+        }
+        writeSseEvent(reply.raw, event);
+      });
+
+      const heartbeat = setInterval(() => {
+        reply.raw.write(": heartbeat\n\n");
+      }, HEARTBEAT_INTERVAL_MS);
+
+      request.raw.on("close", () => {
+        clearInterval(heartbeat);
+        unsubscribe();
+      });
+    },
+  );
+}
+
+module.exports = eventsRoutes;
@@ -10,6 +10,7 @@ const { sha256Hex } = require("../utils/crypto");
 const { toMoneyString } = require("../utils/workflow");
 const { findActiveDelegationForDelegate } = require("../utils/delegation");
 const { getMissingRequiredOcrFields, isOcrEnabledForType } = require("../services/ocr");
+const { enqueueOcrInvoice } = require("../jobs/pgBossJobs");
 const { registerInvoiceVerificationRoutes } = require("./invoicePool/verification");
 const { registerInvoicePoolReadRoutes } = require("./invoicePool/read");
 const { normalizeInvoiceResponse } = require("./invoicePool/shared/mappers");
@@ -17,6 +18,7 @@ const { buildInvoiceDetailSelect } = require("./invoicePool/shared/selects");
 const { writeBuffer } = require("../services/storage");
 const {
  mapInvoiceUnavailableReason,
+  resolveInvoiceAvailability,
  resolveInvoiceDedupBlocker,
  resolveUploadDedupDecision,
 } = require("../services/invoiceGovernance");
@@ -509,6 +511,8 @@ async function invoicePoolRoutes(fastify) {
          uploadAction: uploadDedupDecision.action,
          unavailableReason: uploadDedupDecision.reason,
          unavailableMessage: message,
+          availabilityReason: uploadDedupDecision.reason,
+          availabilityMessage: message,
        });
      }

@@ -570,10 +574,20 @@ async function invoicePoolRoutes(fastify) {
        return created;
      });

+      if (invoice.status === "pending_ocr") {
+        enqueueOcrInvoice(fastify, invoice.id).catch((error) => {
+          request.log.warn({ err: error, invoiceId: invoice.id }, "Failed to enqueue OCR invoice job");
+        });
+      }
+
+      const availability = resolveInvoiceAvailability(invoice);
      return sendData(reply, request, {
        invoicePoolId: invoice.id,
        status: invoice.status,
        fileSha256: invoice.file_sha256,
+        uploadAction: "create",
+        availabilityReason: availability.reason,
+        availabilityMessage: availability.message,
      });
    },
  );
@@ -1231,6 +1245,10 @@ async function invoicePoolRoutes(fastify) {
        return updated;
      });

+      enqueueOcrInvoice(fastify, invoice.id).catch((error) => {
+        request.log.warn({ err: error, invoiceId: invoice.id }, "Failed to enqueue retry OCR invoice job");
+      });
+
      return sendData(reply, request, normalizeInvoiceResponse(invoice));
    },
  );
@@ -6,7 +6,7 @@ const { buildAuditLogData } = require("../../utils/audit");
 const { signPayload, verifyToken } = require("../../utils/signedUrl");
 const { openReadStream, StorageNotFoundError } = require("../../services/storage");
 const { toMoneyString } = require("../../utils/workflow");
-const { mapInvoiceUnavailableReason } = require("../../services/invoiceGovernance");
+const { resolveInvoiceAvailability } = require("../../services/invoiceGovernance");
 const {
  mapInvoiceSummary,
  normalizeInvoiceResponse,
@@ -106,48 +106,7 @@ function parseInvoiceStatusQuery(query) {
 }

 function resolveInvoiceStatusReason(invoice) {
-  if (invoice.status === "pending_ocr") {
-    return {
-      reason: "pending_ocr",
-      message: "发票正在识别，请稍后刷新",
-    };
-  }
-
-  if (invoice.status === "ocr_failed") {
-    const rawError = String(invoice.ocr_last_error ?? "");
-    if (rawError === "duplicate_invoice_code_number" || rawError.includes("duplicate_invoice")) {
-      return {
-        reason: "duplicate_invoice_code_number",
-        message: mapInvoiceUnavailableReason("used_by_company") ?? "发票重复，不能添加",
-      };
-    }
-    return {
-      reason: "ocr_failed",
-      message: rawError || "发票识别失败，请重新识别或手动处理",
-    };
-  }
-
-  if (invoice.status === "bound") {
-    return {
-      reason: "already_added",
-      message: "发票已添加到报销单",
-    };
-  }
-
-  if (invoice.status === "archived") {
-    return {
-      reason: invoice.archived_reason === "used_complete" ? "used_by_company" : "archived",
-      message:
-        invoice.archived_reason === "used_complete"
-          ? "该发票已用于报销，不能重复添加"
-          : "发票已归档，不可添加",
-    };
-  }
-
-  return {
-    reason: "available",
-    message: "发票可添加",
-  };
+  return resolveInvoiceAvailability(invoice);
 }

 function ensureInvoiceReadableByUser(request, invoice) {
@@ -254,6 +213,8 @@ function registerInvoicePoolReadRoutes(fastify) {
            status: invoice.status,
            reason: statusReason.reason,
            message: statusReason.message,
+            availabilityReason: statusReason.reason,
+            availabilityMessage: statusReason.message,
            invoiceCode: invoice.invoice_code ?? null,
            invoiceNumber: invoice.invoice_number ?? null,
            invoiceDate: invoice.invoice_date?.toISOString?.()?.slice(0, 10) ?? null,
@@ -1,4 +1,5 @@
 const { toMoneyString } = require("../../../utils/workflow");
+const { resolveInvoiceAvailability } = require("../../../services/invoiceGovernance");

 function mapVerificationRecord(item) {
  if (!item) {
@@ -26,10 +27,13 @@ function mapInvoiceSummary(item) {
  const latestVerification = Array.isArray(item.verification_records)
    ? item.verification_records[0] ?? null
    : null;
+  const availability = resolveInvoiceAvailability(item);

  return {
    id: item.id,
    status: item.status,
+    availabilityReason: availability.reason,
+    availabilityMessage: availability.message,
    ocrType: item.ocr_type,
    ocrProvider: item.ocr_provider,
    ocrAttempts: item.ocr_attempts,
@@ -71,10 +75,13 @@ function normalizeInvoiceResponse(invoice) {
  const latestVerification = Array.isArray(invoice.verification_records)
    ? invoice.verification_records[0] ?? null
    : null;
+  const availability = resolveInvoiceAvailability(invoice);

  return {
    id: invoice.id,
    status: invoice.status,
+    availabilityReason: availability.reason,
+    availabilityMessage: availability.message,
    archivedReason: invoice.archived_reason ?? null,
    archivedAt: invoice.archived_at?.toISOString?.() ?? null,
    ownerEmployeeId: invoice.owner_employee_id,
@@ -28,6 +28,7 @@ function buildInvoiceSummarySelect() {
  return {
    id: true,
    status: true,
+    archived_reason: true,
    ocr_type: true,
    ocr_provider: true,
    ocr_attempts: true,
@@ -0,0 +1,104 @@
+const { EventEmitter } = require("node:events");
+
+function uniqueStrings(values) {
+  return Array.from(
+    new Set(
+      (Array.isArray(values) ? values : [])
+        .map((value) => (typeof value === "string" ? value.trim() : ""))
+        .filter(Boolean),
+    ),
+  );
+}
+
+function createAppEventBus() {
+  const emitter = new EventEmitter();
+  emitter.setMaxListeners(500);
+  let sequence = 0;
+
+  return {
+    publish(event) {
+      const payload = {
+        id: `${Date.now()}-${++sequence}`,
+        createdAt: new Date().toISOString(),
+        ...event,
+        audienceEmployeeIds: uniqueStrings(event?.audienceEmployeeIds),
+      };
+      emitter.emit("event", payload);
+      return payload;
+    },
+    subscribe(handler) {
+      emitter.on("event", handler);
+      return () => emitter.off("event", handler);
+    },
+  };
+}
+
+function buildInvoiceUpdatedEvent({
+  invoiceId,
+  status,
+  updatedAt = null,
+  audienceEmployeeIds = [],
+}) {
+  return {
+    type: "invoice.updated",
+    invoiceId,
+    status,
+    updatedAt: updatedAt ?? new Date().toISOString(),
+    audienceEmployeeIds: uniqueStrings(audienceEmployeeIds),
+  };
+}
+
+function publishInvoiceUpdated(fastify, event) {
+  if (!fastify?.appEvents || typeof fastify.appEvents.publish !== "function") {
+    return null;
+  }
+  return fastify.appEvents.publish(buildInvoiceUpdatedEvent(event));
+}
+
+function canReceiveEvent(employee, event, options = {}) {
+  if (!employee) {
+    return false;
+  }
+
+  if (event?.type === "invoice.updated" && options.canManageInvoice) {
+    return true;
+  }
+
+  const audience = uniqueStrings(event?.audienceEmployeeIds);
+  if (!audience.length) {
+    return false;
+  }
+
+  return audience.includes(employee.id);
+}
+
+function toClientEvent(event) {
+  if (!event) {
+    return null;
+  }
+
+  if (event.type === "invoice.updated") {
+    return {
+      id: event.id,
+      type: event.type,
+      invoiceId: event.invoiceId,
+      status: event.status ?? null,
+      updatedAt: event.updatedAt ?? event.createdAt ?? null,
+      createdAt: event.createdAt ?? null,
+    };
+  }
+
+  return {
+    id: event.id,
+    type: event.type,
+    createdAt: event.createdAt ?? null,
+  };
+}
+
+module.exports = {
+  buildInvoiceUpdatedEvent,
+  canReceiveEvent,
+  createAppEventBus,
+  publishInvoiceUpdated,
+  toClientEvent,
+};
@@ -8,6 +8,14 @@ const INVOICE_UNAVAILABLE_REASONS = {
  usedByCompany: "used_by_company",
 };

+const OCR_FIELD_LABELS = {
+  invoiceCode: "发票代码",
+  invoiceNumber: "发票号码",
+  invoiceDate: "开票日期",
+  totalAmount: "总金额",
+  sellerName: "销售方",
+};
+
 function buildInvoiceDedupFilters({ fileSha256 = null, invoiceCode = null, invoiceNumber = null }) {
  const filters = [];
  if (fileSha256) {
@@ -182,13 +190,100 @@ function mapInvoiceUnavailableReason(reason) {
  }
 }

+function parseMissingInvoiceOcrFields(rawError) {
+  if (typeof rawError !== "string") {
+    return [];
+  }
+
+  const matched = rawError.match(/^missing_required_fields:(.+)$/);
+  if (!matched?.[1]) {
+    return [];
+  }
+
+  return matched[1]
+    .split(",")
+    .map((field) => field.trim())
+    .filter(Boolean);
+}
+
+function formatInvoiceOcrFailureMessage(rawError) {
+  const missingFields = parseMissingInvoiceOcrFields(rawError);
+  if (missingFields.length) {
+    const labels = missingFields.map((field) => OCR_FIELD_LABELS[field] ?? field);
+    return `票据识别缺少关键字段：${labels.join("、")}。`;
+  }
+
+  if (rawError === "mock_ocr_failed") {
+    return "票据识别失败，请重试或人工补齐关键信息。";
+  }
+
+  if (!rawError) {
+    return "票据识别失败，请稍后重试。";
+  }
+
+  return "票据识别失败，请重新识别或手动处理。";
+}
+
+function resolveInvoiceAvailability(invoice) {
+  if (!invoice) {
+    return {
+      reason: "not_found",
+      message: "未找到发票",
+    };
+  }
+
+  if (invoice.status === "pending_ocr") {
+    return {
+      reason: "pending_ocr",
+      message: "发票正在识别，完成后会自动刷新",
+    };
+  }
+
+  if (invoice.status === "ocr_failed") {
+    const rawError = String(invoice.ocr_last_error ?? "");
+    if (rawError === "duplicate_invoice_code_number" || rawError.includes("duplicate_invoice")) {
+      return {
+        reason: "duplicate_invoice",
+        message: "已识别出相同发票，不能重复添加",
+      };
+    }
+
+    return {
+      reason: "ocr_failed",
+      message: formatInvoiceOcrFailureMessage(rawError),
+    };
+  }
+
+  if (isUsedInvoice(invoice)) {
+    return {
+      reason: INVOICE_UNAVAILABLE_REASONS.usedByCompany,
+      message: mapInvoiceUnavailableReason(INVOICE_UNAVAILABLE_REASONS.usedByCompany),
+    };
+  }
+
+  if (invoice.status === "archived") {
+    return {
+      reason: "archived",
+      message: "发票已归档，不可添加",
+    };
+  }
+
+  return {
+    reason: "available",
+    message: "发票可添加",
+  };
+}
+
 module.exports = {
  INVOICE_UNAVAILABLE_REASONS,
  buildInvoiceDedupFilters,
  classifyInvoiceConflict,
  findInvoiceDedupConflicts,
+  formatInvoiceOcrFailureMessage,
  isUsedInvoice,
  mapInvoiceUnavailableReason,
+  parseMissingInvoiceOcrFields,
+  resolveInvoiceAvailability,
  resolveInvoiceDedupBlocker,
  resolveUploadDedupDecision,
 };