cmroubao

Table of Contents

问题 / 背景
关联需求与交互
方案
验收要点
边界
执行记录

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

同步来源：docs/tasks/T-224.md · commit afc651f75a3a

id: T-224 title: ERP 日期增量同步 phase: 2 deps:

T-223 status: DONE created: 2026-07-28 context_ref: 78dc595 work_branch: null write_paths:
erp-connector/**
backend-api/internal/domain/**
backend-api/internal/usecase/**
backend-api/internal/repository/sqlite/**
backend-api/internal/transport/httpapi/**
backend-api/internal/transport/webui/**
backend-api/migrations/**
docs/api.md
docs/routes.md
docs/tasks/T-224.md
docs/current-state.md

问题 / 背景

精确单号适合第一版人工导入，但日常运营需要按时间发现新货运单。已验证 HAR 使用 t_stock.created 日期区间条件；增量同步必须处理分页过程中数据变化、重复窗口、失败重试和服务端时区，不能简单保存“最后一页”。

关联需求与交互

功能：F-011、F-012
用户故事：US-011、US-012
交互：IX-012、IX-013
架构/API：日期查询、sync watermark 和重叠窗口

方案

Connector 增加日期区间请求，严格使用已验证字段： colName=created, op=0, type=3, optType=0，日期使用 Asia/Shanghai。
单次窗口最大 7 天，分页/总数均设上限，按 stock id 去重后批量取详情。
后端保存 last successful watermark；每次从成功水位前回看 10 分钟/至少同一自然日，依靠外部 ID + hash 去重更新。
只有整批事务成功才推进水位；认证、网络、协议、超限或明细缺失时保留旧水位并显示可重试错误。
Admin 提供手动日期范围和“同步至现在”，不在本任务引入系统级计划任务；定时器后置到运行稳定后。

验收要点

日期 query 与脱敏 HAR 合约一致，时区和闭区间规则有测试。
重叠窗口、重复页、来源更新、空窗口和中途失败不丢单/不重复。
失败不推进 watermark，成功重放得到相同货运与采购需求集合。
Admin 可查看范围、状态、计数和匿名错误，不显示 PII/秘密。
Python、Go 全量测试、race/vet、根验证和响应式 SSR 验收通过。

边界

不做无人值守验证码 OCR、cron、消息队列或多 ERP 租户。
不承诺逆向页面接口 SLA；正式生产前仍需确认 ERP 开放 API 和数据使用权限。
不因时间同步自动领取或执行 Roubao 任务。

执行记录

2026-07-28：任务合约已冻结，等待 T-223。
2026-07-28：Connector 增加 CREATED_RANGE，严格复现 t_stock.created/op=0/type=3/optType=0 和最多 7 个自然日闭区间；分页按 stock id 去重，空范围不请求详情，输出继续使用 allowlist schema。
2026-07-28：v14 将同步运行扩展为 ORDER_NUMBER/CREATED_RANGE 并新增 creator 级成功水位。后端“同步至现在”从水位前 10 分钟所在自然日回看，超过 7 天自动切窗；货运 upsert、同步成功和水位推进处于同一 SQLite 事务，失败和较旧成功任务不推进。
2026-07-28：Admin JSON/SSR 支持手动日期范围、“同步至现在”、范围/计数/稳定错误码和水位查看。SSR 实测发现并修复预填日期与 sync_to_now 同时提交的 422，API 仍严格拒绝混合语义。
2026-07-28：Python 22 项伪响应测试、Go 全量测试、race、vet 和根 init.ps1 通过。隔离 Gin/SQLite + 本地伪 Connector 验证成功/失败水位；Playwright 在 1440×900、390×844、360×800 无横向溢出、页头遮挡、过小命令控件或 PII 文本。未访问真实 ERP。