hfb_sys/docs/线下提号字段扩展与店铺管理实施方案.md

线下提号字段扩展与店铺管理实施方案

一、进度与证据分类登记

1. 已知（附证据与确信度）

• 远程生产环境只读统计（确信度 100%）： 通过 SSH 连接生产服务器（aliyun, 42.121.217.194），从线上 MySQL 执行只读聚合查询： SELECT DISTINCT shop_name, COUNT(*) as cnt FROM admin_pickups GROUP BY shop_name ORDER BY cnt DESC; 获取到了全部 61 种历史店铺名称及统计分布（详见后文清单）。其中高频店铺包括：糖浆(1049)、王大锤游戏(846)、王大锤数娱(604)、淘宝王大锤网游专营店(494)等，亦包含部分历史空值和脏数据。
• 当前提号表结构（确信度 100%）： admin_pickups 现有字段包含 admin_id, platform, shop_name, listing_price_cent, profit_amount_cent 等，缺少 operator, third_party_order_no, order_amount_cent, deposit_amount_cent。
• 当前店铺来源逻辑（确信度 100%）： 现有 GET /api/v1/admin/pickups/shop-options 直接对 admin_pickups 表进行 Distinct("shop_name") 查询，没有独立的店铺配置表。
• 当前筛选条件（确信度 100%）： 现有列表仅支持关键词、状态、店铺、账号来源、线下结算状态筛选，缺少精确到“日期+时间”的时间范围筛选。
• SQL 防线与测试规范（确信度 100%）： scripts/check-sql-guard.sh 对 migration 追加、Goose Up/Down 规范以及单号唯一索引直达有严格断言。

2. 未知与假设（附当前假设与确信度）

• 店铺历史脏数据映射（确信度 100%）： 用户表示后续会提供具体的店铺映射规则；当前阶段先完成标准店铺表设计及 CRUD 管理功能，前端与接口在选择店铺时兼容已录入店铺和历史店铺。
• 操作人录入习惯（确信度 95%）： 创建提号时，操作人字段默认自动预填当前登录管理员的用户名/昵称，同时支持管理员自由修改输入为客服名或经办人姓名。

---

二、生产环境历史店铺名称只读清单（共 61 项）

序号	店铺名称	历史提号单量	备注/分类特征
1	糖浆	1049	主力店铺
2	王大锤游戏	846	主力店铺
3	王大锤数娱	604	主力店铺
4	淘宝王大锤网游专营店	494	淘宝渠道
5	咸鱼大锤商行小白	170	闲鱼渠道
6	拼多多王大锤数娱	152	拼多多渠道
7	淘宝王大锤网游	149	淘宝渠道
8	糖浆游戏 拼多多	143	拼多多渠道
9	(空字符串)	137	未填店铺
10	咸鱼羊小胖	114	闲鱼渠道
11	咸鱼滑翔伞	110	闲鱼渠道
12	咸鱼大锤商行	68	闲鱼渠道
13	王大锤游戏专营	36	主力店铺变体
14	咸鱼西红柿不错	35	闲鱼渠道
15	微信	33	微信私域
16	拼多多游戏	32	拼多多渠道
17	王大锤网游专营店	30	淘宝/天猫变体
18	淘宝艾优游戏	30	淘宝渠道
19	游戏	29	简写
20	淘宝三角洲行动租号商行	27	淘宝渠道
21	闲鱼羊小胖	23	闲鱼渠道
22	富友	18	渠道/平台
23	滑翔伞	17	简写
24	宜收宝	15	渠道/平台
25	淘宝大锤商行	15	淘宝渠道
26	西红柿不错	14	简写
27	三角洲行动租号商行	11	简写
28	大锤商行	9	简写
29	羊小胖	8	简写
30	数	7	简写脏数据
31	三角洲行动商行	6	简写
32	三角洲行动	6	简写
33	淘宝356166138小边	5	淘宝单店
34	艾优	4	简写
35	溟科	4	机构/分销
36	覃公子未付	4	临时备注型店铺名
37	11.25 7	3	日期数字型脏数据
38	艾优游戏	3	简写
39	小边	3	客服/分销
40	数娱	3	简写
41	淘宝王大锤商行	3	淘宝渠道
42	富友+宜收宝	2	复合渠道
43	淘宝易磊	2	淘宝单店
44	半野潮汐俱乐部	2	专营店
45	10.17W免押500	2	备注型脏数据
46	7.20 拼多多东	2	日期拼多多型
47	超帅	1	别名
48	0526🐠	1	特殊符号
49	西红柿	1	简写
50	行动	1	简写
51	淘宝980493223	1	淘宝店号
52	.7.22	1	日期型
53	网游	1	简写
54	Lost	1	别名
55	七友	1	别名
56	大锤	1	简写
57	王大锤商行	1	简写
58	爱优游戏	1	同音别名
59	小白	1	客服名
60	深南群主正常拿号	1	渠道拿号说明
61	撞车 / 正在输入	各 1	临时测试/异常字符

