qipai/docs/devlogs/2026-06-18-M01-C-轻量异步任务基础.md

开发日志：2026-06-18 M01-C 轻量异步任务基础

完成内容

• 新增 qipai_outbox_events 与 qipai_async_tasks 独立迁移、回滚和验证 SQL。
• outbox 与任务均使用租户级幂等键；重复写入返回既有记录，不产生重复副作用入口。
• 任务支持优先级、可执行时间、FOR UPDATE SKIP LOCKED 并发领取、worker 租约、过期租约恢复、指数退避和最大重试次数。
• 达到最大重试次数后进入 COMPENSATION_REQUIRED，保留最后错误供人工补偿。
• 新增通知、订单推进、设备命令、退款查询、统计汇总和 outbox 发布六类任务类型。
• 新增独立 worker 入口和 qipai-worker PM2 进程；具体业务 handler 由后续模块注册，不创建空业务实现。

数据库/API/部署影响

• 数据库：新增迁移版本 2026061802_m01c_async_tasks；down 先删除任务/outbox 表，再由历史迁移回滚核心表。
• API：无公开接口变化。
• 部署：PM2 增加 qipai-worker，与 API 共用后端构建产物和 MySQL 配置。

验证结果

• npm test（backend/）：退出码 0。
• powershell -ExecutionPolicy Bypass -File scripts/dev/windows/check-backend.ps1：退出码 0；编译、契约测试、迁移计划和 HTTP 健康检查通过。
• powershell -ExecutionPolicy Bypass -File scripts/dev/windows/check-secrets.ps1：退出码 0。
• WSL 原生临时副本 + MySQL 8.4.9：up → verify → down → up → verify 退出码 0；up 14 条、verify 6 条、down 13 条。
• 真实 MySQL 验证重复任务只保留一条；销毁第一个 Repository 后由新 Repository 领取并完成，证明 worker 重启不丢任务。
• 迁移摘要：up 5b381518ca8875e6bc5398e35d8627e56effa11618983412d5f41ca92c96ca9b；verify 9b36eb26c7e4b2b884dca609fba172a2a0fbbfc828ec1376a8504afa798c6564；down 20f8f37a0662c3f5a20ba207a4314c5c7df47bcfc64a60604696b2d9ee44dc2d。

边界与下一步

• 未连接生产数据库，未启动生产 PM2。
• 通知、订单、设备、退款和统计真实 handler 属于后续业务模块；M01-C 只提供可运行基础设施。
• 工作区已有未跟踪 miniapp/ 模板继续按 ISSUE-007 隔离，本提交不修改、不暂存。
• 下一阶段：M02-A 多小程序、多租户边界与微信登录身份基础。

Git

• commit：2b90d1f feat(M01-C): 建立MySQL异步任务基础
• 远端：origin/main
• push/远端校验：成功，工程提交推送后 HEAD == origin/main。