cmautobuy/docs/task/236-档口入库码匹配自动登录.md

236 Admin：档口入库码匹配在会话过期时自动登录

• 类型：缺陷
• 父级大工单：#14
• 所属 MVP / 版本：#224
• 状态：已完成
• 日期：2026-08-15
• Gitea 工单：#236

背景与目标

档口入库码匹配依赖顺运宝登录会话。原实现发现本地缓存不存在或超过 24 小时后直接停止，采购员必须先进入“顺运宝数据”并启动同步，才能通过同步入口刷新会话。

本任务让匹配入口复用现有 OCR 自动登录：登录成功后继续处理原来勾选的记录，但不启动顺运宝同步。

最终方案

• 把“检查缓存、必要时自动登录”整理为 ensureInnerCodeMatchSession，由匹配 Handler 负责流程编排。
• 有效会话直接进入匹配，不调用 OCR。
• EnsureSybSession 返回 ErrSybLoginRequired 时调用现有 attemptSybAutoLogin；成功后沿用同一个 syb.Client 继续只读匹配。
• 自动登录成功只保存会话，不调用 startSybSync，因此不会因为匹配操作创建同步任务。
• OCR 未配置、不可达、识别失败或登录失败时停止在商品详情读取之前，提示失败原因和恢复路径。
• 普通会话缓存读取错误不尝试 OCR，继续按内部错误停止。
• 不修改 24 小时会话上限、数据库结构、匹配选中范围或顺运宝远端回写流程。

改了哪些

• admin/handler/web/inner_code.go：档口入库码匹配接入顺运宝自动登录，并补充成功/失败提示。
• admin/handler/web/inner_code_test.go：覆盖有效会话、过期后登录成功、自动登录失败、未配置 OCR 和普通读取错误。

验收结果

验收标准	结果
有效会话直接匹配且不调用自动登录	通过
过期或缺失会话自动登录一次，成功后允许继续匹配	通过
自动登录路径不启动顺运宝同步	通过
自动登录失败时不继续匹配并显示恢复提示	通过
普通会话读取错误不尝试 OCR	通过
匹配已选、占用保护和安全回写行为不变	通过
固定 Go 1.23.0 构建、测试和静态检查通过	通过

测试

• 执行的命令：
  • go test ./handler/web ./syb ./service -count=1
  • go test ./... -count=1
  • $env:GOTOOLCHAIN="go1.23.0"; go build ./...; go test ./... -count=1; go vet ./...
  • git diff --check
• 结果：全部通过。
• 没验证到的部分：未使用真实 OCR 和顺运宝账号执行自动登录；未在浏览器中勾选真实档口入库码记录完成端到端匹配；未在真实环境核对 syb_sync_runs 在自动登录匹配前后保持不变。任务无数据库迁移，未执行迁移测试。

相关提交

• 7b328b5 fix: 档口入库码匹配自动恢复顺运宝会话 (#236)