---

三、方案设计与改造范围

1. 数据库升级 (000079_admin_pickup_extra_fields_and_shops.sql)

1. 对 admin_pickups 表增加 4 个字段及必要索引：
   • operator VARCHAR(64) NOT NULL DEFAULT '' COMMENT '操作人（如客服/运营人员名字）'
   • third_party_order_no VARCHAR(128) NOT NULL DEFAULT '' COMMENT '第三方订单号'
   • order_amount_cent BIGINT NOT NULL DEFAULT 0 COMMENT '下单金额(分)'
   • deposit_amount_cent BIGINT NOT NULL DEFAULT 0 COMMENT '押金金额(分)'
   • 索引：idx_admin_pickups_third_party_order_no, idx_admin_pickups_operator
2. 新增店铺配置表 pickup_shops：
   • id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY
   • name VARCHAR(100) NOT NULL UNIQUE COMMENT '店铺名称'
   • platform VARCHAR(32) NOT NULL DEFAULT '' COMMENT '所属平台'
   • status VARCHAR(20) NOT NULL DEFAULT 'active' COMMENT '状态: active/disabled'
   • sort_order INT NOT NULL DEFAULT 0 COMMENT '排序权重'
   • remark VARCHAR(255) NOT NULL DEFAULT '' COMMENT '备注'
   • created_at DATETIME NOT NULL, updated_at DATETIME NOT NULL
   • 索引：uk_pickup_shop_name, idx_pickup_shop_status

2. 后端核心代码改造

• backend/internal/model/pickup.go：结构体添加新增字段。
• backend/internal/model/pickup_shop.go：创建店铺模型。
• backend/internal/modules/pickup/dto.go：
  • PickupDTO 扩充 Operator, ThirdPartyOrderNo, OrderAmountCent, DepositAmountCent；
  • CreateRequest 扩充对应 4 个字段；
  • AdminPickupQuery 增加 StartTime, EndTime 时间范围筛选；
  • 增加 PickupShopDTO, CreatePickupShopRequest, UpdatePickupShopRequest, PickupShopQuery 等 DTO。
• backend/internal/modules/pickup/repository.go：
  • Create 写入新字段，并在事件与审计日志中留痕；
  • applyAdminPickupFilters 增加 p.created_at >= ? 与 p.created_at <= ? 时间筛选；关键词搜索补充支持第三方单号与操作人；
  • 增加店铺管理 CRUD：ListShops, CreateShop, UpdateShop, DeleteShop；
  • ListShopNames：优先读取 pickup_shops 活跃店铺，并合并 admin_pickups 历史店铺去重返回。
• backend/internal/modules/pickup/handler.go & handler_parse.go：
  • 解析 query 参数中的 start_time 与 end_time（支持多种格式）；
  • 实现店铺增删改查处理函数。
• backend/internal/router/router.go：注册店铺相关路由。

3. 前端界面重构与布局优化

• 创建线下提号弹窗布局优化：
  • 第一行（双列）：左侧「账号来源」，右侧「操作人」（默认当前登录用户，可手动修改）。
  • 第二行（全宽）：「选择账号」（带远程搜索、来源确认与价格快照）。
  • 第三行（双列）：左侧「第三方订单号」，右侧「交易渠道」。
  • 第四行（全宽）：「店铺名称」（下拉选择已有店铺，右侧提供店铺管理快捷入口）。
  • 第五行（三列金额区块）：
    • 「下单金额(元)」
    • 「押金金额(元)」
    • 「线下利润(元)」
  • 第六行（全宽）：「备注」。
  • 底部操作按钮及说明提示。
