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

server/src/app.js

@@ -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" });

server/src/jobs/ocrJob.js

@@ -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,
 };

server/src/jobs/pgBossJobs.js

@@ -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,
 };

server/src/routes/events.js

@@ -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;

server/src/routes/invoicePool.js

@@ -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));
     },
   );

server/src/routes/invoicePool/read.js

@@ -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,

server/src/routes/invoicePool/shared/mappers.js

@@ -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,

server/src/routes/invoicePool/shared/selects.js

@@ -28,6 +28,7 @@ function buildInvoiceSummarySelect() {
   return {
     id: true,
     status: true,
+    archived_reason: true,
     ocr_type: true,
     ocr_provider: true,
     ocr_attempts: true,

server/src/services/events.js

@@ -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,
+};

server/src/services/invoiceGovernance.js

@@ -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,
 };

server/tests/unit/invoiceGovernance.dedup.test.js

@@ -1,6 +1,8 @@
 const {
   INVOICE_UNAVAILABLE_REASONS,
   classifyInvoiceConflict,
+  formatInvoiceOcrFailureMessage,
+  resolveInvoiceAvailability,
   resolveUploadDedupDecision,
 } = require("../../src/services/invoiceGovernance");
 
@@ -17,6 +19,7 @@ function buildInvoice(overrides = {}) {
     file_sha256: overrides.file_sha256 ?? "sha256-a",
     invoice_code: overrides.invoice_code ?? null,
     invoice_number: overrides.invoice_number ?? null,
+    ocr_last_error: overrides.ocr_last_error ?? null,
   };
 }
 
@@ -90,4 +93,34 @@ describe("invoiceGovernance dedup", () => {
     expect(decision.action).toBe("blocked");
     expect(decision.reason).toBe(INVOICE_UNAVAILABLE_REASONS.duplicateOtherOwner);
   });
+
+  it("formats invoice availability without leaking raw OCR error codes", () => {
+    expect(
+      resolveInvoiceAvailability(
+        buildInvoice({
+          status: "ocr_failed",
+          ocr_last_error: "missing_required_fields:invoiceCode,sellerName",
+        }),
+      ),
+    ).toEqual({
+      reason: "ocr_failed",
+      message: "票据识别缺少关键字段：发票代码、销售方。",
+    });
+
+    expect(
+      resolveInvoiceAvailability(
+        buildInvoice({
+          status: "ocr_failed",
+          ocr_last_error: "duplicate_invoice_code_number",
+        }),
+      ),
+    ).toEqual({
+      reason: "duplicate_invoice",
+      message: "已识别出相同发票，不能重复添加",
+    });
+
+    expect(formatInvoiceOcrFailureMessage("mock_ocr_failed")).toBe(
+      "票据识别失败，请重试或人工补齐关键信息。",
+    );
+  });
 });

server/tests/unit/jobs/ocrJob.test.js

@@ -2,12 +2,14 @@ const fs = require("node:fs/promises");
 const os = require("node:os");
 const path = require("node:path");
 
