From fc60efacd0bcf60544fee5f15c6fa3091a71c3c3 Mon Sep 17 00:00:00 2001
From: ila <ila2002@qq.com>
Date: Fri, 7 Aug 2026 16:36:39 +0800
Subject: [PATCH] docs: import wiki at afc651f75a3a

---
 T-224.-.md | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 T-224.-.md

diff --git a/T-224.-.md b/T-224.-.md
new file mode 100644
index 0000000..6272c27
--- /dev/null
+++ b/T-224.-.md
@@ -0,0 +1,82 @@
+<!-- docs-wiki-sync:docs/tasks/T-224.md@afc651f75a3abc2676bb13aa8a80f6aa6a25a72e -->
+> 同步来源：[`docs/tasks/T-224.md`](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/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 和重叠窗口
+
+## 方案
+
+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 提供手动日期范围和“同步至现在”，不在本任务引入系统级计划任务；定时器
+   后置到运行稳定后。
+
+## 验收要点
+
+- [x] 日期 query 与脱敏 HAR 合约一致，时区和闭区间规则有测试。
+- [x] 重叠窗口、重复页、来源更新、空窗口和中途失败不丢单/不重复。
+- [x] 失败不推进 watermark，成功重放得到相同货运与采购需求集合。
+- [x] Admin 可查看范围、状态、计数和匿名错误，不显示 PII/秘密。
+- [x] 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。