OPC/goauto
2
0
Fork 0
Code Issues 192 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(yeeke): 建立退货包裹只读对接与定时同步 #336

New Issue
Open
opened 2026-09-23 09:40:55 +08:00 by ila · 3 comments
ila commented 2026-09-23 09:40:55 +08:00
Owner
Copy Link
Copy Source

来源与目标

来源：docs/task/yeeke-return-sync-requirement.md 的需求澄清结果。用户确认先只实施 yeeke 对接和只读退货数据同步，匹配、人工绑定和采购替代后续另行讨论。

目标：在 GoAuto Server 中建立对 mmt.yeeke.com（对裹/duiguo）包裹认领模块的只读同步能力，把退货包裹及商品明细稳定保存到本地，供后续工单使用。

本单范围

1. yeeke 连接与会话

  • 按当前 HAR 事实实现独立 yeeke adapter，不把第三方请求散落到业务模块。
  • 支持验证码获取、登录和 token 会话复用。
  • yeeke 账号凭据使用独立安全存储，仅管理员可维护；不得进入代码、日志、工单、Wiki 或任务归档。
  • token 按过期时间管理；失效后有限次数重新登录，失败后进入明确的同步失败状态。
  • yeeke 验证码可使用已获用户明确批准的线上 OCR 例外，但需要同步更新安全边界说明；OCR 请求不得记录验证码、账号或 token。
  • 所有请求日志脱敏，禁止记录 URL 中的 token、Authorization、密码、验证码和完整响应。

2. 包裹认领只读同步

同步接口：包裹认领列表及必要的只读详情/时间线接口。首版不调用 yeeke 的二次销售、销毁或其他写接口。

保存包裹和商品的结构化字段，至少包括：

  • yeeke 包裹外部 ID（如响应提供）；
  • ordersn、trackingNo；
  • 店铺 ID/名称；
  • 仓库编码、仓库名称、库位；
  • 包裹认领状态、创建/认领/更新时间、销毁截止时间；
  • itemId、variationId、商品标题、规格文本、图片 URL、退货数量；
  • 最近一次同步时间、来源响应时间和脱敏同步状态。

外部唯一键必须能区分同一包裹内的多个商品、规格和数量，不能只使用 itemId。

3. 幂等、增量和恢复

  • 分页按 createTime/更新时间读取，不能只依赖首次返回的 total；total 变化、重复页、空页和接口超时必须有明确处理。
  • 相同包裹/商品重复同步不得产生重复本地记录。
  • 保存同步游标或可恢复的时间窗口，进程重启后从上次安全位置继续。
  • 外部接口异常时保留上次有效数据，不把记录直接标记为已销毁或不可用。
  • 状态变化采用幂等更新，并保留最近同步状态和脱敏错误原因。
  • 使用现有定时任务、租约和执行日志能力；默认关闭，支持管理员手动触发。
  • 每小时同步只是默认建议，具体 Cron、批量大小和重试次数应可配置且有上限。

4. Admin 只读运行状态

本单不新增退货匹配和采购按钮；如需要页面，仅提供最小同步运行记录/摘要入口，展示总页数、读取数量、新增、更新、跳过、失败和最后成功时间，不展示凭据、token、完整响应或不必要的个人数据。

明确非目标

  • 不实现 SYB 商品与退货商品匹配。
  • 不实现规格文本/AI 匹配。
  • 不实现“使用退货”或人工绑定界面。
  • 不实现库存占用、释放或 consumed 状态驱动。
  • 不修改采购任务创建、PDD 采购流程、订单状态或付款行为。
  • 不调用 yeeke 二次销售、销毁或任何写接口。
  • 不修改现有 SYB 同步流程。

数据与安全要求

  • HAR 文件仅作本地分析证据，含凭据和 token，禁止提交。
  • 退货图片只保存外部 URL 或经确认的非敏感元数据；不保存原始 HAR、登录页面或完整个人信息。
  • 第三方 token 不通过普通业务接口返回。
  • OCR 从现有 SYB 例外扩大到 yeeke，属于安全边界变化；实施前必须在工单记录批准范围并更新长期安全文档。
  • 数据库迁移、凭据存储、定时任务和发布属于高风险，实施前需要明确授权。