-const { runOcrOnce } = require("../../../src/jobs/ocrJob");
+const { runOcrForInvoiceId, runOcrOnce } = require("../../../src/jobs/ocrJob");
 
 function buildClaimedInvoice(overrides = {}) {
   return {
     id: "11111111-1111-4111-8111-111111111111",
     file_sha256: "sha256-1",
+    owner_employee_id: "employee-owner-1",
+    uploaded_by_employee_id: "employee-upload-1",
     ocr_provider: "mock",
     ocr_type: "vat",
     storage_path: "20260428/invoice.txt",
@@ -91,6 +93,45 @@ describe("ocrJob quality gate", () => {
     );
   });
 
+  it("processes a directed invoice and emits processed metadata", async () => {
+    await fs.writeFile(
+      path.join(tempDir, "20260428/invoice.txt"),
+      "MOCK_DIRECTED_SUCCESS_R73",
+      "utf8",
+    );
+
+    const prisma = buildPrisma([buildClaimedInvoice()]);
+    const logger = {
+      warn: vi.fn(),
+      error: vi.fn(),
+    };
+    const onInvoiceProcessed = vi.fn();
+
+    const result = await runOcrForInvoiceId(
+      prisma,
+      {
+        storageDir: tempDir,
+        ocrBatchSize: 10,
+        ocrLockTtlSeconds: 300,
+        ocrMaxAttempts: 3,
+        ocrProvider: "mock",
+      },
+      logger,
+      "11111111-1111-4111-8111-111111111111",
+      "ocr-directed-worker",
+      { onInvoiceProcessed },
+    );
+
+    expect(result).toEqual({ claimed: 1, available: 1, duplicate: 0, failed: 0 });
+    expect(onInvoiceProcessed).toHaveBeenCalledWith({
+      invoiceId: "11111111-1111-4111-8111-111111111111",
+      status: "available",
+      outcome: "available",
+      ownerEmployeeId: "employee-owner-1",
+      uploadedByEmployeeId: "employee-upload-1",
+    });
+  });
+
   it("marks invoice ocr_failed when required VAT fields are missing", async () => {
     await fs.writeFile(
       path.join(tempDir, "20260428/invoice.txt"),

server/tests/unit/jobs/pgBossJobs.test.js

@@ -0,0 +1,56 @@
+const { enqueueOcrInvoice, JOB_OCR_INVOICE } = require("../../../src/jobs/pgBossJobs");
+
+describe("pgBossJobs enqueueOcrInvoice", () => {
+  it("queues a directed OCR invoice job when pg-boss is available", async () => {
+    const send = vi.fn(async () => ({ id: "job-1" }));
+
+    const result = await enqueueOcrInvoice(
+      {
+        config: {
+          jobDriver: "pgboss",
+          ocrProvider: "mock",
+        },
+        boss: { send },
+      },
+      "11111111-1111-4111-8111-111111111111",
+    );
+
+    expect(result).toEqual({ mode: "queued" });
+    expect(send).toHaveBeenCalledWith(JOB_OCR_INVOICE, {
+      invoiceId: "11111111-1111-4111-8111-111111111111",
+    });
+  });
+
+  it("falls back cleanly when pg-boss is unavailable", async () => {
+    await expect(
+      enqueueOcrInvoice(
+        {
+          config: {
+            jobDriver: "pgboss",
+            ocrProvider: "mock",
+          },
+          boss: null,
+        },
+        "11111111-1111-4111-8111-111111111111",
+      ),
+    ).resolves.toEqual({ mode: "fallback" });
+  });
+
+  it("does not queue OCR when the OCR provider is disabled", async () => {
+    const send = vi.fn();
+
+    const result = await enqueueOcrInvoice(
+      {
+        config: {
+          jobDriver: "pgboss",
+          ocrProvider: "off",
+        },
+        boss: { send },
+      },
+      "11111111-1111-4111-8111-111111111111",
+    );
+
+    expect(result).toEqual({ mode: "fallback" });
+    expect(send).not.toHaveBeenCalled();
+  });
+});

server/tests/unit/routes/events.test.js

@@ -0,0 +1,52 @@
+const Fastify = require("fastify");
+
+const eventsRoutes = require("../../../src/routes/events");
+const { createAppEventBus } = require("../../../src/services/events");
+const { AppError } = require("../../../src/utils/AppError");
+
+async function buildApp() {
+  const app = Fastify();
+  app.decorate("appEvents", createAppEventBus());
+  app.decorate("authenticate", async (request) => {
+    const auth = request.headers.authorization ?? "";
+    if (!auth.startsWith("Bearer ")) {
+      throw new AppError({ code: "AUTH_001", message: "未登录", statusCode: 401 });
+    }
+    request.employee = { id: "employee-1", permissionCodes: [] };
+  });
+  app.decorate("hasPermission", (employee, permissionCode) =>
+    (employee?.permissionCodes ?? []).includes(permissionCode),
+  );
+  app.setErrorHandler((error, request, reply) => {
+    if (error instanceof AppError) {
+      return reply.status(error.statusCode).send({
+        error: {
+          code: error.code,
+          message: error.message,
+          details: error.details ?? {},
+        },
+      });
+    }
+    return reply.status(500).send({ error: { code: "SYS_001", message: "服务异常" } });
+  });
+  await app.register(eventsRoutes, { prefix: "/api" });
+  return app;
+}
+
+describe("GET /api/events", () => {
+  it("requires bearer authentication before opening the event stream", async () => {
+    const app = await buildApp();
+
+    try {
+      const response = await app.inject({
+        method: "GET",
+        url: "/api/events",
+      });
+
+      expect(response.statusCode).toBe(401);
+      expect(response.json().error.code).toBe("AUTH_001");
+    } finally {
+      await app.close();
+    }
+  });
+});

server/tests/unit/routes/invoicePool.upload.test.js

@@ -38,6 +38,8 @@ function buildMultipartRequest({ filename, contentType, content, fields = [] })
 
 async function buildApp({
   ocrProvider = "off",
+  jobDriver = "cron",
+  bossSend = null,
   invoiceConflicts = [],
   statusRows = [],
   permissionCodes = ["invoice.upload"],
@@ -75,7 +77,11 @@ async function buildApp({
     maxUploadSizeBytes: 5 * 1024 * 1024,
     invoiceArchiveUnusedDays: 30,
     ocrProvider,
+    jobDriver,
   });
+  if (bossSend) {
+    app.decorate("boss", { send: bossSend });
+  }
   app.decorate("authenticate", async (request) => {
     if (!request.headers.authorization) {
       throw new AppError({ code: "AUTH_001", message: "未登录", statusCode: 401 });
@@ -177,8 +183,13 @@ describe("invoicePool upload route", () => {
     }
   });
 
-  it("puts VAT uploads into pending_ocr when OCR provider is enabled", async () => {
-    const { app, prisma, tempDir } = await buildApp({ ocrProvider: "mock" });
+  it("puts VAT uploads into pending_ocr and enqueues a directed OCR job when OCR provider is enabled", async () => {
+    const bossSend = vi.fn(async () => ({ id: "ocr-job-1" }));
+    const { app, prisma, tempDir } = await buildApp({
+      ocrProvider: "mock",
+      jobDriver: "pgboss",
+      bossSend,
+    });
 
     try {
       const requestPayload = buildMultipartRequest({
@@ -214,6 +225,9 @@ describe("invoicePool upload route", () => {
           }),
         }),
       );
+      expect(bossSend).toHaveBeenCalledWith("ocr.invoice", {
+        invoiceId: "11111111-1111-4111-8111-111111111111",
+      });
     } finally {
       await app.close();
       await fs.rm(tempDir, { recursive: true, force: true });

server/tests/unit/routes/reimbursements.create.test.js

@@ -133,6 +133,7 @@ async function buildApp(options = {}) {
     ],
     travelRequests: (options.travelRequests ?? [buildTravelRequest()]).map((item) => cloneTravelRequest(item)),
     auditLogs: [],
+    sequenceNumber: 0,
   };
 
   function buildReimbursementSelect(record, select) {
@@ -236,6 +237,28 @@ async function buildApp(options = {}) {
           return found ? cloneTravelRequest(found) : null;
         }),
       },
+      documentSequence: {
+        findUnique: vi.fn(async () => null),
+        upsert: vi.fn(async ({ create, update }) => {
+          stateRef.sequenceNumber = (stateRef.sequenceNumber ?? 0) + 1;
+          return {
+            document_type: create.document_type,
+            prefix: update.prefix ?? create.prefix,
+            date_format: update.date_format ?? create.date_format,
+            separator: update.separator ?? create.separator,
+            number_length: update.number_length ?? create.number_length,
+            reset_period: update.reset_period ?? create.reset_period,
+            current_number: stateRef.sequenceNumber,
+            last_reset_date: null,
+            updated_at: new Date("2026-04-08T12:00:00.000Z"),
+            updated_by: update.updated_by ?? create.updated_by ?? null,
+          };
+        }),
+      },
+      documentCategory: {
+        findUnique: vi.fn(async () => null),
+        findFirst: vi.fn(async () => null),
+      },
       reimbursementForm: {
         create: vi.fn(async ({ data, select }) => {
           const record = {
@@ -317,6 +340,7 @@ async function buildApp(options = {}) {
       expenseTypes: state.expenseTypes.map((item) => ({ ...item })),
       travelRequests: state.travelRequests.map((item) => cloneTravelRequest(item)),
       auditLogs: state.auditLogs.map((item) => ({ ...item })),
+      sequenceNumber: state.sequenceNumber,
     };
     const tx = buildPrismaLike(txState);
     const result = await callback(tx);
@@ -327,6 +351,7 @@ async function buildApp(options = {}) {
     state.expenseTypes = txState.expenseTypes;
     state.travelRequests = txState.travelRequests;
     state.auditLogs = txState.auditLogs;
+    state.sequenceNumber = txState.sequenceNumber;
     return result;
   });
 

server/tests/unit/routes/reimbursements.detail.test.js

@@ -44,6 +44,7 @@ function buildReimbursementRecord(overrides = {}) {
         },
       },
     ],
+    attachments: [],
     invoice_pool_items: [
       {
         id: "invoice-1",

server/tests/unit/services/events.test.js

@@ -0,0 +1,67 @@
+const {
+  buildInvoiceUpdatedEvent,
+  canReceiveEvent,
+  createAppEventBus,
+  toClientEvent,
+} = require("../../../src/services/events");
+
+describe("app events", () => {
+  it("publishes minimal invoice updated events", () => {
+    const event = buildInvoiceUpdatedEvent({
+      invoiceId: "11111111-1111-4111-8111-111111111111",
+      status: "available",
+      audienceEmployeeIds: ["employee-1", "employee-1", ""],
+      updatedAt: "2026-05-09T10:00:00.000Z",
+    });
+
+    expect(event).toEqual({
+      type: "invoice.updated",
+      invoiceId: "11111111-1111-4111-8111-111111111111",
+      status: "available",
+      updatedAt: "2026-05-09T10:00:00.000Z",
+      audienceEmployeeIds: ["employee-1"],
+    });
+
+    expect(toClientEvent({ id: "evt-1", createdAt: "2026-05-09T10:00:01.000Z", ...event })).toEqual({
+      id: "evt-1",
+      type: "invoice.updated",
+      invoiceId: "11111111-1111-4111-8111-111111111111",
+      status: "available",
+      updatedAt: "2026-05-09T10:00:00.000Z",
+      createdAt: "2026-05-09T10:00:01.000Z",
+    });
+  });
+
+  it("filters invoice events by employee audience unless invoice manager", () => {
+    const event = buildInvoiceUpdatedEvent({
+      invoiceId: "11111111-1111-4111-8111-111111111111",
+      status: "available",
+      audienceEmployeeIds: ["employee-1"],
+    });
+
+    expect(canReceiveEvent({ id: "employee-1" }, event)).toBe(true);
+    expect(canReceiveEvent({ id: "employee-2" }, event)).toBe(false);
+    expect(canReceiveEvent({ id: "employee-2" }, event, { canManageInvoice: true })).toBe(true);
+  });
+
+  it("supports subscribe and unsubscribe on the in-process event bus", () => {
+    const bus = createAppEventBus();
+    const handler = vi.fn();
+    const unsubscribe = bus.subscribe(handler);
+
+    bus.publish({ type: "invoice.updated", invoiceId: "invoice-1", audienceEmployeeIds: ["employee-1"] });
+    unsubscribe();
+    bus.publish({ type: "invoice.updated", invoiceId: "invoice-2", audienceEmployeeIds: ["employee-1"] });
+
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler.mock.calls[0][0]).toEqual(
+      expect.objectContaining({
+        id: expect.any(String),
+        createdAt: expect.any(String),
+        type: "invoice.updated",
+        invoiceId: "invoice-1",
+        audienceEmployeeIds: ["employee-1"],
+      }),
+    );
+  });
+});