bulk-brand-import.md

Bulk Brand Import Playbook

本文档描述 Fluxa Map 当前用于“批量添加品牌门店”的实际流程、判断标准和注意事项。

适用场景：

• 先批量铺设品牌门店，但暂时没有真实支付记录
• 需要只创建 shell location，不写 attempt
• 需要结合官方门店源和地图 POI，提高名称、地址、坐标质量

1. 目标原则

批量导入时，优先保证以下事情：

• 不创建重复品牌
• 不写错误的 attempt
• 不把闭店门店导入进库
• 不把明显漂移或低精度点位强行写入
• 不把“同店不同名”当成多家店
• 不让新的 shell 记录覆盖旧的真实记录
• 地址尽可能细，坐标尽可能准

2. 品牌处理规则

导入前先查现有品牌：

• 如果品牌已存在，直接复用
• 不重复创建只是名字略有差别的品牌

当前已经验证过的做法：

• 优衣库 直接复用已有品牌
• 星巴克 (Starbucks) 直接复用已有品牌

注意：

• 品牌详情页里的地点归属，依赖 shell location 里的 brand 文本值
• 所以写入 fluxa_locations 时，brand 字段必须和目标品牌展示名一致

3. 导入目标表

批量铺店默认写：

• fluxa_locations

不写：

• pos_attempts
• 初始支付尝试

对应原则：

• 这是 shell location 导入，不是 POS 交易记录导入
• 只有后续真实 attempt 才应该把 shell location 逐步转成真实 POS 轨迹

3.1 真实记录优先原则

这里的“真实记录”指：

• 来自真实用户或志愿者手工提交的 pos_machines
• 带真实支付、真实常识判断或人工核验背景的历史记录

处理原则：

• 新导入的 shell location 只能作为补全层，不能覆盖真实记录
• 如果 shell 与真实记录指向同一家店，应做合并展示，而不是让 shell 把真实记录顶掉
• 合并时，优先保留真实记录的来源身份、创建者和真实轨迹
• shell 只能补全更规整的品牌归属、官方名称、官方地址、官方编码或更可靠坐标

禁止做法：

• 因为官方源更整齐，就直接删除旧的真实记录
• 因为 shell 坐标更漂亮，就强行把真实记录当成低质量记录替换掉
• 只在 fluxa_locations 内部查重，不和现有真实记录一起查重

导入实现要求：

• 导入前查重必须基于“合并视图”而不是只看 fluxa_locations
• 如果发现库里已经有真实记录，优先复用或合并该记录，不重复铺一条平行 shell
• 如果暂时不能自动安全合并，宁可跳过并留待人工整理，也不要让 shell 覆盖真实记录

4. 数据源优先级

当前采用“双源策略”：

1. 官方门店源

• 负责“是否应该存在”
• 负责完整门店清单
• 负责官方名称、官方地址、官方状态、官方编码

2. 地图 POI 源

• 负责“坐标是否更准”
• 负责地址是否可以更适合地图展示
• 只在高置信命中时覆盖官方点位

当前实践：

• 优衣库：uniqlo.cn 官方门店列表 + AMap JS
• 星巴克：starbucks.com.cn 官方门店列表 + AMap JS

5. 基本导入流程

第一步：拿官方完整门店清单

要求：

• 先拿全量官方门店
• 必须保留官方门店编码
• 必须拿到当前官方状态字段，不能只拿门店名和地址

目的：

• 后续可精确查重
• 可识别闭店、OFFLINE、CLOSED
• 可避免“地图搜得到，但官方已经下线”的误导入

第二步：名称和地址规范化

需要做的清洗：

• 去掉重复行政区前缀
• 去掉重复省市，如 上海市上海市...
• 去掉明显脏前缀或错误拼接
• 名称统一成品牌内的规范格式

示例：

• 优衣库（上海南京西路全球旗舰店） 规范成 优衣库(上海南京西路全球旗舰店)
• 避免出现 北京市北京市...
• 避免出现 浦东新区浦东新区...

第三步：地图校准

地图 POI 不是强制覆盖源，只是校准源。

规则：

• 先用品牌 + 城市/区域建立地图候选池
• 再按单店名、地址、距离做评分
• 只有高置信命中时，才用地图点位覆盖官方点位

高置信依据通常包括：

• 店名强匹配
• 地址强匹配
• 商业体匹配
• 距离足够近
• 地图结果本身不是低精度 POI

如果达不到阈值：

• 保留官方坐标
• 保留官方详细地址
• 绝不为了“用了地图”而硬覆盖成错点

6. 查重规则

导入前必须做两层去重：