验收标准

  1. 验证码获取、登录成功、token 复用和 token 失效后的有限重登均有单元/集成测试。
  2. 分页同步能处理 total 变化、重复页、空页、超时和中途重启。
  3. 同一包裹重复执行同步不会重复插入；同一商品不同规格/数量不会互相覆盖。
  4. yeeke 状态变化能幂等更新本地记录；接口失败不会覆盖已有有效状态。
  5. 手动触发与定时触发使用同一租约，不能并发运行；默认定时任务保持关闭。
  6. 同步摘要和错误日志不包含密码、验证码、token、Cookie、完整响应或订单个人信息。
  7. 现有 SYB 同步、采购创建和 Agent 接口回归测试通过。
  8. 未执行 yeeke 写操作、真实采购、下单或付款。

依赖与未决事项

  • 实施前确认 yeeke 响应中是否稳定提供包裹外部 ID；如没有，需根据 HAR 事实确定安全组合唯一键。
  • 实施前确认 token 实际有效期和 Redis 是否为线上既有依赖；若无 Redis，应评估使用现有数据库会话存储，避免为单一 token 缓存增加不必要基础设施。
  • HAR 中只观察到的状态枚举不能直接视为完整枚举，未知状态必须保留并告警，不得静默归类。
  • 后续匹配/绑定/采购拦截工单依赖本单完成并验收。

文档影响

长期事实变化预计需要更新架构与代码图、业务规则、安全边界和部署运维页面；实施时按 Wiki-first 规则同步。当前仅建立工单，不修改代码、数据库、线上配置或定时任务。

退货商品页表格显示约束（已确认）

仅调整前端显示，不改变后端接口字段、数据库字段或同步数据结构：

  • 表头“商品id”显示为“蝦皮id”；
  • 表头“规格id”显示为“sku_id”；
  • 去掉“仓库/库位”显示列；
  • 在原“仓库/库位”位置增加独立“规格数据”列，展示规格文本/规格明细；
  • 仓库编码、仓库名称和库位仍可保存在同步数据中，但本次页面不展示该列。
