feat(server): 完成 F19~F19d pg-boss 作业系统迁移\n\n- 引入 pg-boss(JOB_DRIVER=pgboss)并保留 cron 回滚\n- OCR/委派回收/超期归档改由 pg-boss schedule + work 执行\n- OCR_PROVIDER=off 自动 unschedule ocr.tick\n- 更新 trialrun env/compose/runbook 与 README,并推进 CSV 状态为 DONE

这个提交包含在:
2026-02-09 20:05:01 +08:00
父节点 f233a0d5bc
当前提交 dff1aabc26
共修改 11 个文件,包含 249 行新增和 12 行删除
@@ -17,10 +17,10 @@ F15,邮件通知(SMTP/Nodemailer),"引入 nodemailer 发送邮件:新待
F16,前端通知入口(Bell),"新增通知列表页/弹层与未读角标;支持标记已读","四角色均可见自己的通知;读写后角标正确;e2e 覆盖核心路径","cd client && npm run test:e2e",manual,DONE,DONE,DONE,"client/src/components/navigation/Topbar.tsx | client/src/pages/NotificationsPage.tsx | client/src/api/notifications.ts","[""F14""]","保持 UI 轻量,不做复杂订阅推送"
F17,报表导出(CSV/Excel),"新增报销/票据/审计的导出接口(权限控制),前端提供下载入口","导出字段与权限正确;大数据量时可分页/流式输出;审计记录导出操作","manual: 导出后核对字段;并在 audit_logs 中检索 EXPORT 动作",manual,DONE,DONE,DONE,"server/src/routes/exports.js | server/src/app.js | server/package.json | server/package-lock.json | client/src/api/exports.ts | client/src/api/http.ts | client/src/lib/download.ts | client/src/pages/ReimbursementsPage.tsx | client/src/pages/InvoicePoolPage.tsx | client/src/pages/AuditLogsPage.tsx","[""F6"",""F16""]","选型:exceljs(XLSX),CSV 采用流式生成;回滚:删除 exportsRoutes 注册与依赖即可"
F18,审批规则维护(system.settings),"补齐 approval_rules 维护 API 与最小前端页(finance_mgr/admin),支持启停与优先级/金额段维护","规则变更可立即影响新 submit;历史 instance 不回写;审计记录变更","cd server && ./scripts/regression-workflow-actions.sh",manual,DONE,DONE,DONE,"server/src/routes/approvalRules.js | server/src/app.js | client/src/pages/ApprovalRulesPage.tsx | client/src/api/approvalRules.ts | client/src/router/index.tsx | client/src/components/navigation/NavLinks.tsx","[""F5""]","只做最小可运营;复杂可视化后置"
F19,作业系统升级(pg-boss 基础设施),"引入 pg-boss(Postgres 队列)作为作业基础设施:提供统一注册/执行框架与开关;保持 node-cron 作业可回滚;并文档化单机用法","pg-boss 可在单机/多进程下可靠运行;最小示例 job 可跑通;不影响现有回归","cd server && ./scripts/regression-all.sh",manual,TODO,TODO,TODO,"server/src/jobs/* | server/src/app.js | server/package.json | deploy/trialrun/* | server/README.md","[""F1""]","选择 pg-boss(成熟/无 Redis);回滚:关闭开关并切回 node-cron"
F19b,作业迁移(OCR -> pg-boss),"将 OCR 异步处理迁移到 pg-boss:保持并发锁语义、幂等与回归脚本不变","mock/tencent 两种 provider 下 OCR 仍可跑;并发下单条仅处理一次;回归全绿","cd server && ./scripts/regression-ocr.sh && ./scripts/regression-all.sh",manual,TODO,TODO,TODO,"server/src/jobs/ocrJob.js | server/src/services/ocr/* | server/README.md","[""F19""]","迁移后移除/停用对应 node-cron tick(保留回滚路径)"
F19c,作业迁移(委派回收 -> pg-boss),"将委派过期回收迁移到 pg-boss:保持 FOR UPDATE SKIP LOCKED + UPDATE RETURNING 原子认领语义","多进程并发下审计不重复写;回收逻辑不变;回归全绿","cd server && RUN_DELEGATION_CONCURRENCY_CHECK=1 ./scripts/regression-workflow-actions.sh",manual,TODO,TODO,TODO,"server/src/jobs/delegationRevokeJob.js | server/README.md","[""F19""]","仍需保留原子认领+审计只基于 RETURNING 结果集"
F19d,作业迁移(超期归档 -> pg-boss),"将 90 天游离归档迁移到 pg-boss(替代 node-cron),统一重试/并发/可观测字段","作业可重复执行幂等;多进程不重复处理;回归全绿","cd server && ./scripts/regression-ocr.sh && ./scripts/regression-all.sh",manual,TODO,TODO,TODO,"server/src/jobs/invoiceArchiveJob.js | server/README.md","[""F19"",""F12""]","迁移后在 README 标注调度频率与开关"
F19,作业系统升级(pg-boss 基础设施),"引入 pg-boss(Postgres 队列)作为作业基础设施:提供统一注册/执行框架与开关;保持 node-cron 作业可回滚;并文档化单机用法","pg-boss 可在单机/多进程下可靠运行;最小示例 job 可跑通;不影响现有回归","cd server && ./scripts/regression-all.sh",manual,DONE,DONE,DONE,"server/src/jobs/jobSystem.js | server/src/jobs/pgBossJobs.js | server/src/app.js | server/src/config.js | server/package.json | server/package-lock.json | server/README.md | deploy/trialrun/.env.example | deploy/trialrun/docker-compose.yml | deploy/trialrun/runbook.md","[""F1""]","选择 pg-boss(成熟/无 Redis);回滚:JOB_DRIVER=cron 或 JOBS_ENABLED=false"
F19b,作业迁移(OCR -> pg-boss),"将 OCR 异步处理迁移到 pg-boss:保持并发锁语义、幂等与回归脚本不变","mock/tencent 两种 provider 下 OCR 仍可跑;并发下单条仅处理一次;回归全绿","cd server && ./scripts/regression-ocr.sh && ./scripts/regression-all.sh",manual,DONE,DONE,DONE,"server/src/jobs/pgBossJobs.js | server/src/jobs/ocrJob.js | server/src/jobs/jobSystem.js | server/src/config.js | server/README.md","[""F19""]","pg-boss schedule 支持秒级 cron;OCR_PROVIDER=off 时自动 unschedule ocr.tick"
F19c,作业迁移(委派回收 -> pg-boss),"将委派过期回收迁移到 pg-boss:保持 FOR UPDATE SKIP LOCKED + UPDATE RETURNING 原子认领语义","多进程并发下审计不重复写;回收逻辑不变;回归全绿","cd server && RUN_DELEGATION_CONCURRENCY_CHECK=1 ./scripts/regression-workflow-actions.sh",manual,DONE,DONE,DONE,"server/src/jobs/pgBossJobs.js | server/src/jobs/delegationRevokeJob.js | server/src/jobs/jobSystem.js | server/README.md","[""F19""]","仍保留原子认领+审计只基于 RETURNING 结果集"
F19d,作业迁移(超期归档 -> pg-boss),"将 90 天游离归档迁移到 pg-boss(替代 node-cron),统一重试/并发/可观测字段","作业可重复执行幂等;多进程不重复处理;回归全绿","cd server && ./scripts/regression-ocr.sh && ./scripts/regression-all.sh",manual,DONE,DONE,DONE,"server/src/jobs/pgBossJobs.js | server/src/jobs/invoiceArchiveJob.js | server/src/jobs/jobSystem.js | server/README.md","[""F19"",""F12""]","invoice.archive-unused 默认按 INVOICE_ARCHIVE_CRON 调度;回滚:JOB_DRIVER=cron"
F20,Worker进程拆分(可选),"提供 API 进程与 Worker 进程拆分的部署方式(compose 开关),保持单机也可跑","开启后:API 不跑作业;Worker 只跑作业;两者共享 DATABASE_URL;功能不回归","manual: docker compose 起两个进程并跑回归脚本",manual,TODO,TODO,TODO,"deploy/trialrun/docker-compose.yml | server/src/index.js | server/README.md","[""F19""]","仍保持单机;为未来横向扩展铺路"
F21,对象存储(MinIO/S3兼容),"存储从本地目录演进到 S3 兼容(先 MinIO),保持 signed-url 契约不变或提供兼容层","上传/预览/签名URL 在 MinIO 下可用;回归与 E2E 通过;迁移路径清晰可回滚","manual: trialrun 环境启用 MinIO 并完成一次上传预览",manual,TODO,TODO,TODO,"server/src/services/storage/* | deploy/trialrun/* | server/README.md","[""F20""]","优先用 @aws-sdk/client-s3;单机优先 MinIO"
F22,可观测性增强(metrics/日志),"新增 /metrics(Prometheus)与更完整的结构化日志字段规范(不落敏感)","metrics 可抓取关键指标(HTTP/作业/DB);日志具备 requestId/actorId/targetId 等字段","manual: curl /metrics 并核对字段;触发作业观察指标变化",manual,TODO,TODO,TODO,"server/src/app.js | server/src/observability/* | deploy/trialrun/*","[""F19""]","优先用 prom-client;OTel 放更后"
1 ID Title Description Acceptance Test_Method Tools Dev_Status Review1_Status Regression_Status Files Dependencies Notes
17 F16 前端通知入口(Bell) 新增通知列表页/弹层与未读角标;支持标记已读 四角色均可见自己的通知;读写后角标正确;e2e 覆盖核心路径 cd client && npm run test:e2e manual DONE DONE DONE client/src/components/navigation/Topbar.tsx | client/src/pages/NotificationsPage.tsx | client/src/api/notifications.ts ["F14"] 保持 UI 轻量,不做复杂订阅推送
18 F17 报表导出(CSV/Excel) 新增报销/票据/审计的导出接口(权限控制),前端提供下载入口 导出字段与权限正确;大数据量时可分页/流式输出;审计记录导出操作 manual: 导出后核对字段;并在 audit_logs 中检索 EXPORT 动作 manual DONE DONE DONE server/src/routes/exports.js | server/src/app.js | server/package.json | server/package-lock.json | client/src/api/exports.ts | client/src/api/http.ts | client/src/lib/download.ts | client/src/pages/ReimbursementsPage.tsx | client/src/pages/InvoicePoolPage.tsx | client/src/pages/AuditLogsPage.tsx ["F6","F16"] 选型:exceljs(XLSX),CSV 采用流式生成;回滚:删除 exportsRoutes 注册与依赖即可
19 F18 审批规则维护(system.settings) 补齐 approval_rules 维护 API 与最小前端页(finance_mgr/admin),支持启停与优先级/金额段维护 规则变更可立即影响新 submit;历史 instance 不回写;审计记录变更 cd server && ./scripts/regression-workflow-actions.sh manual DONE DONE DONE server/src/routes/approvalRules.js | server/src/app.js | client/src/pages/ApprovalRulesPage.tsx | client/src/api/approvalRules.ts | client/src/router/index.tsx | client/src/components/navigation/NavLinks.tsx ["F5"] 只做最小可运营;复杂可视化后置
20 F19 作业系统升级(pg-boss 基础设施) 引入 pg-boss(Postgres 队列)作为作业基础设施:提供统一注册/执行框架与开关;保持 node-cron 作业可回滚;并文档化单机用法 pg-boss 可在单机/多进程下可靠运行;最小示例 job 可跑通;不影响现有回归 cd server && ./scripts/regression-all.sh manual TODO DONE TODO DONE TODO DONE server/src/jobs/* | server/src/app.js | server/package.json | deploy/trialrun/* | server/README.md server/src/jobs/jobSystem.js | server/src/jobs/pgBossJobs.js | server/src/app.js | server/src/config.js | server/package.json | server/package-lock.json | server/README.md | deploy/trialrun/.env.example | deploy/trialrun/docker-compose.yml | deploy/trialrun/runbook.md ["F1"] 选择 pg-boss(成熟/无 Redis);回滚:关闭开关并切回 node-cron 选择 pg-boss(成熟/无 Redis);回滚:JOB_DRIVER=cron 或 JOBS_ENABLED=false
21 F19b 作业迁移(OCR -> pg-boss) 将 OCR 异步处理迁移到 pg-boss:保持并发锁语义、幂等与回归脚本不变 mock/tencent 两种 provider 下 OCR 仍可跑;并发下单条仅处理一次;回归全绿 cd server && ./scripts/regression-ocr.sh && ./scripts/regression-all.sh manual TODO DONE TODO DONE TODO DONE server/src/jobs/ocrJob.js | server/src/services/ocr/* | server/README.md server/src/jobs/pgBossJobs.js | server/src/jobs/ocrJob.js | server/src/jobs/jobSystem.js | server/src/config.js | server/README.md ["F19"] 迁移后移除/停用对应 node-cron tick(保留回滚路径) pg-boss schedule 支持秒级 cron;OCR_PROVIDER=off 时自动 unschedule ocr.tick
22 F19c 作业迁移(委派回收 -> pg-boss) 将委派过期回收迁移到 pg-boss:保持 FOR UPDATE SKIP LOCKED + UPDATE RETURNING 原子认领语义 多进程并发下审计不重复写;回收逻辑不变;回归全绿 cd server && RUN_DELEGATION_CONCURRENCY_CHECK=1 ./scripts/regression-workflow-actions.sh manual TODO DONE TODO DONE TODO DONE server/src/jobs/delegationRevokeJob.js | server/README.md server/src/jobs/pgBossJobs.js | server/src/jobs/delegationRevokeJob.js | server/src/jobs/jobSystem.js | server/README.md ["F19"] 仍需保留原子认领+审计只基于 RETURNING 结果集 仍保留原子认领+审计只基于 RETURNING 结果集
23 F19d 作业迁移(超期归档 -> pg-boss) 将 90 天游离归档迁移到 pg-boss(替代 node-cron),统一重试/并发/可观测字段 作业可重复执行幂等;多进程不重复处理;回归全绿 cd server && ./scripts/regression-ocr.sh && ./scripts/regression-all.sh manual TODO DONE TODO DONE TODO DONE server/src/jobs/invoiceArchiveJob.js | server/README.md server/src/jobs/pgBossJobs.js | server/src/jobs/invoiceArchiveJob.js | server/src/jobs/jobSystem.js | server/README.md ["F19","F12"] 迁移后在 README 标注调度频率与开关 invoice.archive-unused 默认按 INVOICE_ARCHIVE_CRON 调度;回滚:JOB_DRIVER=cron
24 F20 Worker进程拆分(可选) 提供 API 进程与 Worker 进程拆分的部署方式(compose 开关),保持单机也可跑 开启后:API 不跑作业;Worker 只跑作业;两者共享 DATABASE_URL;功能不回归 manual: docker compose 起两个进程并跑回归脚本 manual TODO TODO TODO deploy/trialrun/docker-compose.yml | server/src/index.js | server/README.md ["F19"] 仍保持单机;为未来横向扩展铺路
25 F21 对象存储(MinIO/S3兼容) 存储从本地目录演进到 S3 兼容(先 MinIO),保持 signed-url 契约不变或提供兼容层 上传/预览/签名URL 在 MinIO 下可用;回归与 E2E 通过;迁移路径清晰可回滚 manual: trialrun 环境启用 MinIO 并完成一次上传预览 manual TODO TODO TODO server/src/services/storage/* | deploy/trialrun/* | server/README.md ["F20"] 优先用 @aws-sdk/client-s3;单机优先 MinIO
26 F22 可观测性增强(metrics/日志) 新增 /metrics(Prometheus)与更完整的结构化日志字段规范(不落敏感) metrics 可抓取关键指标(HTTP/作业/DB);日志具备 requestId/actorId/targetId 等字段 manual: curl /metrics 并核对字段;触发作业观察指标变化 manual TODO TODO TODO server/src/app.js | server/src/observability/* | deploy/trialrun/* ["F19"] 优先用 prom-client;OTel 放更后