# 外卖多国扩展需求设计文档

## 项目概述

将现有外卖系统扩展至泰国、菲律宾、马来西亚、印尼，不新建系统，在现有台湾外卖基础上开多语言版本，分区域点餐。台湾上架时同步开通这四个国家的下载。不同定位展示不同商家，数据不隔离。

**目标国家：** 台湾（已有）、泰国（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 核心改造点（概要，详细方案待确认后补充）

1. **商家查询** — `PosStoreMapper` 加 `country` 过滤
2. **货币系统** — 按国家配置货币单位
3. **支付网关** — 按国家路由到不同支付渠道
4. **商家入驻** — 注册时绑定国家
5. **App 配置** — 按国家加载语言、货币、支付方式

---

*文档状态：需求收集中，待逐项确认后完善*