## 来源与目标 来源：`docs/task/yeeke-return-sync-requirement.md` 的需求澄清结果。用户确认先只实施 yeeke 对接和只读退货数据同步，匹配、人工绑定和采购替代后续另行讨论。 目标：在 GoAuto Server 中建立对 mmt.yeeke.com（对裹/duiguo）包裹认领模块的只读同步能力，把退货包裹及商品明细稳定保存到本地，供后续工单使用。 ## 本单范围 ### 1. yeeke 连接与会话 - 按当前 HAR 事实实现独立 yeeke adapter，不把第三方请求散落到业务模块。 - 支持验证码获取、登录和 token 会话复用。 - yeeke 账号凭据使用独立安全存储，仅管理员可维护；不得进入代码、日志、工单、Wiki 或任务归档。 - token 按过期时间管理；失效后有限次数重新登录，失败后进入明确的同步失败状态。 - yeeke 验证码可使用已获用户明确批准的线上 OCR 例外，但需要同步更新安全边界说明；OCR 请求不得记录验证码、账号或 token。 - 所有请求日志脱敏，禁止记录 URL 中的 token、Authorization、密码、验证码和完整响应。 ### 2. 包裹认领只读同步 同步接口：包裹认领列表及必要的只读详情/时间线接口。首版不调用 yeeke 的二次销售、销毁或其他写接口。 保存包裹和商品的结构化字段，至少包括： - yeeke 包裹外部 ID（如响应提供）； - `ordersn`、`trackingNo`； - 店铺 ID/名称； - 仓库编码、仓库名称、库位； - 包裹认领状态、创建/认领/更新时间、销毁截止时间； - `itemId`、`variationId`、商品标题、规格文本、图片 URL、退货数量； - 最近一次同步时间、来源响应时间和脱敏同步状态。 外部唯一键必须能区分同一包裹内的多个商品、规格和数量，不能只使用 `itemId`。 ### 3. 幂等、增量和恢复 - 分页按 `createTime`/更新时间读取，不能只依赖首次返回的 total；total 变化、重复页、空页和接口超时必须有明确处理。 - 相同包裹/商品重复同步不得产生重复本地记录。 - 保存同步游标或可恢复的时间窗口，进程重启后从上次安全位置继续。 - 外部接口异常时保留上次有效数据，不把记录直接标记为已销毁或不可用。 - 状态变化采用幂等更新，并保留最近同步状态和脱敏错误原因。 - 使用现有定时任务、租约和执行日志能力；默认关闭，支持管理员手动触发。 - 每小时同步只是默认建议，具体 Cron、批量大小和重试次数应可配置且有上限。 ### 4. Admin 只读运行状态 本单不新增退货匹配和采购按钮；如需要页面，仅提供最小同步运行记录/摘要入口，展示总页数、读取数量、新增、更新、跳过、失败和最后成功时间，不展示凭据、token、完整响应或不必要的个人数据。 ## 明确非目标 - 不实现 SYB 商品与退货商品匹配。 - 不实现规格文本/AI 匹配。 - 不实现“使用退货”或人工绑定界面。 - 不实现库存占用、释放或 consumed 状态驱动。 - 不修改采购任务创建、PDD 采购流程、订单状态或付款行为。 - 不调用 yeeke 二次销售、销毁或任何写接口。 - 不修改现有 SYB 同步流程。 ## 数据与安全要求 - HAR 文件仅作本地分析证据，含凭据和 token，禁止提交。 - 退货图片只保存外部 URL 或经确认的非敏感元数据；不保存原始 HAR、登录页面或完整个人信息。 - 第三方 token 不通过普通业务接口返回。 - OCR 从现有 SYB 例外扩大到 yeeke，属于安全边界变化；实施前必须在工单记录批准范围并更新长期安全文档。 - 数据库迁移、凭据存储、定时任务和发布属于高风险，实施前需要明确授权。 ## 验收标准 1. 验证码获取、登录成功、token 复用和 token 失效后的有限重登均有单元/集成测试。 2. 分页同步能处理 total 变化、重复页、空页、超时和中途重启。 3. 同一包裹重复执行同步不会重复插入；同一商品不同规格/数量不会互相覆盖。 4. yeeke 状态变化能幂等更新本地记录；接口失败不会覆盖已有有效状态。 5. 手动触发与定时触发使用同一租约，不能并发运行；默认定时任务保持关闭。 6. 同步摘要和错误日志不包含密码、验证码、token、Cookie、完整响应或订单个人信息。 7. 现有 SYB 同步、采购创建和 Agent 接口回归测试通过。 8. 未执行 yeeke 写操作、真实采购、下单或付款。 ## 依赖与未决事项 - 实施前确认 yeeke 响应中是否稳定提供包裹外部 ID；如没有，需根据 HAR 事实确定安全组合唯一键。 - 实施前确认 token 实际有效期和 Redis 是否为线上既有依赖；若无 Redis，应评估使用现有数据库会话存储，避免为单一 token 缓存增加不必要基础设施。 - HAR 中只观察到的状态枚举不能直接视为完整枚举，未知状态必须保留并告警，不得静默归类。 - 后续匹配/绑定/采购拦截工单依赖本单完成并验收。 ## 文档影响 长期事实变化预计需要更新架构与代码图、业务规则、安全边界和部署运维页面；实施时按 Wiki-first 规则同步。当前仅建立工单，不修改代码、数据库、线上配置或定时任务。 ## 退货商品页表格显示约束（已确认） 仅调整前端显示，不改变后端接口字段、数据库字段或同步数据结构： - 表头“商品id”显示为“蝦皮id”； - 表头“规格id”显示为“sku_id”； - 去掉“仓库/库位”显示列； - 在原“仓库/库位”位置增加独立“规格数据”列，展示规格文本/规格明细； - 仓库编码、仓库名称和库位仍可保存在同步数据中，但本次页面不展示该列。
ila commented 2026-09-23 09:50:36 +08:00
Author
Owner
Copy Link
Copy Source

