67 lines
2.4 KiB
Markdown
67 lines
2.4 KiB
Markdown
|
---
|
||
|
|
id: T-224
|
||
|
|
title: ERP 日期增量同步
|
||
|
|
phase: 2
|
||
|
|
deps:
|
||
|
|
- T-223
|
||
|
|
status: TODO
|
||
|
|
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 和重叠窗口
|
||
|
|
|
||
|
|
## 方案
|
||
|
|
|
||
|
|
1. Connector 增加日期区间请求，严格使用已验证字段：
|
||
|
|
`colName=created, op=0, type=3, optType=0`，日期使用 Asia/Shanghai。
|
||
|
|
2. 单次窗口最大 7 天，分页/总数均设上限，按 stock id 去重后批量取详情。
|
||
|
|
3. 后端保存 last successful watermark；每次从成功水位前回看 10 分钟/至少同一自然日，
|
||
|
|
依靠外部 ID + hash 去重更新。
|
||
|
|
4. 只有整批事务成功才推进水位；认证、网络、协议、超限或明细缺失时保留旧水位并
|
||
|
|
显示可重试错误。
|
||
|
|
5. Admin 提供手动日期范围和“同步至现在”，不在本任务引入系统级计划任务；定时器
|
||
|
|
后置到运行稳定后。
|
||
|
|
|
||
|
|
## 验收要点
|
||
|
|
|
||
|
|
- [ ] 日期 query 与脱敏 HAR 合约一致，时区和闭区间规则有测试。
|
||
|
|
- [ ] 重叠窗口、重复页、来源更新、空窗口和中途失败不丢单/不重复。
|
||
|
|
- [ ] 失败不推进 watermark，成功重放得到相同货运与采购需求集合。
|
||
|
|
- [ ] Admin 可查看范围、状态、计数和匿名错误，不显示 PII/秘密。
|
||
|
|
- [ ] Python、Go 全量测试、race/vet、根验证和响应式 SSR 验收通过。
|
||
|
|
|
||
|
|
## 边界
|
||
|
|
|
||
|
|
- 不做无人值守验证码 OCR、cron、消息队列或多 ERP 租户。
|
||
|
|
- 不承诺逆向页面接口 SLA；正式生产前仍需确认 ERP 开放 API 和数据使用权限。
|
||
|
|
- 不因时间同步自动领取或执行 Roubao 任务。
|
||
|
|
|
||
|
|
## 执行记录
|
||
|
|
|
||
|
|
- 2026-07-28：任务合约已冻结，等待 T-223。
|