Admin：按允许店铺筛选顺运宝同步入库 #196

New Issue

2026-08-12T18:38:08+08:00

ila commented

2026-08-12 18:38:08 +08:00

基本信息

类型：需求
父级大工单：#14
所属 MVP / 版本：#15 / 顺运宝同步店铺准入
阶段：顺运宝数据接入治理

要解决什么

当前顺运宝日期同步会把查询范围内所有店铺的货运单写入 Admin。客户只处理指定店铺，非目标店铺继续拉取明细并入库会增加噪声、人工筛选成本和外部请求量。需要由管理员维护全局店铺白名单，后续同步只接收启用店铺，同时不能削弱既有分页完整性和游标安全保护。

做什么 / 不做什么

做：
- 新增 MySQL v14：持久化顺运宝允许店铺，并扩展同步记录的接受/店铺跳过统计及白名单快照哈希。
- 新增管理员专用店铺管理页，支持新增、停用和重新启用；采购员只在顺运宝页看到启用店铺数量。
- 同步开始时读取一次启用白名单快照；按去除首尾空白后的店铺名精确匹配。
- 白名单为空时关闭失败：不请求顺运宝、不推进游标，并给出可操作提示。
- 仍对顺运宝原始全部货运单完成总量、分页和唯一 ID 校验；校验完成后才筛选，非目标店铺不拉明细、不入库。
- 明细响应若把店铺改成非白名单或空值，再次拦截，不写该货运单。
- 同步记录展示原始货运单、接受货运单、店铺跳过数量。
- 补充数据模型、界面和顺运宝同步文档。
不做：
- 不删除或回写历史已入库的非白名单货运单。
- 不按用户分别维护白名单，不做模糊/正则匹配，不自动猜测空店铺。
- 不改变 Client 四接口、任务逻辑、顺运宝账号配置和采购安全红线。

怎么做