审阅意见与用户决定（2026-09-23）

结论

方案合理，范围切分正确（先只读同步，匹配/绑定/采购替代后续工单）。以下为用户明确决定，按此修订本单。

1. yeeke 验证码 OCR：已批准

用户于 2026-09-23 明确批准：yeeke 登录可使用线上自建 OCR 服务（与 SYB 同一服务）。

  • 仓库规则已同步更新：AGENTS.md 的 OCR 例外由“仅 SYB”扩大为“SYB + yeeke 服务端登录”，并写明 OCR 请求与日志不得记录账号、密码、验证码原文或 token（提交 3ba93ec，已推送 main）。
  • 原工单正文中“已获用户明确批准的线上 OCR 例外”此前并不成立，现已通过本条批准补齐。
  • 长期文档（安全边界页）在实施时按 Wiki-first 同步。

2. yeeke 接入方式：参照 SYB

adapter/会话管理参照 sybclient：独立 client + SessionStore 式数据库会话存储（Load/Save/Delete + 会话有效性校验 + 失效后有限次重登）。

  • 线上没有 Redis（单 Go 进程 + MySQL），确认不引入 Redis；token/cookie 保留方式沿用线上 SYB 的数据库存储方案。

3. 增量与手动同步

自动同步允许存在少量遗漏，由管理员手动同步补齐；不要求实现回看重叠窗口等复杂补偿。手动与定时共用同一租约、不并发（原验收第 5 条保留）。

4. 记录消失（二次销售/销毁后脱离过滤条件）的处理

本单不处理，后续另行讨论。实施时不得因此删除本地记录。

5. 第三方访问节制

内部系统，不设门禁与额外限流要求。仍保留原工单的批量大小、重试次数上限可配置。

6. 测试数据

单元/集成测试直接使用 HAR 中的样例响应；HAR 本体禁止提交。

7. 可见范围

同步运行记录/摘要：管理员和采购员均可查看。不展示凭据、token、完整响应。

8. 仓库防护（已执行）

.gitignore 增加 *.har 与 /xml_data/，避免误提交第三方抓包（含凭据/token）与设备控件树导出（含收货地址）。同上提交 3ba93ec。

仍建议保留的原有要求

外部唯一键区分同包裹多商品/多规格、分页 total 变化与重复页处理、幂等更新、未知状态保留并告警、默认关闭定时任务、日志脱敏。

