GEO 内容分层适配逻辑设计

GEO 分层适配：基于用户地理位置（国家 / 大区 / 省份 / 城市 / 商圈 / IP / 经纬度），对内容、文案、功能、权益、资源、UI做分层分发与渲染，做到不同地域看到不一样的业务内容，同时兼顾兜底、降级、灰度、权限、数据一致性。核心目标：地域精准匹配、异常可降级、配置可运营、性能可控、可追溯。

一、先梳理 GEO 维度分层（粒度由粗到细）

先定义系统内 GEO 层级字典，统一编码，避免各业务各自维护地理库。

重要：同一个用户会有多套 GEO 来源：GPS 定位、IP 地址、账号属地、用户手动选择，需要设计 GEO 优先级策略。

GEO 来源优先级（可配置）

示例通用规则，业务可调整：

1. 用户手动选择城市 > 2.GPS 经纬度逆地理 > 3. 账号注册 / 属地信息 > 4.IP 解析地理位置 > 5. 系统默认兜底 GEO

问题点：IP 容易出错、VPN 会篡改；GPS 可能为空；弱网定位失败，必须做降级。

二、GEO 分层适配核心模型设计

1. 配置模型：地域规则表（运营后台可配置）

核心是规则 + 内容 + 生效地域 + 排除地域 + 优先级 + 生效时间，不要写死代码。

rule_id：规则唯一ID
content_id：关联要展示的内容（活动/文案/弹窗/资源）
geo_scope_type：包含模式｜排除模式
include_geo_list：生效geo编码集合（支持多层级混合：国家、省、城市）
exclude_geo_list：排除geo编码集合
priority：优先级，数字越大越优先
effective_time：生效/失效时间
status：启用/禁用
version：配置版本，用于灰度回滚

支持混合粒度：比如一条规则「全国生效，排除新疆、西藏」；另一条规则「仅上海、北京展示专属内容」。

两种匹配模式

1. 包含模式白名单：只有在 include_geo_list 内的地域命中这条内容
2. 排除模式黑名单：全国 / 大区内生效，排除部分地区

2. 用户侧 GEO 上下文模型

用户请求时，组装用户 GEO 上下文对象，传给匹配引擎：

{
  "geo_source":"gps/manual/ip/account",
  "country":"CN",
  "region":"east",
  "province":"310000",
  "city":"310100",
  "district":"310101",
  "lnglat":[121.47,31.23],
  "geo_confidence":0.8 //置信度，定位不准时降低，触发降级
}

geo_confidence置信度非常关键：GPS 高精度置信度高；IP 解析置信度低，置信度过低不使用精细规则，自动往上一层回退。

三、分层匹配逻辑（核心算法流程）

匹配原则：越细粒度规则优先级越高；同粒度看 priority 权重；匹配不到执行向上兜底

完整执行流程：

1. 获取用户 GEO 上下文获取用户当前地理位置，标记来源、置信度。如果定位完全失败，直接使用兜底默认内容。
2. 过滤有效规则集读取配置库，过滤：状态启用、在生效时间范围内的所有 GEO 适配规则。
3. 层级匹配（从细到粗尝试匹配）

优先尝试细粒度，匹配成功直接取；匹配失败向上回退上一级 GEO

• Step1：尝试区县 L4 匹配规则
• Step2：区县无命中，尝试城市 L3 匹配
• Step3：城市无命中，尝试省份 L2 匹配
• Step4：省份无命中，尝试大区 L1 匹配
• Step5：大区无命中，尝试国家 L0 匹配
• Step6：全部未命中 → 使用全局兜底默认内容

4. 排除规则校验即使命中包含列表，如果用户 GEO 落在 exclude_geo_list，则本条规则失效，继续往下匹配次优先级规则。
5. 同层级多条规则冲突处理同一地域命中多条规则：

• 取priority优先级高的一条；
• 如果业务允许多内容，按优先级排序全部返回前端，由前端做渲染取舍。

6. 置信度降级逻辑例：IP 解析得到城市，置信度只有 0.3，直接跳过城市、区县规则，只匹配省份、国家级别的粗粒度规则，避免 IP 错误导致展示错误内容。

