多地区 · 多语言架构设计

提案的核心方向正确且符合业界标准做法（路径前缀隔离地区 + 共享 BFF）：

需在提案基础上补全一个维度：地区（region）与语言（lang）是两个正交维度，必须显式拆开——

一句话：地区决定「有哪些页、长什么样」，语言只决定「同一张页上显示什么文字」。

URL 结构：/{region}/{lang}/{page}

路由规则表

地区切换：页头 / 页尾的「國家選項」2026-07-27 增补

geoip 只是落地猜测，访客必须能自己改。因此在页头（语言按钮左侧）与页尾各放一个国家选项，与语言切换器同构：选择进 URL，由服务端按路径重新渲染，可缓存、可分享、利于 hreflang。

• 清单来自注册表：/config.js 下发 regions（regionList()），切换器据此渲染；站点名走 i18n 键 region_{code}（缺键回落注册表 name）。新增地区仍只改 regions.js 一处，页面与切换器代码不动。
• 换站映射：语言沿用当前，目标站不支持则用其默认语言（/jp/ja/x → 香港站取 zh-HK）；页面同名平移，目标站没有的页面回落（plans-plus → plans，pay-return → 首页）；不带查询串 / hash —— 换国家是换上下文，另一个站读不懂本站参数。
• 挂载方式：由 _shared/js/main.js 在地区页运行时注入到 .nav-inner 与 footer .footer-inner，不逐页改 HTML（plans-plus 这类不再由生成器管理的页面同样自动获得）。
• 选择不持久化：状态只在 URL 里，裸域访问仍走 geoip。如需「记住上次选的国家」，另加 cookie 层。

为什么「地区在前、语言显式成段」

public/
├── _shared/                 # 跨地区共享（唯一真源）
│   ├── css/                 # 基础样式（reset / 变量 / 公共组件）
│   ├── js/
│   │   ├── i18n.js          # i18n 引擎（读地区字典 + 渲 data-i18n）
│   │   ├── api.js           # BFF 客户端（自动带 region/lang）
│   │   └── main.js          # 公共交互
│   ├── img/                 # 公共图片（logo 等）
│   └── i18n/en.js …         # 跨地区共享文案（nav/footer/cookie）
│
├── jp/                      # ── 日本地区：独立页面 + 排版 ──
│   ├── pages/               # index / plans / … 页数、页种可不同
│   ├── css/  img/           # 地区专属覆盖（可选）
│   └── i18n/
│       ├── ja.js            # 日文文案
│       └── en.js            # 日本站的英文
│
├── hk/                      # ── 香港地区 ──
│   ├── pages/               # 可以多几张页
│   ├── css/  img/
│   └── i18n/
│       ├── zh-HK.js         # 繁中文案
│       └── en.js
│
├── global/                  # ── 其他國家（纯英文，无在线订阅）──
│   ├── pages/               # 不含 plans-plus / pay-return
│   └── i18n/en.js
│
└── (新增地区照抄一个目录即可，零特判)

• 一个地区 = 一个自包含目录：页面、专属样式、专属图片、i18n 字典都在里面 →「不同排版/页数」天然成立。
• 共享的抽到 _shared/：i18n 引擎、BFF 客户端、公共样式/图片只维护一份。
• 语言不建目录、用字典：仅当某地区某语言排版确实要分叉时，才在该地区目录内加语言变体页（局部特例）。

关键：「地区+语言」解析是一个中间件，而非为每地区/每页写特判。新增地区 = 加一个目录 + 注册表加一行。

沿用现有「运行时按 data-i18n 换字符串」的机制（改造成本低），但把字典按地区拆分：

• 共享文案（导航/页脚/Cookie）→ _shared/i18n/{lang}.js
• 地区专属文案 → public/{region}/i18n/{lang}.js
• 页面加载：先加载共享字典，再加载地区字典（地区覆盖共享），由 _shared/js/i18n.js 统一渲染。

好处：各地区文案独立演进，互不影响；单文件体积可控（不再是 2185 行巨无霸）；语言切换仍是纯前端行为，无需为每语言生成一套 HTML。

