feat(t224): add incremental freight sync

docs/api.md

@@ -172,7 +172,17 @@ Connector 是 loopback 内部服务，不复用 ADMIN/BUYER 凭证。除 `/healt
 ### Connector `POST /v1/freight/query`
 
 ```json
-{"order_number":"完整单号"}
+{"mode":"ORDER_NUMBER","order_number":"完整单号"}
+```
+
+或按 Asia/Shanghai 自然日闭区间查询，单次最多 7 天：
+
+```json
+{
+  "mode":"CREATED_RANGE",
+  "created_from":"2026-07-22",
+  "created_to":"2026-07-28"
+}
 ```
 
 成功返回最小化规范结构：
@@ -219,11 +229,15 @@ T-224 增加：
 ```json
 {
   "mode":"CREATED_RANGE",
-  "created_from":"2026-07-27T16:00:00Z",
-  "created_to":"2026-07-28T16:00:00Z"
+  "created_from":"2026-07-22",
+  "created_to":"2026-07-28"
 }
 ```
 
+手动范围最多 7 个自然日；也可以只提交
+`{"mode":"CREATED_RANGE","sync_to_now":true}`。后者在没有水位时从当天开始，有水位时
+从成功水位前回看 10 分钟对应的自然日开始，后端再按最多 7 天切窗。
+
 响应 `202`，返回 sync id/status。订单号不进入 URL、事件 message 或访问日志；数据库
 只保存规范值及用于审计/检索的受控字段，不保存 Connector 密钥。
 
@@ -232,11 +246,16 @@ T-224 增加：
 返回 `PENDING/RUNNING/SUCCEEDED/FAILED`、查询模式、匿名查询摘要、开始/结束时间、
 订单/商品计数和稳定错误码。失败不返回 ERP 原始 body 或个人信息。
 
+### `GET /api/v1/freight-sync-watermark`
+
+返回当前 ADMIN creator 的顺运宝最近成功日期同步水位；尚未成功同步时返回
+`{"watermark":null}`。只有完整批次落库成功才在同一事务推进水位；失败、空响应以外
+的协议错误和较旧范围成功均不会覆盖较新的水位。
+
 ### `GET /api/v1/freight-orders`
 
-T-222 首版返回当前 ADMIN creator 最近更新的货运单并支持 `limit`（1..100）。
-T-224 增加 `q`、`sync_status`、`created_from/to` 和 `cursor`；`q` 只匹配受控来源
-单号、店铺或内部 UUID，不匹配电话/地址。响应不包含收件人字段或 Connector 原文。
+返回当前 ADMIN creator 最近更新的货运单并支持 `limit`（1..100）。响应不包含
+收件人字段或 Connector 原文；列表筛选和 cursor 后置，不属于本次日期同步闭环。
 
 ### `GET /api/v1/freight-orders/{id}`
 

docs/current-state.md

@@ -5,7 +5,7 @@
 ## 当前快照
 
 - 日期：2026-07-28
-- 阶段：T-223 已完成，T-224 ERP 日期增量同步已领取
+- 阶段：T-220 至 T-224 ERP 货运接入闭环已完成
 - Git：当前分支为 `main`；T-001 至 T-004、T-101 至 T-104、T-201 至 T-219
   均按文档提交、实现提交的顺序纳入历史
 - 生产代码：`android-buyer/` 已接入 Roubao Android 源码
@@ -17,6 +17,10 @@
 - ERP 货运：Go 后端通过仅限 loopback、服务密钥鉴权的 Python Connector 异步按
   完整单号同步；v12 保存同步记录、货运头和全部明细，canonical hash 控制 revision，
   Admin 已有 `/freight`、`/freight/import`、`/freight/{id}` 与对应 JSON API。
+- ERP 增量同步：v14 支持 Asia/Shanghai 创建日期闭区间和“同步至现在”，Connector
+  单窗最多 7 天，后端对较长水位范围切窗并从成功水位前 10 分钟所在自然日回看。
+  货运落库、同步成功和水位推进同事务完成；失败与较旧范围成功不推进水位。Admin
+  可查看查询范围、计数、稳定错误码和最近成功水位。
 - 采购需求：v13 按货运商品 revision 保存可复核快照；ADMIN 显式确认采购、上传参考
   图后生成不可变 PENDING 任务。来源变化不会改写任务，Roubao 可沿用现有 claim 流程。
 - 本机 Android 工具：JDK 17.0.13、Command-line Tools 22.0、SDK 34、
@@ -24,9 +28,10 @@
 - Android Studio：未安装；`winget` 静默安装卡住后已终止，不阻塞命令行构建
 - 测试：T-219 Android Debug/Release 单元测试与构建和根 `init.ps1` 通过；
   Debug APK `1.4.16 (21)` 已覆盖安装到 PKG110
-- 后端测试：T-223 运行 `go test ./...`、`go test -race ./...`、`go vet ./...`；
-  覆盖采购需求 migration 降级保护、一商品一需求、阻塞字段、图片唯一绑定、任务
-  并发重放、来源变化后任务不变、Roubao claim 和 Admin API/SSR
+- 后端测试：T-224 运行 `go test ./...`、`go test -race ./...`、`go vet ./...`；
+  覆盖 v14 上下迁移、7 天切窗、水位重叠、中途失败、空窗口、重复页、来源 revision、
+  水位事务/不回退、Admin API/SSR 和 Connector 严格响应窗口；Python 22 项伪响应
+  测试通过，未访问真实 ERP
 - 原型：4 个管理 Web 页面和 7 个 Android 页面均可离线独立打开；Playwright
   以 1440×900、390×844、360×800 验证 36 个页面/视口组合，无页面横向溢出、
   脚本错误或外部请求，Android 可见交互控件均不小于 44px
@@ -165,7 +170,7 @@
 | `docs/tasks/T-221.md` | DONE | 顺运宝精确单号 Connector |
 | `docs/tasks/T-222.md` | DONE | 货运信息存储、API 与 Admin 页面 |
 | `docs/tasks/T-223.md` | DONE | 待采购需求提取与任务生成 |
-| `docs/tasks/T-224.md` | DOING | ERP 日期增量同步 |
+| `docs/tasks/T-224.md` | DONE | ERP 日期增量同步 |
 | `docs/design/` | 已确认 | T-202 原型索引、4 个管理页和 7 个 Android 页面 |
 | `deepseek总结.txt` | 已有 | 历史讨论摘要，不是正式需求权威 |
 | `android-buyer/` | 已有 | Roubao `main` 固定 commit 的 Android 基线 |
@@ -178,10 +183,11 @@
 ## 任务摘要
 
 - 已完成：T-001 至 T-004、T-101 至 T-104、T-201 至 T-219。
-- 已完成：另含 T-220 至 T-223 ERP 契约、Connector、货运存储和采购需求生成。
-- 进行中：T-224 ERP 日期增量同步。
-- 下一步：完成 T-223 采购需求生成和 T-224 日期增量同步，再进入 T-301 P0 UI
-  完整交互验收。
+- 已完成：另含 T-220 至 T-224 ERP 契约、Connector、货运存储、采购需求生成和
+  日期增量同步。
+- 进行中：无。
+- 下一步：进入 T-301 P0 UI 完整交互验收；真实 ERP 上线前仍需确认开放 API、
+  数据使用权限并由人员完成验证码登录。
 
 ## 当前可运行内容
 

docs/routes.md

@@ -11,8 +11,8 @@ T-202 的离线 P0 页面入口见[原型索引](design/index.html)。原型仅
 | `/tasks` | 任务列表 | 查看状态、筛选并进入详情 | US-002 | IX-003 |
 | `/tasks/new` | 新建任务 | 提交图片和采购约束 | US-001 | IX-002 |
 | `/tasks/{id}` | 任务详情 | 查看输入/候选/证据、创建下单授权，并展示对账中/人工对账/待人工付款状态 | US-002、US-006、US-010 | IX-003、IX-008、IX-011 |
-| `/freight` | ERP 货运列表 | 按来源单号、同步状态和时间查看已导入货运单 | US-011 | IX-012 |
-| `/freight/import` | ERP 货运导入 | 创建精确单号或日期范围同步 | US-011 | IX-012 |
+| `/freight` | ERP 货运列表 | 查看已导入货运单并进入全部商品明细 | US-011 | IX-012 |
+| `/freight/import` | ERP 货运导入 | 创建精确单号、最多 7 天日期范围或“同步至现在”任务，并查看成功水位 | US-011 | IX-012 |
 | `/freight/{id}` | ERP 货运详情 | 查看全部商品明细、来源变化、补图和采购任务生成状态 | US-011、US-012 | IX-012、IX-013 |
 
 MVP 登录后默认进入 `/tasks`。未登录访问受保护页面时跳转 `/login` 并携带安全的
@@ -89,7 +89,7 @@ T-207 的 events/candidates/complete/fail 接受原设备对授权内已产生
 | `CandidateReview` | Android/Web | 展示候选与硬约束校验，不执行自动化动作 |
 | `ExecutionController` | Android | UI 命令入口，委托 workflow，不直接调用 Accessibility |
 | `PendingPaymentSummary` | 管理 Web/App | 只读展示对账订单与人工付款提醒，不提供付款或重提动作 |
-| `FreightSyncForm` | 管理 Web | 创建精确单号/日期同步记录，不持有 ERP 凭证 |
+| `FreightSyncForm` | 管理 Web | 创建精确单号/日期同步记录、查看成功水位，不持有 ERP 凭证 |
 | `FreightItemReview` | 管理 Web | 显示规范化来源字段、缺失项和采购任务生成操作 |
 
 具体状态反馈以[交互清单](08-interaction-checklist.md)为准，组件命名可在接入真实框架后

docs/tasks/T-224.md

@@ -4,7 +4,7 @@ title: ERP 日期增量同步
 phase: 2
 deps:
   - T-223
-status: TODO
+status: DONE
 created: 2026-07-28
 context_ref: 78dc595
 work_branch: null
@@ -49,11 +49,11 @@ write_paths:
 
 ## 验收要点
 
-- [ ] 日期 query 与脱敏 HAR 合约一致，时区和闭区间规则有测试。
-- [ ] 重叠窗口、重复页、来源更新、空窗口和中途失败不丢单/不重复。
-- [ ] 失败不推进 watermark，成功重放得到相同货运与采购需求集合。
-- [ ] Admin 可查看范围、状态、计数和匿名错误，不显示 PII/秘密。
-- [ ] Python、Go 全量测试、race/vet、根验证和响应式 SSR 验收通过。
+- [x] 日期 query 与脱敏 HAR 合约一致，时区和闭区间规则有测试。
+- [x] 重叠窗口、重复页、来源更新、空窗口和中途失败不丢单/不重复。
+- [x] 失败不推进 watermark，成功重放得到相同货运与采购需求集合。
+- [x] Admin 可查看范围、状态、计数和匿名错误，不显示 PII/秘密。
+- [x] Python、Go 全量测试、race/vet、根验证和响应式 SSR 验收通过。
 
 ## 边界
 
@@ -64,3 +64,16 @@ write_paths:
 ## 执行记录
 
 - 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。