feat: reconcile commerce payments

README.md

@@ -17,7 +17,7 @@
 - 学生端能力：题库入口、分类树、题目集合、顺序/随机/模考 session 组卷快照、答题、错题本、收藏夹、背单词进度、个人中心、考试倒计时、签到积分、题目反馈、排行榜、分数线、题目视频、订单详情/状态轮询、优惠券领取/抵扣、权益、激活码预检查/兑换、资料下载。
 - 平台后台能力：租户管理、SaaS 套餐、订阅、账单、服务费收款、用量记录。
 - 销售/代理/CRM 增长链路：邀请码、扫码/分享事件、首绑客资保护、销售统计、团队关系、CRM 配置和队列。
-- `apps/worker` 后台任务进程：CRM webhook 队列消费、generic/钉钉/飞书/企微机器人发送、签名、失败重试和日志。
+- `apps/worker` 后台任务进程：CRM webhook 队列消费、generic/钉钉/飞书/企微机器人发送、签名、失败重试和日志；commerce worker 可补偿查询微信/支付宝支付和退款状态，兜底漏通知订单。
 - 销售/代理分佣结算基础闭环：租户默认比例、成员比例、激活码批次比例、订单/激活码归因、结算单生成、审核、线下打款状态和权限隔离。
 - 订单售后基础闭环：退款请求、审核、处理状态流、微信/支付宝发起退款、微信/支付宝退款查询确认、微信/支付宝退款通知 webhook、退款金额累计、部分/全额退款订单状态、全额退款权益撤销、退款事件和审计日志。
 - PocketBase schema/数据导入器雏形和导入后校验脚本。
@@ -26,7 +26,7 @@
 还没有达到生产交付的部分：
 
 - Supabase Auth/JWT、租户角色模板、班级/教师/学生范围权限已可联调；生产前还要做真实云端 Auth/JWKS 回归和 RLS 深测。
-- 阿里云/腾讯云短信、微信小程序登录、微信支付、支付宝主链路和微信/支付宝发起退款/查询确认/退款通知已完成本地适配；微信网页登录、QQ 登录、手机号换绑、对账、支付补偿和真实生产账号联调还没接完。
+- 阿里云/腾讯云短信、微信小程序登录、微信支付、支付宝主链路、微信/支付宝发起退款/查询确认/退款通知、支付/退款补偿 worker 已完成本地适配；微信网页登录、QQ 登录、手机号换绑、完整资金流水对账和真实生产账号联调还没接完。
 - OSS/COS/Supabase Storage 上传下载签名 provider 已接入；上传后校验、PDF 预览、防盗链和视频水印还没完成。
 - Excel/CSV 导入、分数线/视频批量导入和异步 worker 还没完成。
 - 分佣真实打款、结算导出、发票/凭证、CRM 轮询/定向分配、富卡片模板、失败告警和销售转化看板还没完成。
@@ -56,7 +56,7 @@
 
 ```text
 apps/api/                   Node.js 业务 API
-apps/worker/                后台异步任务：CRM webhook、后续支付补偿/导入复检等
+apps/worker/                后台异步任务：CRM webhook、支付/退款补偿、后续导入复检等
 packages/config/            共享配置
 packages/db/                PostgreSQL 连接池和查询封装
 packages/domain/            领域常量和共享类型
@@ -95,6 +95,12 @@ npm run dev:api
 npm --workspace @tiku-saas/worker run crm:once
 ```
 
+单次运行支付/退款补偿 worker：
+
+```bash
+npm --workspace @tiku-saas/worker run commerce:once
+```
+
 默认本地数据库：
 
 ```text
@@ -133,6 +139,7 @@ npm run check:importer
 npm run pb:import:validate
 npm run test:api
 npm run test:worker:crm
+npm run test:worker:commerce
 ```
 
 ## API 模块
@@ -173,7 +180,7 @@ API 身份上下文：
 - 资料、PDF、视频等资源必须先进入 `content_assets` 台账，再由 API 校验权限并下发签名 URL。
 - 题库入口和分类使用 `content_entries/content_nodes`；题目列表和练习规则使用 `question_collections/practice_blueprints`，前端不要再把旧树字段当成唯一业务结构。
 - 批量导入必须先写 `content_import_jobs/items/issues`，保留原始 payload、规范化 payload、逐行问题和审计记录。题目、单词、知识手册导入已走这套后台校验管线，前端只做预检查和预览展示。
-- 支付 webhook 必须先设计幂等键和验签流程，再进入生产使用。
+- 支付 webhook 必须先设计幂等键和验签流程，再进入生产使用；生产环境还应定时运行 commerce worker 兜底供应商漏通知和处理中退款。
 
 ## 最近一次验证
 
@@ -193,4 +200,4 @@ npm run check:refactor
 2. Taro 前端 scaffold，让 H5 和小程序共用同一套 API。
 3. 对象存储上传后校验、PDF 预览、防盗链和视频水印。
 4. Excel/CSV 以及分数线、视频批量导入；把现有 JSON 导入升级为可排队异步执行。
-5. 微信网页/QQ 登录、支付对账、支付补偿、公共题库版本同步 worker、积分活动深化，以及排行榜防刷/预聚合。
+5. 微信网页/QQ 登录、完整资金流水对账、公共题库版本同步 worker、积分活动深化，以及排行榜防刷/预聚合。