6.1 官方编码去重

最高优先级：

• 官方编码相同，视为同一家店

用途：

• 防止重复导入
• 后续增量同步时可稳定 upsert

6.2 同店判定去重

当名字不完全一致时，仍要防止重复：

• 近似地址
• 名称归一化
• 商业体一致
• 距离很近

典型问题：

• 同一家店可能出现多个名字变体
• 如城市名前缀不同
• 或品牌前缀、括号、分店描述不同

结论：

• “名字略有差别，但地址几乎相同”的，应该判成同店
• “旧真实记录名字较脏，但商场、地址、距离和品牌语义都指向同一家店”的，也应优先向真实记录合并

7. 闭店与失效店过滤

这是本流程里最重要的质量门之一。

7.1 绝对不导入的情况

满足任一条都不应保留：

• 名称中明确包含 已闭店 / 闭店
• 官方 shopStatus != ONLINE
• 官方明确返回 CLOSED
• 官方明确返回 OFFLINE

7.2 当前已经验证过的实际问题

优衣库全国核查时，确实发现并清掉了这类错误店：

• 121809 上海新田360广场康桥店，官方 OFFLINE
• 130269 上海博物东馆(已闭店），官方 CLOSED
• 102591 杭州银泰百货庆春店，官方 OFFLINE
• 132016 合肥瑶海天地，官方 CLOSED
• 116466 南昌青山湖万达广场店，官方 CLOSED
• 121088 武汉金银湖万达广场，官方 CLOSED
• 101414 深圳华强北茂业百货店，官方 OFFLINE

处理原则：

• 不是改名隐藏
• 而是直接删除错误 shell location

7.3 验收要求

导入后必须再扫一遍库：

• 名称/备注中不得残留 已闭店
• 不得残留 CLOSED
• 不得残留 OFFLINE

8. 迁址与迁店注意事项

闭店不是唯一风险，迁址也要注意。

高风险情况：

• 官方编码还在，但地址明显变更
• 商场同名店迁到新楼层/新铺位
• 地图点位还停留在旧地址

处理建议：

• 以官方当前地址为基线
• 地图只用于高置信坐标修正
• 如果地址变化明显但地图还命中旧点，不要继续沿用旧地图点位

9. 导入后验收清单

每次批量导入后至少要做下面这些检查：

1. 总数对齐

• 数据库总数应和官方当前有效门店总数一致

2. 编码完整

• 每一条导入记录都应带官方编码
• 不能出现无编码记录混入正式结果

3. 编码唯一

• 同一官方编码只能有一条记录

4. 闭店清理

• 不能残留 已闭店 / CLOSED / OFFLINE

5. 地址质量

• 不能出现明显重复前缀
• 不能出现脏拼接

6. 品牌一致

• 所有地点的 brand 必须正确指向目标品牌展示名

7. 不写 attempt

• shell 导入不得生成支付尝试记录

10. 当前已验证品牌

星巴克

• 品牌名：星巴克 (Starbucks)
• 当前 shell 地点数应与星巴克中国官方现役门店总数一致
• 当前全量文本扫描未发现 已闭店 / CLOSED / OFFLINE 残留标记

优衣库

• 品牌名：优衣库
• 当前已按官方非营业状态清掉闭店/下线门店
• 当前库内不再残留 已闭店 / CLOSED / OFFLINE 标记

11. 操作建议

以后继续做批量品牌导入时，顺序建议固定为：

1. 查品牌是否已存在
2. 拉官方全量门店和官方状态
3. 过滤非营业门店
4. 规范化名称和地址
5. 用地图做高置信坐标校准
6. 与现有真实记录和 shell 记录一起做统一查重
7. 以官方编码做主键级查重
8. 仅在不会覆盖真实记录时写入 shell
9. 导入后再做闭店/重复/地址质量验收

12. 不应做的事

不要这样做：

• 只靠地图搜索结果直接全量导入
• 不看官方状态就把门店写进库
• 因为地图点更“像真的”就覆盖官方地址
• 创建重复品牌
• 把 shell 铺店和交易 attempt 混在一起
• 只看店名完全一致才查重
• 用新的 shell 记录去覆盖旧的真实记录
• 因为真实记录不够整齐，就把它当作低质量数据直接替换

13. 当前文档结论

批量品牌导入的底线是：

• 官方门店源决定“应不应该存在”
• 地图源决定“能不能更精准”
• 任何闭店、下线、明显失效门店都不能保留
• 任何 shell 导入都必须可通过官方编码复核和清理
• 任何真实记录都优先于新 shell；shell 只能补全和合并，不能覆盖真实记录