BFF（routes/* + services/*）保持单一共享，通过「地区上下文」做数据差异化，而非每地区一套后端逻辑。

• 上下文传递：前端 api.js 每个 /api/* 请求自动带地区标识（推荐请求头 X-Region: hk / X-Lang: en，取自 __APP_CONFIG__）；/api/* 前缀保持全局。
• 服务端读取：轻量中间件把 X-Region 解析进 req.region，交给下游。
• 按地区变化的数据：国家/币种/合规文案（countries/industries）、Plans/Editions 目录（plans/editions）、上游代理可按地区选不同 API_BASE_URL/租户。
• 在线支付方式：各地区接入不同网关/支付方式（日本 PayPay·Konbini·JCB / 香港 FPS·AlipayHK·信用卡）—— 作为重点单列 §07。
• 不变的部分：鉴权、代理框架、mock 框架、错误处理 —— 全部复用。

即提案所说「BFF 层都是一样的」——成立。差异只体现在「同一套代码根据 region 返回不同数据」。

不同国家/地区接入不同的在线支付方式，这是「地区上下文」的又一维（与币种、Plans 目录同类），不新增架构维度 —— 用同一套共享 BFF + 适配器（Strategy 模式）承载即可。

各地区声明自己的币种与支付方式

写进 region 注册表：region → { …, currency, paymentMethods: [...] }，与 availableLangs 同理。前端从 /config.js 或 GET /api/payments/methods 拿到当前地区可用方式，渲染收银台。

BFF 统一门面（网关无关），内部按 (region, method) 选适配器

• 适配器模式：server/services/payments/ 一网关一文件（stripe / alipay-hk / payjp-konbini / fps …），实现统一接口 createPayment · verifyWebhook · getStatus；注册表映射 region → [providers]、providerCode → adapter。
• 新增支付方式 = 加一个适配器 + 注册表登记，不改前端、不改下单流程。
• 归一化支付记录：沿用现有 mock 已定义的形状（paymentId / orderId / amount / currency / status / events 时间线），各适配器把第三方回调翻译成这个形状。
• 前端去硬编码：pay-gateway.js / pay-return.js 里的 HK$ / PayPartner / zh-HK 改为读地区 currency + 方式元数据；收银台按 paymentMethods 渲染。
• 回调与地区解耦：webhook 是服务端到服务端，路径按 :provider 与地区无关，通过 paymentId 反查地区/订单；用户可见的返回页地区化：/{region}/{lang}/pay-return。
• 线上/线下并存：保留现有 subscribe-offline（联络我们/推荐人），作为暂无在线支付地区的兜底通道。

要点：下单流程（subscribe）与前端收银台保持不变，具体网关全部收敛到适配器背后 —— 加国家、换支付方式都不动主干。

在现有 window.__APP_CONFIG__ 基础上补充地区/语言上下文，让前端 JS 无需自己解析 URL：

window.__APP_CONFIG__ = {
  appEnv, apiPrefix, apiBaseUrl, mock,       // 现有
  region: "hk",                      // 当前地区（路径解析得出）
  lang: "en",                        // 当前语言
  defaultLang: "zh-HK",               // 该地区默认语言
  availableLangs: ["zh-HK", "en"],    // 语言切换器用
  currency: "HKD",                    // 该地区币种（§07）
  paymentMethods: ["fps", "alipay_hk", "card"], // 该地区可用支付方式（§07）
  subscription: true,                 // 该地区是否有在线订阅（决定 Plans 入口给哪张页）
  regions: [{ code, name, defaultLang, availableLangs, subscription }, …], // 全部站点，国家选项用（§02）
  markets: { HKG: {…}, JPN: {…} },      // 市场码 → 站点，跨站续费/加购用
  geo: { country, lang, … }             // 现有 geoip 结果（裸域落地判断）
}

• /config.js 保持 no-store，按请求路径注入正确的 region/lang。
• 语言切换器读 availableLangs 渲染，切换即跳到 /{region}/{targetLang}/{samePage}。
• 国家选项读 regions 渲染，切换即跳到 /{targetRegion}/{lang}/{samePage}（见 §02）。

分阶段推进，每步可独立上线、可回滚：

1. 抽公共层：新建 public/_shared/，迁入公共 css/js/img、i18n 引擎、api.js；页面引用改 /_shared/…。
2. 建 HK 基线地区：现有扁平页面复制进 public/hk/pages/ 作为基线（Q3/Q4），验证 region 中间件。
3. 拆 i18n：translations.js 按「共享 / 地区」拆分，tc→zh-HK、jp→ja 做别名。
4. 接入 region 中间件：实现 /{region}/{lang} 解析 + 裸地区/裸域重定向；同时移除 /plans-jp 与 /plans 的日本特判。
5. 克隆日本地区：public/jp/，落地日文排版与 ja.js/en.js。
6. BFF 引入地区上下文：X-Region 中间件 + 让 countries/industries/plans 等按地区返回。
7. 收尾：旧扁平 URL（如 /plans）301 到默认地区，保留一段时间兼容外链。
8. 补建 global 站 + 国家选项（2026-07-27，Q1/Q3 修订）：regions.js 加 global 一行 → 重跑 build-regions.js（生成 public/global/pages）+ split-i18n.js（生成 global/i18n/en.js）；裸域兜底改 global；main.js 注入页头/页尾国家选项。

• SEO：每个 {region}/{lang} 是独立可索引 URL；<head> 加 <link rel="alternate" hreflang> 串联各语言并设 x-default。
• 缓存/CDN：地区+语言进 URL → 天然可按路径缓存，不被 Cookie/geoip 打碎缓存键。
• 重定向语义：裸域 / 与裸地区 /{region} 用 302（临时/个性化）；旧扁平 URL 收敛用 301。
• 可扩展性：新增地区 = 加一个 public/{region}/ 目录 + 注册表一行，无需改路由代码。

Q1–Q5 已拍板并回填到上文相关章节；Q6–Q7 待后续确认。Q1 与 Q3 已于 2026-07-27 因「页头/页尾国家选项」需求修订——原决策保留在下方以便追溯。