2026-04-28-multi-country-expansion-design.md 6.6 KB
外卖多国扩展需求设计文档
项目概述
将现有外卖系统扩展至泰国、菲律宾、马来西亚、印尼，不新建系统，在现有台湾外卖基础上开多语言版本，分区域点餐。台湾上架时同步开通这四个国家的下载。不同定位展示不同商家，数据不隔离。
目标国家： 台湾（已有）、泰国（TH）、菲律宾（PH）、马来西亚（MY）、印尼（ID）
1. 待确认需求
1.1 用户国家识别方式（待定）
用户打开 App 后，系统如何确定他应该看到哪个国家的商家。以下四种方案待选定：
方案 A：GPS 定位自动判断
根据用户当前 GPS 经纬度调用 Google Maps 反向地理编码，自动确定国家。
| 优点 | 缺点 |
|---|---|
| 用户零操作，体验最顺滑 | GPS 权限被拒绝时无法工作 |
| 最准确，不存在选错的问题 | 首次加载慢（要等定位 + API 返回） |
| 适合外卖场景（本身就是本地服务） | 跨境用户（边境城市）可能误判 |
| 不需要额外的 UI 入口 | 调 Google Maps API 有费用 |
方案 B：用户手动选择国家
App 首页或设置页提供国家切换入口（类似 Shopee 顶部国家标签）。
| 优点 | 缺点 |
|---|---|
| 实现最简单，不依赖 GPS 和外部 API | 用户可能选错国家，看到无关商家 |
| 响应快，无等待 | 用户换国家时需要手动操作，容易忘 |
| 完全可控 | 每个新用户都要多一步操作 |
| 适合"浏览型"场景 | 和外卖"就近点餐"的逻辑矛盾 |
方案 C：GPS 自动 + 手动切换
默认 GPS 自动判断国家，但在 App 顶部提供切换入口。
| 优点 | 缺点 |
|---|---|
| 兼顾自动和灵活 | 实现复杂度最高 |
| 覆盖 GPS 不可用的 fallback | 需要额外设计国家切换 UI |
| 支持帮异地朋友点餐等场景 | 切换后商家列表要全部刷新 |
| 用户体验最优 | 两个逻辑路径都要测试和维护 |
方案 D：注册时绑定国家
用户注册时选择所在国家，之后固定展示该国商家。
| 优点 | 缺点 |
|---|---|
| 实现简单，一次选择终身生效 | 用户搬家/换国家后很不方便 |
| 不依赖 GPS | 出差/旅游时无法使用当地外卖 |
| 数据归属清晰 | 不适合东南亚人群流动频繁的场景 |
| 注册信息即国家信息 | 修改国家可能涉及钱包余额等复杂问题 |
初步建议：方案 C，可分阶段实施（先 GPS 自动，后加手动切换）。
2. 已确认需求
2.1 核心原则
- 不新建系统 — 复用现有台湾外卖代码，多语言 + 分区域
- 数据不隔离 — 所有国家共享同一数据库
- 定位驱动商家列表 — 不同位置搜索到的商家不同
- 同步上架 — 台湾上架时同步开通 TH/PH/MY/ID 的 App 下载
2.2 当前系统现状（已确认可行）
| 能力 | 状态 | 说明 |
|---|---|---|
| 定位搜商家 | 已支持 | ST_DISTANCE() 按经纬度排序，area 字段过滤 |
| 数据不隔离 | 已支持 | 单库架构，无需改动 |
| 多语言框架 | 已支持 | 已有 zh_CN/zh_TW/en/vi 四种语言的 i18n |
| 区域点餐 | 已支持 | 商家按 area + 经纬度距离过滤 |
2.3 必须改造的模块（已确认）
| 问题 | 严重程度 | 说明 |
|---|---|---|
| 无国家/地区字段 | 高 | pos_store 需加 country 字段，商家查询加国家过滤 |
| 货币固定 VND | 高 | 需按国家配置货币（THB/PHP/MYR/IDR/TWD） |
| 支付只有 ZaloPay | 高 | 各国需对接本地主流支付方式 |
| 商家注册无国家信息 | 中 | 入驻流程需加国家选择 |
| Google Maps Key 管理 | 低 | 各国共用 Google Maps，注意 API 配额 |
3. 待讨论需求
以下问题尚未讨论，后续逐一确认：
3.1 货币与定价（已确认）
- 各国独立定价 — 同一品牌在各国使用不同商家号管理，各自独立维护菜品和价格，不存在跨国同商品定价问题
- 各商家号绑定所在国家，使用当地货币定价（TH/THB, PH/PHP, MY/MYR, ID/IDR, TW/TWD）
- 平台佣金比例是否各国不同？待确认
3.2 支付方式（待调研）
- 每个国家需要接入哪些本地支付？待调研后确定
- 泰国候选：PromptPay, TrueMoney
- 菲律宾候选：GCash, Maya
- 马来候选：Touch'n Go, FPX
- 印尼候选：GoPay, OVO
- 台湾：待确认
- 接入策略待定：每国一种 / 每国 2-3 种 / 聚合支付平台
- 钱包余额是否按国家隔离？待确认
- 跨国充值/提现如何处理？待确认
3.3 多语言（待定）
- 每个国家需要支持哪些语言？待定
- 候选方案 A：当地语言 + 英语
- 候选方案 B：中文 + 英语 + 当地语言
- 候选方案 C：各国不同，逐个确认
- 商家端的语言支持范围？待定
- 菜品名称是否需要商家自己填多语言版本？待定
3.4 商家管理（待定）
- 商家入驻审核是各国独立还是统一管理？待定
- 候选方案 A：统一后台，通过国家字段筛选区分
- 候选方案 B：各国独立管理后台
- 商家可以同时在多国营业吗？待定（已确认同一品牌用不同商家号管理）
- 各国的商家分类/标签是否统一？待定
3.5 配送与骑手（待定）
- 配送费计算规则各国是否不同？待定
- 候选方案 A：统一算法 + 各国参数配置
- 候选方案 B：各国独立规则
- 骑手是按国家分开管理还是统一？待定
- 配送范围（公里数）各国是否不同？待定
3.6 法律与合规（待定）
- 各国的税务处理（增值税/消费税）？待定
- 食品安全认证要求是否不同？待定
- 隐私政策和用户协议是否需要各国版本？待定
3.7 运营与后台（待定）
- 后台管理是否需要按国家区分权限？待定
- 各国的促销/优惠券活动是否独立？待定
- 客服系统是否按国家分开？待定
4. 技术架构
4.1 当前技术栈
- Spring Boot 3.3.5 + Java 21
- MyBatis-Plus 3.0.3 + MySQL 8.2.0
- Redis 缓存
- Google Maps API（地理编码、路线）
- ZaloPay（越南支付）
- JWT 认证
4.2 核心改造点（概要，详细方案待确认后补充）
- 商家查询 —
PosStoreMapper加country过滤 - 货币系统 — 按国家配置货币单位
- 支付网关 — 按国家路由到不同支付渠道
- 商家入驻 — 注册时绑定国家
- App 配置 — 按国家加载语言、货币、支付方式
文档状态：需求收集中，待逐项确认后完善