## 审阅意见与用户决定（2026-09-23） ### 结论 方案合理，范围切分正确（先只读同步，匹配/绑定/采购替代后续工单）。以下为用户明确决定，按此修订本单。 ### 1. yeeke 验证码 OCR：已批准 用户于 2026-09-23 明确批准：**yeeke 登录可使用线上自建 OCR 服务**（与 SYB 同一服务）。 - 仓库规则已同步更新：`AGENTS.md` 的 OCR 例外由“仅 SYB”扩大为“SYB + yeeke 服务端登录”，并写明 OCR 请求与日志不得记录账号、密码、验证码原文或 token（提交 `3ba93ec`，已推送 main）。 - 原工单正文中“已获用户明确批准的线上 OCR 例外”此前并不成立，现已通过本条批准补齐。 - 长期文档（安全边界页）在实施时按 Wiki-first 同步。 ### 2. yeeke 接入方式：参照 SYB adapter/会话管理参照 `sybclient`：独立 client + `SessionStore` 式数据库会话存储（Load/Save/Delete + 会话有效性校验 + 失效后有限次重登）。 - **线上没有 Redis**（单 Go 进程 + MySQL），确认不引入 Redis；token/cookie 保留方式沿用线上 SYB 的数据库存储方案。 ### 3. 增量与手动同步 自动同步允许存在少量遗漏，由**管理员手动同步**补齐；不要求实现回看重叠窗口等复杂补偿。手动与定时共用同一租约、不并发（原验收第 5 条保留）。 ### 4. 记录消失（二次销售/销毁后脱离过滤条件）的处理 本单**不处理**，后续另行讨论。实施时不得因此删除本地记录。 ### 5. 第三方访问节制 内部系统，不设门禁与额外限流要求。仍保留原工单的批量大小、重试次数上限可配置。 ### 6. 测试数据 单元/集成测试直接使用 HAR 中的样例响应；HAR 本体禁止提交。 ### 7. 可见范围 同步运行记录/摘要：**管理员和采购员均可查看**。不展示凭据、token、完整响应。 ### 8. 仓库防护（已执行） `.gitignore` 增加 `*.har` 与 `/xml_data/`，避免误提交第三方抓包（含凭据/token）与设备控件树导出（含收货地址）。同上提交 `3ba93ec`。 ### 仍建议保留的原有要求 外部唯一键区分同包裹多商品/多规格、分页 total 变化与重复页处理、幂等更新、未知状态保留并告警、默认关闭定时任务、日志脱敏。
ila commented 2026-09-23 16:54:46 +08:00
Author
Owner
Copy Link
Copy Source

退货商品页表格显示约束（补充确认）

仅调整前端显示，不改变后端接口字段、数据库字段或同步数据结构：

  • 表头“商品id”显示为“蝦皮id”；
  • 表头“规格id”显示为“sku_id”；
  • 去掉“仓库/库位”显示列；
  • 在“仓库/库位”原来的位置增加独立“规格数据”列，展示规格文本/规格明细；
  • 仓库编码、仓库名称和库位仍可保存在同步数据中，但本次页面不展示该列。
## 退货商品页表格显示约束（补充确认） 仅调整前端显示，不改变后端接口字段、数据库字段或同步数据结构： - 表头“商品id”显示为“蝦皮id”； - 表头“规格id”显示为“sku_id”； - 去掉“仓库/库位”显示列； - 在“仓库/库位”原来的位置增加独立“规格数据”列，展示规格文本/规格明细； - 仓库编码、仓库名称和库位仍可保存在同步数据中，但本次页面不展示该列。
ila commented 2026-09-23 17:12:14 +08:00
Author
Owner
Copy Link
Copy Source

已检查 Claude Code 的 #336/#337 实现，退货商品列表位于 feat/337-yeeke-admin-ui，不是当前 fix/230-horizontal-spec-selection 工作树。已按 #336 已确认的表格约束更新并提交：

  • 商品ID/规格ID → 蝦皮id / sku_id
  • 移除列表列 仓库/库位
  • 原位置新增 规格数据 列，展示规格文本
  • 不改后端字段、数据库字段或接口契约

提交：6773c88（已推送 feat/337-yeeke-admin-ui）。
验证：Web pnpm run build:prod 通过；全量 lint 仍有既有文件格式错误，与本次文件无关。当前未合并 main、未部署线上，待验收。

已检查 Claude Code 的 #336/#337 实现，退货商品列表位于 `feat/337-yeeke-admin-ui`，不是当前 `fix/230-horizontal-spec-selection` 工作树。已按 #336 已确认的表格约束更新并提交： - `商品ID/规格ID` → `蝦皮id / sku_id` - 移除列表列 `仓库/库位` - 原位置新增 `规格数据` 列，展示规格文本 - 不改后端字段、数据库字段或接口契约 提交：`6773c88`（已推送 `feat/337-yeeke-admin-ui`）。 验证：Web `pnpm run build:prod` 通过；全量 lint 仍有既有文件格式错误，与本次文件无关。当前未合并 main、未部署线上，待验收。
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin ila
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: OPC/goauto#336