admin/repository/mysql_db.go 追加可重放且带自检的 MySQL schema v14；历史迁移不改写。
在 admin/model、admin/repository、admin/service 增加允许店铺模型、参数化 CRUD、权限校验及稳定快照哈希。
在 admin/service/syb.go 保持“原始总量熔断 → 全量分页完整性校验 → 白名单筛选 → 允许货运单明细请求/写入”的顺序；同步过程只使用启动时快照。
在 admin/handler/web 和 admin/templates/syb 增加管理员 GET/POST 路由，所有写操作经过现有登录和 CSRF 防护；使用已有服务端渲染和三段式页面样式。
同步记录保留现有 stock_count 作为原始货运单数，新增接受和店铺跳过字段，旧记录回填为“接受=原始、跳过=0”。
修改预计涉及：admin/model/model.go、admin/repository/mysql_db.go、admin/repository/syb.go、admin/service/syb.go、admin/handler/web/*.go、admin/templates/syb/*.html、相关测试和 docs/admin/03/05/08。

验收标准

管理员可新增店铺、停用和重新启用；重名、空名有明确错误，采购员不能进入管理页或调用写接口。
未配置任何启用店铺时，同步在任何顺运宝请求前失败，不推进游标。
同步对原始全量继续执行容量与分页完整性校验，白名单不会掩盖列表漂移。
只有名称精确匹配启用白名单的货运单才请求明细并写库；首尾空白被忽略，空名/未知名被跳过。
列表通过但明细店铺变成空值或非白名单时，该货运单不会写库。
同一次同步固定使用启动时白名单快照；运行中改配置不改变本次结果。
同步记录可区分原始货运单、接受货运单和店铺跳过数，并保存快照哈希。
既有历史顺运宝数据不被删除，Client 四接口和任务行为回归通过。
MySQL v14 首次建库、v13 升级、失败重放、重复迁移和 schema 自检通过。
固定 Go 1.23.0 下 go vet ./...、go build ./...、go test ./... -count=1 通过。

怎么验证

从 admin/ 执行：

gofmt -w <本工单修改的 Go 文件>
$env:GOTOOLCHAIN="go1.23.0"
go vet ./...
go build ./...
go test ./... -count=1
Remove-Item Env:GOTOOLCHAIN

另使用独立、名称以 _test 结尾的 MySQL 8.4 测试库验证 v14 首建、v13 升级、失败重放、重复迁移和自检；浏览器核对 1366×768 页面、管理员/采购员权限、CSRF 与空白名单提示。

风险和回退

风险：空白名单会有意阻止同步；上线前必须先配置至少一个启用店铺。
风险：店铺名由上游提供，改名或空值会被安全跳过；同步记录用于发现跳过量异常。
风险：若先筛选再校验分页会静默漏单，因此实现必须保持原始全量校验在前。
回退：回退应用版本不会删除新增表/列；v14 迁移为追加式，旧程序忽略新结构。历史货运单不自动清理，业务数据可保留。

实施记录

状态：已验收。
功能提交：8a8fff8
归档提交：7cdfc6d
本地归档：docs/task/196-顺运宝同步店铺准入.md
固定 Go 1.23.0：go vet ./...、go build ./...、go test ./... -count=1 全部通过。
未验证：当前环境未配置独立 MySQL 8.4 _test 库，真实 v14 首建/升级/失败重放尚未运行；浏览器 1366×768 人工视觉与权限操作尚未执行；未部署生产、未在生产执行 v14。

## 基本信息 - 类型：需求 - 父级大工单：#14 - 所属 MVP / 版本：#15 / 顺运宝同步店铺准入 - 阶段：顺运宝数据接入治理 ## 要解决什么当前顺运宝日期同步会把查询范围内所有店铺的货运单写入 Admin。客户只处理指定店铺，非目标店铺继续拉取明细并入库会增加噪声、人工筛选成本和外部请求量。需要由管理员维护全局店铺白名单，后续同步只接收启用店铺，同时不能削弱既有分页完整性和游标安全保护。 ## 做什么 / 不做什么 - 做： - 新增 MySQL v14：持久化顺运宝允许店铺，并扩展同步记录的接受/店铺跳过统计及白名单快照哈希。 - 新增管理员专用店铺管理页，支持新增、停用和重新启用；采购员只在顺运宝页看到启用店铺数量。 - 同步开始时读取一次启用白名单快照；按去除首尾空白后的店铺名精确匹配。 - 白名单为空时关闭失败：不请求顺运宝、不推进游标，并给出可操作提示。 - 仍对顺运宝原始全部货运单完成总量、分页和唯一 ID 校验；校验完成后才筛选，非目标店铺不拉明细、不入库。 - 明细响应若把店铺改成非白名单或空值，再次拦截，不写该货运单。 - 同步记录展示原始货运单、接受货运单、店铺跳过数量。 - 补充数据模型、界面和顺运宝同步文档。 - 不做： - 不删除或回写历史已入库的非白名单货运单。 - 不按用户分别维护白名单，不做模糊/正则匹配，不自动猜测空店铺。 - 不改变 Client 四接口、任务逻辑、顺运宝账号配置和采购安全红线。 ## 怎么做 - `admin/repository/mysql_db.go` 追加可重放且带自检的 MySQL schema v14；历史迁移不改写。 - 在 `admin/model`、`admin/repository`、`admin/service` 增加允许店铺模型、参数化 CRUD、权限校验及稳定快照哈希。 - 在 `admin/service/syb.go` 保持“原始总量熔断 → 全量分页完整性校验 → 白名单筛选 → 允许货运单明细请求/写入”的顺序；同步过程只使用启动时快照。 - 在 `admin/handler/web` 和 `admin/templates/syb` 增加管理员 GET/POST 路由，所有写操作经过现有登录和 CSRF 防护；使用已有服务端渲染和三段式页面样式。 - 同步记录保留现有 `stock_count` 作为原始货运单数，新增接受和店铺跳过字段，旧记录回填为“接受=原始、跳过=0”。 - 修改预计涉及：`admin/model/model.go`、`admin/repository/mysql_db.go`、`admin/repository/syb.go`、`admin/service/syb.go`、`admin/handler/web/*.go`、`admin/templates/syb/*.html`、相关测试和 `docs/admin/03/05/08`。 ## 验收标准 - [x] 管理员可新增店铺、停用和重新启用；重名、空名有明确错误，采购员不能进入管理页或调用写接口。 - [x] 未配置任何启用店铺时，同步在任何顺运宝请求前失败，不推进游标。 - [x] 同步对原始全量继续执行容量与分页完整性校验，白名单不会掩盖列表漂移。 - [x] 只有名称精确匹配启用白名单的货运单才请求明细并写库；首尾空白被忽略，空名/未知名被跳过。 - [x] 列表通过但明细店铺变成空值或非白名单时，该货运单不会写库。 - [x] 同一次同步固定使用启动时白名单快照；运行中改配置不改变本次结果。 - [x] 同步记录可区分原始货运单、接受货运单和店铺跳过数，并保存快照哈希。 - [x] 既有历史顺运宝数据不被删除，Client 四接口和任务行为回归通过。 - [x] MySQL v14 首次建库、v13 升级、失败重放、重复迁移和 schema 自检通过。 - [x] 固定 Go 1.23.0 下 `go vet ./...`、`go build ./...`、`go test ./... -count=1` 通过。 ## 怎么验证从 `admin/` 执行： ```powershell gofmt -w <本工单修改的 Go 文件> $env:GOTOOLCHAIN="go1.23.0" go vet ./... go build ./... go test ./... -count=1 Remove-Item Env:GOTOOLCHAIN ``` 另使用独立、名称以 `_test` 结尾的 MySQL 8.4 测试库验证 v14 首建、v13 升级、失败重放、重复迁移和自检；浏览器核对 1366×768 页面、管理员/采购员权限、CSRF 与空白名单提示。 ## 风险和回退 - 风险：空白名单会有意阻止同步；上线前必须先配置至少一个启用店铺。 - 风险：店铺名由上游提供，改名或空值会被安全跳过；同步记录用于发现跳过量异常。 - 风险：若先筛选再校验分页会静默漏单，因此实现必须保持原始全量校验在前。 - 回退：回退应用版本不会删除新增表/列；v14 迁移为追加式，旧程序忽略新结构。历史货运单不自动清理，业务数据可保留。 ## 实施记录 - 状态：已验收。 - 功能提交：`8a8fff8` - 归档提交：`7cdfc6d` - 本地归档：`docs/task/196-顺运宝同步店铺准入.md` - 固定 Go 1.23.0：`go vet ./...`、`go build ./...`、`go test ./... -count=1` 全部通过。 - 未验证：当前环境未配置独立 MySQL 8.4 `_test` 库，真实 v14 首建/升级/失败重放尚未运行；浏览器 1366×768 人工视觉与权限操作尚未执行；未部署生产、未在生产执行 v14。

ila referenced this issue

2026-08-12 18:38:21 +08:00

[Epic] Admin 采集采购管理端 #14

ila referenced this issue

2026-08-12 18:38:21 +08:00

[MVP] Admin 四模块可用闭环 #15

ila commented

2026-08-12 18:47:42 +08:00

实施进度

已完成代码和文档实现，进入提交前复核：

已追加 MySQL v14：syb_allowed_shops、接受/店铺跳过统计、白名单快照哈希。
已增加管理员专用店铺新增、停用、重新启用页面，写操作受登录、管理员权限和 CSRF 保护。
同步入口在会话、OCR、验证码等顺运宝请求前检查空白名单；后台再次检查以防竞态。
保持原始总量熔断和完整分页校验在前，之后按启动时快照筛选；非目标店铺不拉明细、不入库。
明细店铺覆盖列表店铺后再次核对，空值或非允许店铺不写入。
同步记录和状态摘要区分原始、接受、店铺跳过、数量跳过。
SQLite→MySQL 历史工具会把旧同步记录补为“接受=原始”，不改变摘要核对列。

已通过固定 Go 1.23.0 的 go vet ./...、go build ./...、go test ./... -count=1。真实 MySQL 8.4 _test 集成测试用例已补充，但本机未设置测试库环境，尚未实际执行。

## 实施进度已完成代码和文档实现，进入提交前复核： - 已追加 MySQL v14：`syb_allowed_shops`、接受/店铺跳过统计、白名单快照哈希。 - 已增加管理员专用店铺新增、停用、重新启用页面，写操作受登录、管理员权限和 CSRF 保护。 - 同步入口在会话、OCR、验证码等顺运宝请求前检查空白名单；后台再次检查以防竞态。 - 保持原始总量熔断和完整分页校验在前，之后按启动时快照筛选；非目标店铺不拉明细、不入库。 - 明细店铺覆盖列表店铺后再次核对，空值或非允许店铺不写入。 - 同步记录和状态摘要区分原始、接受、店铺跳过、数量跳过。 - SQLite→MySQL 历史工具会把旧同步记录补为“接受=原始”，不改变摘要核对列。已通过固定 Go 1.23.0 的 `go vet ./...`、`go build ./...`、`go test ./... -count=1`。真实 MySQL 8.4 `_test` 集成测试用例已补充，但本机未设置测试库环境，尚未实际执行。

ila referenced this issue

2026-08-13 08:45:29 +08:00

Admin：允许删除已停用的顺运宝同步店铺 #197

ila commented

2026-08-14 09:20:39 +08:00