feat(server): /metrics 可观测与日志上下文（F22）

- 新增 Prometheus 指标端点 /metrics（HTTP + DB + 作业统计）
- request.log 绑定 requestId/actorId，避免日志难追踪
- cron/pg-boss 作业增加 metrics 计数（runs/processed）
- 更新 env/runbook/README 与 v3 CSV 状态推进

server/src/jobs/delegationRevokeJob.js

@@ -92,9 +92,29 @@ function startDelegationRevokeJob(fastify) {
 
     running = true;
     try {
-      await revokeExpiredDelegations(fastify.prisma, fastify.log);
+      const revoked = await revokeExpiredDelegations(fastify.prisma, fastify.log);
+      fastify.metrics?.jobRunsTotal?.inc?.({
+        job: "delegation.revoke-expired",
+        driver: "cron",
+        outcome: "success",
+      });
+      if (revoked > 0) {
+        fastify.metrics?.jobProcessedTotal?.inc?.(
+          {
+            job: "delegation.revoke-expired",
+            driver: "cron",
+            kind: "revoked",
+          },
+          revoked,
+        );
+      }
     } catch (error) {
       fastify.log.error({ err: error }, "Delegation revoke job failed");
+      fastify.metrics?.jobRunsTotal?.inc?.({
+        job: "delegation.revoke-expired",
+        driver: "cron",
+        outcome: "failure",
+      });
     } finally {
       running = false;
     }

server/src/jobs/invoiceArchiveJob.js

@@ -76,12 +76,32 @@ function startInvoiceArchiveJob(fastify) {
 
     running = true;
     try {
-      await archiveUnusedInvoices(fastify.prisma, fastify.log, {
+      const archived = await archiveUnusedInvoices(fastify.prisma, fastify.log, {
         batchSize: fastify.config.invoiceArchiveBatchSize,
         unusedDays: fastify.config.invoiceArchiveUnusedDays,
       });
+      fastify.metrics?.jobRunsTotal?.inc?.({
+        job: "invoice.archive-unused",
+        driver: "cron",
+        outcome: "success",
+      });
+      if (archived > 0) {
+        fastify.metrics?.jobProcessedTotal?.inc?.(
+          {
+            job: "invoice.archive-unused",
+            driver: "cron",
+            kind: "archived",
+          },
+          archived,
+        );
+      }
     } catch (error) {
       fastify.log.error({ err: error }, "Invoice archive job failed");
+      fastify.metrics?.jobRunsTotal?.inc?.({
+        job: "invoice.archive-unused",
+        driver: "cron",
+        outcome: "failure",
+      });
     } finally {
       running = false;
     }
@@ -107,4 +127,3 @@ module.exports = {
   archiveUnusedInvoices,
   startInvoiceArchiveJob,
 };
-

server/src/jobs/ocrJob.js

@@ -301,6 +301,29 @@ function startOcrJob(fastify) {
     running = true;
     try {
       const result = await runOcrOnce(fastify.prisma, fastify.config, fastify.log, workerId);
+      fastify.metrics?.jobRunsTotal?.inc?.({
+        job: "ocr.tick",
+        driver: "cron",
+        outcome: "success",
+      });
+      if (result.available > 0) {
+        fastify.metrics?.jobProcessedTotal?.inc?.(
+          { job: "ocr.tick", driver: "cron", kind: "available" },
+          result.available,
+        );
+      }
+      if (result.duplicate > 0) {
+        fastify.metrics?.jobProcessedTotal?.inc?.(
+          { job: "ocr.tick", driver: "cron", kind: "duplicate" },
+          result.duplicate,
+        );
+      }
+      if (result.failed > 0) {
+        fastify.metrics?.jobProcessedTotal?.inc?.(
+          { job: "ocr.tick", driver: "cron", kind: "failed" },
+          result.failed,
+        );
+      }
       if (result.claimed > 0) {
         fastify.log.info(
           {
@@ -312,6 +335,11 @@ function startOcrJob(fastify) {
       }
     } catch (error) {
       fastify.log.error({ err: error }, "OCR job tick failed");
+      fastify.metrics?.jobRunsTotal?.inc?.({
+        job: "ocr.tick",
+        driver: "cron",
+        outcome: "failure",
+      });
     } finally {
       running = false;
     }

server/src/jobs/pgBossJobs.js

@@ -38,26 +38,64 @@ async function startPgBossJobs(fastify) {
 
   await boss.work(JOB_DELEGATION_REVOKE, { batchSize: 1 }, async (jobs) => {
     const job = jobs?.[0];
-    const revoked = await revokeExpiredDelegations(fastify.prisma, fastify.log);
-    if (revoked > 0) {
-      fastify.log.info(
-        { jobId: job?.id, revoked },
-        "pg-boss delegation revoke tick processed",
-      );
+    try {
+      const revoked = await revokeExpiredDelegations(fastify.prisma, fastify.log);
+      fastify.metrics?.jobRunsTotal?.inc?.({
+        job: JOB_DELEGATION_REVOKE,
+        driver: "pgboss",
+        outcome: "success",
+      });
+      if (revoked > 0) {
+        fastify.metrics?.jobProcessedTotal?.inc?.(
+          { job: JOB_DELEGATION_REVOKE, driver: "pgboss", kind: "revoked" },
+          revoked,
+        );
+        fastify.log.info(
+          { jobId: job?.id, revoked },
+          "pg-boss delegation revoke tick processed",
+        );
+      }
+    } catch (error) {
+      fastify.metrics?.jobRunsTotal?.inc?.({
+        job: JOB_DELEGATION_REVOKE,
+        driver: "pgboss",
+        outcome: "failure",
+      });
+      fastify.log.error({ err: error, jobId: job?.id }, "pg-boss delegation revoke tick failed");
+      throw error;
     }
   });
 
   await boss.work(JOB_INVOICE_ARCHIVE, { batchSize: 1 }, async (jobs) => {
     const job = jobs?.[0];
-    const archived = await archiveUnusedInvoices(fastify.prisma, fastify.log, {
-      batchSize: fastify.config.invoiceArchiveBatchSize,
-      unusedDays: fastify.config.invoiceArchiveUnusedDays,
-    });
-    if (archived > 0) {
-      fastify.log.info(
-        { jobId: job?.id, archived, unusedDays: fastify.config.invoiceArchiveUnusedDays },
-        "pg-boss invoice archive tick processed",
-      );
+    try {
+      const archived = await archiveUnusedInvoices(fastify.prisma, fastify.log, {
+        batchSize: fastify.config.invoiceArchiveBatchSize,
+        unusedDays: fastify.config.invoiceArchiveUnusedDays,
+      });
+      fastify.metrics?.jobRunsTotal?.inc?.({
+        job: JOB_INVOICE_ARCHIVE,
+        driver: "pgboss",
+        outcome: "success",
+      });
+      if (archived > 0) {
+        fastify.metrics?.jobProcessedTotal?.inc?.(
+          { job: JOB_INVOICE_ARCHIVE, driver: "pgboss", kind: "archived" },
+          archived,
+        );
+        fastify.log.info(
+          { jobId: job?.id, archived, unusedDays: fastify.config.invoiceArchiveUnusedDays },
+          "pg-boss invoice archive tick processed",
+        );
+      }
+    } catch (error) {
+      fastify.metrics?.jobRunsTotal?.inc?.({
+        job: JOB_INVOICE_ARCHIVE,
+        driver: "pgboss",
+        outcome: "failure",
+      });
+      fastify.log.error({ err: error, jobId: job?.id }, "pg-boss invoice archive tick failed");
+      throw error;
     }
   });
 
@@ -68,12 +106,46 @@ async function startPgBossJobs(fastify) {
 
     const job = jobs?.[0];
     const workerId = `pgboss:ocr:${process.pid}`;
-    const stats = await runOcrOnce(fastify.prisma, fastify.config, fastify.log, workerId);
-    if (stats.claimed > 0) {
-      fastify.log.info(
-        { jobId: job?.id, workerId, ...stats },
-        "pg-boss OCR tick processed",
-      );
+    try {
+      const stats = await runOcrOnce(fastify.prisma, fastify.config, fastify.log, workerId);
+      fastify.metrics?.jobRunsTotal?.inc?.({
+        job: JOB_OCR_TICK,
+        driver: "pgboss",
+        outcome: "success",
+      });
+      if (stats.available > 0) {
+        fastify.metrics?.jobProcessedTotal?.inc?.(
+          { job: JOB_OCR_TICK, driver: "pgboss", kind: "available" },
+          stats.available,
+        );
+      }
+      if (stats.duplicate > 0) {
+        fastify.metrics?.jobProcessedTotal?.inc?.(
+          { job: JOB_OCR_TICK, driver: "pgboss", kind: "duplicate" },
+          stats.duplicate,
+        );
+      }
+      if (stats.failed > 0) {
+        fastify.metrics?.jobProcessedTotal?.inc?.(
+          { job: JOB_OCR_TICK, driver: "pgboss", kind: "failed" },
+          stats.failed,
+        );
+      }
+
+      if (stats.claimed > 0) {
+        fastify.log.info(
+          { jobId: job?.id, workerId, ...stats },
+          "pg-boss OCR tick processed",
+        );
+      }
+    } catch (error) {
+      fastify.metrics?.jobRunsTotal?.inc?.({
+        job: JOB_OCR_TICK,
+        driver: "pgboss",
+        outcome: "failure",
+      });
+      fastify.log.error({ err: error, jobId: job?.id }, "pg-boss OCR tick failed");
+      throw error;
     }
   });