• 店铺管理功能：
  • 线下提号页面顶部增加「店铺管理」入口；
  • 弹出全功能店铺管理对话框，支持店铺列表、新增、编辑、启用/禁用、删除；
  • 店铺变更后自动同步刷新外层提号的店铺下拉选择框。
• 时间筛选（日期+时间）：
  • 筛选栏加入 el-date-picker（type="datetimerange"），格式精确到秒；
  • 支持快捷查询与一键重置。
• 提号列表与详情页字段展示：
  • 列表中增加操作人、第三方单号、下单金额、押金金额的展示；
  • 详情页概览卡片同步展示新增字段。

4. 历史店铺可视化手动映射与一键清洗方案 (000080_pickup_shop_mappings.sql)

• 数据表与持久化：
  • admin_pickups 增加 raw_shop_name VARCHAR(100) 字段，永久留存提号单录入时的原始店铺名，确保清洗操作可追溯且可还原；
  • 新建 pickup_shop_mappings 历史映射别名表，记录 source_name, target_shop_id, target_shop_name, mapped_count, remark。
• 后端服务能力：
  • GET /api/v1/admin/pickup-shops/historical-stats：聚合统计线上历史店铺数量及每个店铺的提号单量，并标记 standard（标准店）、mapped（已映射）、unmapped（待映射）；
  • POST /api/v1/admin/pickup-shops/map-historical：支持单条或批量将历史变体名称映射至目标标准店铺，并在原子事务内将 admin_pickups 的 shop_name 批量清洗更新，同时写入映射规则与审计日志；
  • DELETE /api/v1/admin/pickup-shops/mappings：支持撤销映射规则并将对应历史提号单的店铺名安全还原为原始名称；
  • 自动归一化：新建提号单时，若录入已映射的别名，自动归一化为目标标准店铺名，同时将原名称存入 raw_shop_name，防止未来脏数据再次混入。
• 前端可视化管理：
  • PickupShopDialog.vue 升级为双 Tab 结构：
    • Tab 1（标准店铺库）：标准店铺增删改查、启用/禁用、权重排序；
    • Tab 2（历史店铺映射与清洗）：顶部展示统计卡片（历史总数/已入库/已映射/待映射/涉及单量），列表直观展示 61 个历史名称与对应单量、当前状态；支持批量勾选映射、一键【设为标准】、单个【映射】、【重映射】与【撤销】。

---

四、生产克隆数据全链路回归验证证据

1. 生产数据安全克隆过程：

   • 连接生产环境 aliyun (42.121.217.194:2233)，以只读形式 mysqldump 克隆线下提号核心数据及关联支撑数据：
     • admin_pickups：4,498 条记录；
     • admin_pickup_financial_adjustments：30 条财务调整记录；
     • 提号单关联的号主 users (2,050 人)、商品 rental_listings (4,391 项)、账号 game_accounts (4,391 个)；
   • 导入本地 hfb-mysql 容器中的 hfb_sys 开发测试库，并执行 UPDATE admin_pickups SET raw_shop_name = shop_name; 完成基准校准；
   • 远端与本地临时 dump 压缩包已全量清理完毕，无脏文件遗留。

2. 全流程回归测试用例验证 (TestClonedProdDataOperations)：

   • 基准核验：4,498 条线上真实提号单，准确识别出 62 种历史店铺名（含未填空值），Top 店铺统计完全吻合（糖浆 1049、王大锤游戏 847、王大锤数娱 606、淘宝王大锤网游专营店 494、咸鱼大锤商行小白 170 等）；
   • 一键转标准店铺：「糖浆」一键录入标准库，状态由 unmapped 自动转为 standard；
   • 批量映射与清洗：将「王大锤游戏专营」(36单)、「淘宝王大锤商行」(3单)、「王大锤商行」(1单) 批量映射至「王大锤游戏」：
     • 原子事务执行成功，40 条提号记录的 shop_name 全部清洗更新为「王大锤游戏」；
     • 40 条记录的 raw_shop_name 准确留存原始输入字样，未发生数据损毁；
   • 业务列表与时间范围筛选：
     • 按标准店铺「王大锤游戏」查询：总单量从 847 单准确提升至 887 单；
     • 按 2026 年 8 月份时间范围筛选：准确检索出 2,111 单；
   • 撤销映射与安全还原：撤销「王大锤商行」规则后，对应记录的 shop_name 自动恢复为原始字样「王大锤商行」，数据完全可逆。