四、兜底 & 降级策略（GEO 适配容易忽略部分）

1. 定位完全失败：无任何地理位置信息，返回全局默认内容，不展示地域专属内容。
2. 精细 GEO 无配置：向上逐层回退，城市没配置看省，省没配置看国家。
3. GEO 编码不存在（旧城市编码、行政区划变更）：自动映射到父级行政区。
4. 合规屏蔽：部分地域因为法规、业务限制，直接命中屏蔽规则，返回提示 / 默认内容。
5. 离线场景：客户端缓存上次成功解析的 GEO；新用户无缓存直接使用兜底。

五、架构分层设计（前后端分工）

后端

1. GEO 解析服务：输入 IP/GPS，输出标准化 geo 编码，返回置信度；维护行政区划字典库，处理行政区划变更。
2. 规则配置中心：运营后台配置 GEO 适配规则，存储规则，支持版本、灰度、回滚。
3. GEO 匹配引擎：输入用户 GEO 上下文，输出匹配完成的内容集合。

性能优化：规则做本地缓存，不要每次请求查 DB；热点规则预热。

前端

1. 采集定位（GPS / 用户手动选择），上报给后端；
2. 接收后端返回的适配结果，前端不要自己做复杂 GEO 匹配逻辑，只负责渲染；
3. 本地缓存用户选择的城市，弱网下使用缓存；
4. 提供手动切换城市入口，覆盖定位不准的场景。

❌反模式：前端硬编码一堆 if (city== 上海) 展示 xxx；行政区划变更后，版本无法更新，维护灾难。

六、边界问题与设计对策

1. 行政区划变更（城市合并、代码更新）

地理编码库维护新旧编码映射，旧编码自动映射新编码，规则配置层屏蔽底层编码变更。

2. VPN / 代理 IP，GEO 不准

依靠置信度，低置信度禁用精细规则；增加用户手动选择入口作为强优先。

3. 多端一致性：APP、H5、小程序

统一后端 GEO 匹配引擎，各端只传 GEO 来源，统一返回结果，避免各端逻辑不一致。

4. 数据埋点与可观测

每条返回内容带上命中的 rule_id、用户 GEO、geo_source 来源。埋点记录：

• 用户 GEO 来源是什么
• 命中哪条规则
• 是否触发兜底降级便于排查：某个地区用户看到内容不对的问题。

5. 灰度与测试

支持规则灰度：按百分比、按白名单账号测试 GEO 规则；测试环境支持强制模拟 GEO，不用真实切换 IP/GPS，可模拟任意省份城市验证适配效果。

七、简单伪代码展示匹配逻辑

def match_geo_content(user_geo, rule_list):
    # 匹配层级从细到粗
    geo_levels = [user_geo.district, user_geo.city, user_geo.province, user_geo.region, user_geo.country]
    # 过滤有效规则
    valid_rules = [r for r in rule_list if r.is_enable() and r.in_time_range()]
    # 按粒度从细到粗遍历
    for current_geo_code in geo_levels:
        hit_rules = []
        for rule in valid_rules:
            # 排除列表优先校验
            if current_geo_code in rule.exclude_geo_list:
                continue
            # 包含模式匹配
            if rule.geo_scope_type == "include" and current_geo_code in rule.include_geo_list:
                hit_rules.append(rule)
        if hit_rules:
            # 按优先级取最高
            hit_rules.sort(key=lambda x:x.priority, reverse=True)
            return hit_rules[0].content_id
    # 全部没命中，返回兜底
    return get_default_content()

八、业务落地建议

1. 地理编码统一：全系统一套行政区划编码，不要有的用中文 “上海市”、有的用 adcode 编码，统一 adcode 数字编码。
2. 尽量配置化，少写业务 if‑else，运营后台可以新增地域策略，不需要发版本。
3. 置信度机制一定要做，IP 定位错误是高频问题。
4. 必须有手动切换城市入口，给用户修正地理位置的出口。
5. 上线前覆盖测试场景：定位失败、VPN、边界城市、无配置地区，验证兜底逻辑。