From 1abed648a5f03fd0471d3ed86aad2d795ad10df7 Mon Sep 17 00:00:00 2001 From: chengma Date: Thu, 13 Aug 2026 11:16:57 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BD=92=E6=A1=A3=E5=BA=97=E9=93=BA?= =?UTF-8?q?=E7=AE=A1=E7=90=86=E4=BB=BB=E5=8A=A1=20(#208=20#209=20#210=20#2?= =?UTF-8?q?11)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/task/208-全局店铺和渠道别名数据模型.md | 43 ++++++++++++++++++++ docs/task/209-SYB同步切换全局店铺.md | 42 +++++++++++++++++++ docs/task/210-蝦皮商品关联全局店铺.md | 42 +++++++++++++++++++ docs/task/211-独立店铺管理模块.md | 45 +++++++++++++++++++++ 4 files changed, 172 insertions(+) create mode 100644 docs/task/208-全局店铺和渠道别名数据模型.md create mode 100644 docs/task/209-SYB同步切换全局店铺.md create mode 100644 docs/task/210-蝦皮商品关联全局店铺.md create mode 100644 docs/task/211-独立店铺管理模块.md diff --git a/docs/task/208-全局店铺和渠道别名数据模型.md b/docs/task/208-全局店铺和渠道别名数据模型.md new file mode 100644 index 0000000..0a1701d --- /dev/null +++ b/docs/task/208-全局店铺和渠道别名数据模型.md @@ -0,0 +1,43 @@ +# 208 Admin：建立全局店铺和渠道别名数据模型 + +- 类型：需求 +- 父级大工单：#206 +- 所属 MVP / 版本：#207 +- 状态：已完成 +- 日期：2026-08-13 +- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/208 + +## 背景与目标 + +原 SYB 专属准入表不能表达蝦皮等其他渠道中的同一业务店铺。本任务建立稳定业务店铺身份，同时保留各渠道原始名称。 + +## 最终方案 + +MySQL v18 新增 `shops`、`shop_channel_aliases`，并为 `syb_orders`、`shopee_products` 增加可空 `shop_id`。旧 SYB 配置迁移成业务店铺和两个渠道名称，旧表保留。历史数据只按去除首尾空白后的渠道名称精确回填，无法确认时保持空。 + +## 改了哪些 + +- `admin/model/model.go`：增加店铺、渠道名称和业务关联字段。 +- `admin/repository/mysql_db.go`：增加可重放 v18 迁移与结构自检。 +- `admin/repository/shop.go`：增加店铺、渠道名称、状态和关联重建仓储。 +- `admin/repository/mysql_db_integration_test.go`：增加 v17 升级、重放和精确回填测试。 +- `docs/admin/03-data-model.md`：记录 v18 最终模型。 + +## 验收结果 + +| 验收标准 | 结果 | +|---|---| +| 首次迁移建立完整结构与约束 | 通过（代码、自检和测试已覆盖） | +| v17 升级迁移现有 SYB 配置且可重放 | 通过（已增加专用 MySQL 集成测试） | +| 原始店铺名不丢失，无法精确匹配保持空 | 通过 | +| 仓储支持店铺、别名和渠道开关 | 通过 | + +## 测试 + +- 执行的命令：在 `admin/` 执行 `go test ./...`、`go build ./...`、`git diff --check` +- 结果：Go 1.23.0 全部通过。 +- **没验证到的部分**：当前未配置独立 `_test` MySQL 8.4，新增真实 MySQL 迁移用例本次未实际运行。 + +## 相关提交 + +- `8f70772` 建立全局店铺跨渠道管理 diff --git a/docs/task/209-SYB同步切换全局店铺.md b/docs/task/209-SYB同步切换全局店铺.md new file mode 100644 index 0000000..73041f4 --- /dev/null +++ b/docs/task/209-SYB同步切换全局店铺.md @@ -0,0 +1,42 @@ +# 209 Admin：SYB 同步切换到全局店铺渠道配置 + +- 类型：重构 +- 父级大工单：#206 +- 所属 MVP / 版本：#207 +- 状态：已完成 +- 日期：2026-08-13 +- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/209 + +## 背景与目标 + +SYB 同步原来直接读取专属允许列表，需要切换到全局业务店铺的 SYB 渠道配置。 + +## 最终方案 + +同步开始时读取“业务店铺启用且 SYB 渠道启用”的名称到店铺 ID 快照。列表和明细仍按原始名称精确复核，写入时同时保存 `shop_id` 和原始 `shop_name`；分页、游标和失败停止规则未改变。 + +## 改了哪些 + +- `admin/service/syb.go`：改用渠道映射快照并向写入链路传递店铺 ID。 +- `admin/repository/syb.go`：订单和 SYB 蝦皮骨架写入稳定店铺关联。 +- `admin/service/syb_allowed_shop.go`：同步前置检查改读全局配置。 +- `admin/service/syb_test.go`：更新店铺准入和明细覆盖测试。 + +## 验收结果 + +| 验收标准 | 结果 | +|---|---| +| 迁移后允许店铺集合与旧配置一致 | 通过 | +| 停用 SYB 渠道后不再入库 | 通过 | +| 同步货运单保存 `shop_id` 和原始 `shop_name` | 通过 | +| 无启用店铺时安全停止且不推进游标 | 通过 | + +## 测试 + +- 执行的命令：在 `admin/` 执行 `go test ./...`、`go build ./...` +- 结果：Go 1.23.0 全部通过。 +- **没验证到的部分**：未使用真实顺运宝账号发起生产同步。 + +## 相关提交 + +- `8f70772` 建立全局店铺跨渠道管理 diff --git a/docs/task/210-蝦皮商品关联全局店铺.md b/docs/task/210-蝦皮商品关联全局店铺.md new file mode 100644 index 0000000..97563c2 --- /dev/null +++ b/docs/task/210-蝦皮商品关联全局店铺.md @@ -0,0 +1,42 @@ +# 210 Admin：蝦皮商品关联全局店铺并支持待关联筛选 + +- 类型：需求 +- 父级大工单：#206 +- 所属 MVP / 版本：#207 +- 状态：已完成 +- 日期：2026-08-13 +- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/210 + +## 背景与目标 + +蝦皮商品只有上游店铺原文，无法稳定指向 Admin 中的业务店铺，也无法集中找出未识别的数据。 + +## 最终方案 + +商品目录和 SYB 补建商品时按蝦皮渠道名称精确解析 `shop_id`，原始 `shopee_shop_name` 及字段来源保护保持不变。列表新增“业务店铺”列、具体店铺筛选和“待关联”筛选，翻页、详情和写操作继续保留筛选参数；停用店铺仍可筛选历史商品。 + +## 改了哪些 + +- `admin/repository/catalog_import.go`、`admin/repository/shopee.go`：写入关联及统一筛选。 +- `admin/service/shopee_list.go`、`admin/handler/web/shopee.go`：列表视图和参数透传。 +- `admin/templates/shopee/list.html`、`admin/static/js/app.js`：业务店铺列、筛选和模块状态。 +- `admin/service/catalog_import_test.go`：更新商品目录测试结构。 + +## 验收结果 + +| 验收标准 | 结果 | +|---|---| +| 精确别名可关联 `shop_id` | 通过 | +| 无别名或空店铺名保持待关联 | 通过 | +| 店铺筛选和待关联筛选分页计数一致 | 通过（列表与计数共用筛选条件） | +| 原始店铺名和字段来源保护不变 | 通过 | + +## 测试 + +- 执行的命令：在 `admin/` 执行 `go test ./...`、`go build ./...` +- 结果：Go 1.23.0 全部通过。 +- **没验证到的部分**：未在生产商品目录接口导入真实批次。 + +## 相关提交 + +- `8f70772` 建立全局店铺跨渠道管理 diff --git a/docs/task/211-独立店铺管理模块.md b/docs/task/211-独立店铺管理模块.md new file mode 100644 index 0000000..e0b2e31 --- /dev/null +++ b/docs/task/211-独立店铺管理模块.md @@ -0,0 +1,45 @@ +# 211 Admin：新增独立店铺管理模块 + +- 类型：需求 +- 父级大工单：#206 +- 所属 MVP / 版本：#207 +- 状态：已完成 +- 日期：2026-08-13 +- Gitea 工单：http://ilaer.eicp.net:8418/chengma/cmautobuy/issues/211 + +## 背景与目标 + +店铺配置原来藏在 SYB 页面，蝦皮等模块无法共同使用。目标是提供管理员专用的独立店铺管理入口。 + +## 最终方案 + +新增 `/shops` 管理路由、服务和页面，一行维护业务店铺、SYB 名称、蝦皮名称、全局状态与 SYB 同步状态。所有写操作使用 POST、CSRF 和管理员中间件；删除只允许全局停用且无业务引用的店铺。旧 `/syb/shops` 重定向到新模块，SYB 页面仅保留摘要入口。 + +## 改了哪些 + +- `admin/handler/web/shop.go`、`admin/service/shop.go`：管理员管理流程。 +- `admin/templates/shop/list.html`：独立管理页。 +- `admin/handler/web/web.go`、`admin/templates/partials/header.html`：路由和导航。 +- `admin/templates/syb/list.html`：同步摘要链接。 +- `admin/main_test.go`、`admin/service/shop_test.go`：权限、状态区分、删除和导航测试。 +- `docs/admin/05-ui-specification.md`：记录最终页面职责。 + +## 验收结果 + +| 验收标准 | 结果 | +|---|---| +| 管理员可进入并维护店铺及别名 | 通过 | +| 采购员不能访问写接口 | 通过 | +| 页面明确区分店铺启用和 SYB 同步启用 | 通过 | +| 原 SYB 页面只显示摘要并链接新模块 | 通过 | +| 导航和模块状态测试通过 | 通过 | + +## 测试 + +- 执行的命令：在 `admin/` 执行 `go test ./...`、`go build ./...`、`git diff --check` +- 结果：Go 1.23.0 全部通过。 +- **没验证到的部分**：尚未在 1366×768 浏览器中进行人工视觉验收。 + +## 相关提交 + +- `8f70772` 建立全局店铺跨渠道管理