# 远端覆写完全替代本地语言包方案（融合版）

> 目标：让远端语言包成为唯一数据源，本地 `lang/` 目录可以删除，且运行效果与现在一致。
> 核心思想：**前端 `lang/` 文件作为远端基础数据源，数据库覆写作为增量层，后端合并后返回统一全量 bundle；客户端只认一个接口、一种格式。**

---

## 一、为什么需要远端优先

当前方案是 **本地语言包 + 远端覆写** 的混合模式：

- 本地 `lang/zh-cn/`、`lang/en-us/` 是主数据源；
- 远端只返回 `overrides` map，用于运营 Hotfix 或多租户定制；
- 若删除本地语言包，所有 `import('lang/xx/xxx.js')` 会失败，页面直接显示空串或 raw key。

要满足“删除本地语言包后效果一致”，必须让远端承担主数据源角色，本地只做**启动首屏兜底缓存**。

---

## 二、融合架构设计

不再区分“方案 A”和“方案 B”，而是把它们合并成一条统一的远端链路：

```text
┌─────────────────────────────────────────────────────────────┐
│  前端 lang/ 目录（基础数据源）                                │
│  部署到服务端，作为默认、完整、可版本化的语言包基线           │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────┐
│  Admin 后台 / 数据库（覆写层）                                │
│  仅存储需要覆盖或新增的 key                                   │
│  支持 locale / platform / tenant 维度                         │
└─────────────────────────┬───────────────────────────────────┘
                          │  合并
┌─────────────────────────▼───────────────────────────────────┐
│  PHP 后端 API                                                │
│  /api/lang/bundle     读取 lang 文件 + 合并数据库覆写         │
│  /api/lang/diff       返回 base 版本到当前版本的差异          │
└─────────────────────────┬───────────────────────────────────┘
                          │  HTTPS / CDN
┌─────────────────────────▼───────────────────────────────────┐
│  客户端                                                      │
│  1. 启动时优先读本地 storage 缓存                             │
│  2. 异步拉取远端 bundle / diff                                │
│  3. 更新缓存并刷新全局语言上下文                              │
│  4. $lang() 只读内存中的合并语言树                            │
└─────────────────────────────────────────────────────────────┘
```

### 2.1 两层数据源

| 层级 | 来源 | 作用 | 是否必须 |
|---|---|---|---|
| Base | 服务端部署的前端 `lang/` 文件 | 提供完整默认语言包 | 必须 |
| Override | 数据库/配置文件 | 覆盖或补充特定 key | 可选，按需启用 |

### 2.2 合并规则

后端每次响应 `/api/lang/bundle` 时：

1. 读取 `lang/<locale>/` 下所有 `.js` 文件，归一化并合并成 **base tree**；
2. 从数据库读取当前 `locale + platform + tenant` 的覆写记录，展开成 **override tree**；
3. 用深度合并把 `override tree` 覆盖到 `base tree` 上；
4. 返回合并后的全量 tree。

这样：

- 没有覆写时，返回的就是前端语言包本身；
- 有覆写时，只改变被覆写的 key，其余保持前端文件内容；
- 客户端无需关心某个 key 来自文件还是数据库。

---

## 三、远端数据格式

统一返回层级树，客户端直接使用，无需展开：

```json
{
    "code": 0,
    "data": {
        "version": "1751181600",
        "locale": "zh-cn",
        "platform": "h5",
        "tenant": "default",
        "source": "merged",
        "tree": {
            "common": {
                "submit": "提交",
                "cancel": "取消"
            },
            "components": {
                "payment": {
                    "alipay": "支付宝支付",
                    "wechatpay": "微信支付"
                }
            },
            "componentsDiy": {
                "diyArticle": {
                    "viewMore": "查看更多"
                }
            },
            "order": {
                "list": {
                    "title": "我的订单",
                    "status": {
                        "waitpay": "待付款"
                    }
                }
            }
        }
    }
}
```

---

## 四、后端 API 设计

### 4.1 全量 bundle

```http
GET /api/lang/bundle?locale=zh-cn&platform=h5&tenant=default
```

响应字段：

- `version`：bundle 版本，建议用 base 文件最后修改时间或自定义版本号；
- `locale` / `platform` / `tenant`：请求维度；
- `tree`：合并后的完整语言树。

### 4.2 增量 diff

```http
GET /api/lang/diff?locale=zh-cn&platform=h5&tenant=default&from_version=120
```

返回自 `from_version` 以来的变更：

```json
{
    "code": 0,
    "data": {
        "version": "1751181600",
        "changes": {
            "common.submit": "提交",
            "order.list.title": null
        }
    }
}
```

> diff 实现可简可繁：初期可以直接返回全量 `tree` 让客户端覆盖；后期再实现 key 级 diff。

### 4.3 CDN 与缓存策略

bundle 接口应支持 CDN 缓存和客户端缓存：

- **服务端响应头**：
  - `Cache-Control: public, max-age=300`（5 分钟短缓存，保证更新及时性）；
  - `ETag: <version>`；
  - `Content-Encoding: gzip/br`（bundle 通常 50~200KB，压缩后显著减小）。
- **CDN 策略**：按 URL（含 locale / platform / tenant / version）缓存，版本变化自动失效；
- **客户端缓存**：storage 缓存 bundle，key 带 version；
- **缓存优先级**：内存 > storage > CDN > 源站。

### 4.4 安全与访问控制

- `/api/lang/bundle` 可以设为**公开接口**（语言包不涉及敏感业务数据，且 App 启动前用户可能未登录）；
- 若业务需要保护 tenant 级文案，可在请求头中携带匿名 token 或签名；
- 必须对 `locale`、`platform`、`tenant` 做白名单校验，防止路径遍历或非法查询；
- 后端永远不要信任客户端传来的 `version`，diff 接口只做幂等返回。

### 4.5 签名与完整性校验

`/api/lang/bundle` 虽可公开访问，但仍需防止 CDN 污染或中间人篡改。推荐在响应中加入签名字段：

```json
{
    "code": 0,
    "data": {
        "version": "1751181600",
        "tree": { ... },
        "sign": "sha256=xxxxxxxx"
    }
}
```

PHP 生成签名：

```php
private function sign($tree, $version, $secret)
{
    $payload = json_encode($tree, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
    return hash_hmac('sha256', $version . $payload, $secret);
}
```

客户端在收到 bundle 后校验签名，校验失败则视为异常并使用缓存或内嵌兜底。签名密钥从配置中心下发或打包时内嵌，避免硬编码在仓库。

### 4.6 版本控制策略

不建议用文件 `mtime` 作为生产版本号，原因：

- 不同服务器部署时间不一致会导致版本号不一致；
- CI/CD 并行部署时难以保证原子性。

推荐方案：

| 方案 | 实现 | 适用场景 |
|---|---|---|
| 构建生成 version 文件 | CI 打包时写入 `lang/.version`，PHP 读取该文件 | 推荐，稳定可控 |
| Git commit hash | 用当前 commit 短 hash 作为版本 | 适合 DevOps 成熟团队 |
| 内容 hash | 对合并后的 tree 做 MD5/SHA1 | 最精确，但计算成本稍高 |

示例：CI 生成 `lang/.version`

```bash
# deploy.sh
echo "$(date +%s)-$(git rev-parse --short HEAD)" > public/static/lang/.version
```

PHP 读取：

```php
private function getBundleVersion($locale)
{
    $versionFile = $this->basePath . '/' . $locale . '/.version';
    if (file_exists($versionFile)) {
        return trim(file_get_contents($versionFile));
    }
    return 'unknown';
}
```

---

## 五、构建与部署流程

### 5.1 前端构建时同步 lang 文件

在 `package.json` 中增加构建脚本：

```json
{
    "scripts": {
        "build:h5": "npm run sync:lang && uni build",
        "sync:lang": "node scripts/sync-lang-to-server.js"
    }
}
```

`scripts/sync-lang-to-server.js` 示例：

```js
const fs = require('fs');
const path = require('path');

const SRC = path.resolve(__dirname, '../lang');
const DEST = path.resolve(__dirname, '../../server/public/static/lang');

function copyDir(src, dest) {
    if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
        const srcPath = path.join(src, entry.name);
        const destPath = path.join(dest, entry.name);
        if (entry.isDirectory()) {
            copyDir(srcPath, destPath);
        } else {
            fs.copyFileSync(srcPath, destPath);
        }
    }
}

copyDir(SRC, DEST);

// 生成 version 文件
const version = `${Date.now()}-${process.env.GIT_COMMIT || 'dev'}`;
for (const locale of ['zh-cn', 'en-us']) {
    fs.writeFileSync(path.join(DEST, locale, '.version'), version);
}

console.log('lang files synced to server');
```

### 5.2 部署原子性

语言包文件必须**全量替换**，不能部分更新：

- 使用软链/目录切换：先部署到新目录 `lang.new`，再原子切换软链 `lang -> lang.new`；
- 或让 PHP 读取带版本号的目录 `lang/1751181600/`，版本变化时切换配置。

### 5.3 多环境管理

| 环境 | lang 来源 | 是否启用覆写 |
|---|---|---|
| 本地开发 | 本地 `lang/` 文件（`source: 'local'`） | 否 |
| 测试环境 | 远端 bundle（`source: 'remote-only'`） | 可启用 |
| 预发环境 | 远端 bundle | 仅内部租户覆写 |
| 生产环境 | 远端 bundle + CDN | 启用 |

---

## 六、PHP 实现示例

### 6.1 数据表设计（覆写层）

```sql
CREATE TABLE lang_overrides (
    id INT AUTO_INCREMENT PRIMARY KEY,
    locale VARCHAR(10) NOT NULL DEFAULT 'zh-cn',
    platform VARCHAR(20) NOT NULL DEFAULT '',
    tenant VARCHAR(50) NOT NULL DEFAULT '',
    namespace VARCHAR(255) NOT NULL,       -- 点分 key，如 common.submit
    value TEXT,                             -- NULL 表示删除
    is_enabled TINYINT NOT NULL DEFAULT 1,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uk_key (locale, platform, tenant, namespace)
);
```

```sql
CREATE TABLE lang_bundle_versions (
    id INT AUTO_INCREMENT PRIMARY KEY,
    locale VARCHAR(10) NOT NULL DEFAULT 'zh-cn',
    platform VARCHAR(20) NOT NULL DEFAULT '',
    tenant VARCHAR(50) NOT NULL DEFAULT '',
    version VARCHAR(64) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_version (locale, platform, tenant)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

### 6.2 Bundle 控制器

```php
<?php
class LangBundleController
{
    private $basePath;

    public function __construct()
    {
        $this->basePath = __DIR__ . '/../../public/static/lang';
    }

    /**
     * GET /api/lang/bundle?locale=zh-cn&platform=h5&tenant=default
     */
    public function bundle()
    {
        $locale = $_GET['locale'] ?? 'zh-cn';
        $platform = $_GET['platform'] ?? '';
        $tenant = $_GET['tenant'] ?? '';

        if (!in_array($locale, ['zh-cn', 'en-us'])) {
            return $this->json(['code' => 400, 'message' => 'invalid locale']);
        }

        $localePath = $this->basePath . '/' . $locale;
        if (!is_dir($localePath)) {
            return $this->json(['code' => 404, 'message' => 'locale not found']);
        }

        // 1. 读取前端 lang 文件作为 base
        $baseTree = $this->loadLangDir($localePath);

        // 2. 读取数据库覆写层
        $overrideTree = $this->loadOverrides($locale, $platform, $tenant);

        // 3. 深度合并：override 覆盖 base
        $mergedTree = $this->deepMerge($baseTree, $overrideTree);

        // 4. 按平台裁剪（可选）
        $mergedTree = $this->filterByPlatform($mergedTree, $platform);

        $this->setCacheHeaders($locale);

        return $this->json([
            'code' => 0,
            'data' => [
                'version' => $this->getBundleVersion($locale),
                'locale' => $locale,
                'platform' => $platform,
                'tenant' => $tenant,
                'source' => 'merged',
                'tree' => $mergedTree,
            ]
        ]);
    }

    private function setCacheHeaders($locale)
    {
        header('Content-Type: application/json; charset=utf-8');
        header('Cache-Control: public, max-age=300');
        header('ETag: "' . $this->getBundleVersion($locale) . '"');
    }

    /**
     * 递归读取 lang 目录，归一化命名空间
     */
    private function loadLangDir($dir)
    {
        $tree = [];
        $iterator = new RecursiveIteratorIterator(
            new RecursiveDirectoryIterator($dir)
        );

        foreach ($iterator as $file) {
            if ($file->isDir() || $file->getExtension() !== 'js') {
                continue;
            }

            $relativePath = str_replace($dir . DIRECTORY_SEPARATOR, '', $file->getPathname());
            $relativePath = str_replace('\\', '/', $relativePath);
            $relativePath = preg_replace('/\.js$/', '', $relativePath);

            // 跳过 version 文件
            if ($relativePath === '.version') continue;

            $content = file_get_contents($file->getPathname());
            $lang = $this->parseLangExport($content);
            if ($lang === null) continue;

            $namespace = $this->toNamespace($relativePath);
            $this->setNestedValue($tree, $namespace, $lang);
        }

        return $tree;
    }

    /**
     * 解析 export const lang = { ... }
     */
    private function parseLangExport($content)
    {
        if (!preg_match('/export\s+const\s+lang\s*=\s*([\s\S]*?);?\s*$/m', $content, $matches)) {
            return null;
        }
        $json = $matches[1];

        // 简单清理 JS 语法为合法 JSON
        $json = preg_replace('/([\{\,])\s*\/\/[^\n]*/', '$1', $json);
        $json = preg_replace('/\/\*[\s\S]*?\*\//', '', $json);
        $json = str_replace("'", '"', $json);
        $json = preg_replace('/,\s*([\}\]])/', '$1', $json);

        $decoded = json_decode($json, true);
        return is_array($decoded) ? $decoded : null;
    }

    private function toNamespace($relativePath)
    {
        $segments = explode('/', $relativePath);
        return array_map([$this, 'toCamelCase'], $segments);
    }

    private function toCamelCase($name)
    {
        return preg_replace_callback('/[-_]([a-z])/', function ($m) {
            return strtoupper($m[1]);
        }, $name);
    }

    private function setNestedValue(&$tree, $path, $value)
    {
        $cursor = &$tree;
        foreach ($path as $key) {
            if (!isset($cursor[$key]) || !is_array($cursor[$key])) {
                $cursor[$key] = [];
            }
            $cursor = &$cursor[$key];
        }
        $cursor = $this->deepMerge($cursor, $value);
    }

    /**
     * 从数据库读取覆写层，并展开为层级树
     */
    private function loadOverrides($locale, $platform, $tenant)
    {
        $tree = [];

        // 按优先级升序查询，后覆盖先
        $rows = DB::table('lang_overrides')
            ->where('locale', $locale)
            ->where('is_enabled', 1)
            ->where(function ($q) use ($platform, $tenant) {
                $q->where(function ($q2) { // global
                    $q2->where('tenant', '')->where('platform', '');
                })
                ->orWhere(function ($q2) use ($platform) { // platform only
                    $q2->where('tenant', '')->where('platform', $platform);
                })
                ->orWhere(function ($q2) use ($tenant) { // tenant only
                    $q2->where('tenant', $tenant)->where('platform', '');
                })
                ->orWhere(function ($q2) use ($platform, $tenant) { // tenant + platform
                    $q2->where('tenant', $tenant)->where('platform', $platform);
                });
            })
            ->orderByRaw("
                CASE
                    WHEN tenant = '' AND platform = '' THEN 1
                    WHEN tenant = '' AND platform != '' THEN 2
                    WHEN tenant != '' AND platform = '' THEN 3
                    ELSE 4
                END ASC
            ")
            ->get();

        foreach ($rows as $row) {
            $path = explode('.', $row->namespace);
            if ($row->value === null) {
                $this->deleteNestedValue($tree, $path);
            } else {
                $this->setNestedValue($tree, $path, $row->value);
            }
        }

        return $tree;
    }

    /**
     * 可选：按平台裁剪不需要的 key
     */
    private function filterByPlatform($tree, $platform)
    {
        // 示例：若某 key 仅在 mp-weixin 使用，可在此过滤
        // 当前项目暂不需要，留作扩展
        return $tree;
    }

    private function deepMerge($target, $source)
    {
        if (!is_array($target)) $target = [];
        if (!is_array($source)) return $source;

        foreach ($source as $key => $value) {
            if (isset($target[$key]) && is_array($target[$key]) && is_array($value)) {
                $target[$key] = $this->deepMerge($target[$key], $value);
            } else {
                $target[$key] = $value;
            }
        }
        return $target;
    }

    private function deleteNestedValue(&$tree, $path)
    {
        $cursor = &$tree;
        foreach ($path as $i => $key) {
            if (!isset($cursor[$key])) return;
            if ($i === count($path) - 1) {
                unset($cursor[$key]);
            } else {
                $cursor = &$cursor[$key];
            }
        }
    }

    private function getBundleVersion($locale)
    {
        $versionFile = $this->basePath . '/' . $locale . '/.version';
        if (file_exists($versionFile)) {
            return trim(file_get_contents($versionFile));
        }
        return 'unknown';
    }

    private function json($data)
    {
        echo json_encode($data);
    }
}
```

### 6.3 无数据库时的最小实现

如果暂时不需要 Admin 覆写，可以把 `loadOverrides` 直接返回空数组，整个系统仍然可用。等需要运营 Hotfix 时再启用数据库表。

### 6.4 Admin 覆写接口设计

后台对覆写层的增删改查接口：

```php
class LangOverrideController
{
    /**
     * POST /api/admin/lang/overrides
     */
    public function store()
    {
        $locale = $_POST['locale'] ?? 'zh-cn';
        $platform = $_POST['platform'] ?? '';
        $tenant = $_POST['tenant'] ?? '';
        $namespace = $_POST['namespace'] ?? '';
        $value = $_POST['value'] ?? null;

        // 白名单校验
        if (!in_array($locale, ['zh-cn', 'en-us'])) {
            return $this->json(['code' => 400, 'message' => 'invalid locale']);
        }
        if (!$this->isValidNamespace($namespace)) {
            return $this->json(['code' => 400, 'message' => 'invalid namespace']);
        }

        DB::table('lang_overrides')
            ->updateOrInsert(
                ['locale' => $locale, 'platform' => $platform, 'tenant' => $tenant, 'namespace' => $namespace],
                ['value' => $value, 'is_enabled' => 1, 'updated_at' => date('Y-m-d H:i:s')]
            );

        // 更新版本号，触发客户端更新
        $this->bumpVersion($locale, $platform, $tenant);

        return $this->json(['code' => 0, 'message' => 'ok']);
    }

    /**
     * DELETE /api/admin/lang/overrides
     */
    public function destroy()
    {
        $id = $_GET['id'] ?? 0;
        DB::table('lang_overrides')->where('id', $id)->delete();
        return $this->json(['code' => 0, 'message' => 'ok']);
    }

    /**
     * GET /api/admin/lang/overrides
     */
    public function index()
    {
        $locale = $_GET['locale'] ?? 'zh-cn';
        $platform = $_GET['platform'] ?? '';
        $tenant = $_GET['tenant'] ?? '';

        $rows = DB::table('lang_overrides')
            ->where('locale', $locale)
            ->where(function ($q) use ($platform) {
                if ($platform) $q->where('platform', $platform);
            })
            ->where(function ($q) use ($tenant) {
                if ($tenant) $q->where('tenant', $tenant);
            })
            ->orderBy('updated_at', 'desc')
            ->get();

        return $this->json(['code' => 0, 'data' => $rows]);
    }

    private function bumpVersion($locale, $platform, $tenant)
    {
        DB::table('lang_bundle_versions')
            ->updateOrInsert(
                ['locale' => $locale, 'platform' => $platform, 'tenant' => $tenant],
                ['version' => time(), 'updated_at' => date('Y-m-d H:i:s')]
            );
    }
}
```

### 6.5 diff 算法实现

`/api/lang/diff` 用于增量更新。初期可直接返回全量 tree，后期实现 key 级 diff：

```php
public function diff()
{
    $locale = $_GET['locale'] ?? 'zh-cn';
    $platform = $_GET['platform'] ?? '';
    $tenant = $_GET['tenant'] ?? '';
    $fromVersion = $_GET['from_version'] ?? '';

    // 获取当前版本
    $currentVersion = $this->getCurrentVersion($locale, $platform, $tenant);

    // 如果版本相同，返回空 diff
    if ($fromVersion === $currentVersion) {
        return $this->json(['code' => 0, 'data' => ['version' => $currentVersion, 'changes' => []]]);
    }

    // 初期：直接返回全量 tree 作为 changes
    $bundle = $this->buildBundle($locale, $platform, $tenant);
    $changes = $this->flattenTree($bundle['tree']);

    return $this->json([
        'code' => 0,
        'data' => [
            'version' => $currentVersion,
            'changes' => $changes,
        ]
    ]);
}

/**
 * 把层级树展开为点分 key map
 */
private function flattenTree($tree, $prefix = '')
{
    $result = [];
    foreach ($tree as $key => $value) {
        $path = $prefix ? $prefix . '.' . $key : $key;
        if (is_array($value)) {
            $result = array_merge($result, $this->flattenTree($value, $path));
        } else {
            $result[$path] = $value;
        }
    }
    return $result;
}

/**
 * 后期：基于版本快照实现真 diff
 */
private function diffAgainstSnapshot($locale, $platform, $tenant, $fromVersion)
{
    $oldTree = $this->loadSnapshot($locale, $platform, $tenant, $fromVersion);
    $newTree = $this->buildBundle($locale, $platform, $tenant)['tree'];

    $oldFlat = $this->flattenTree($oldTree);
    $newFlat = $this->flattenTree($newTree);

    $changes = [];
    foreach ($newFlat as $key => $value) {
        if (!isset($oldFlat[$key]) || $oldFlat[$key] !== $value) {
            $changes[$key] = $value;
        }
    }
    foreach ($oldFlat as $key => $value) {
        if (!isset($newFlat[$key])) {
            $changes[$key] = null;
        }
    }

    return $changes;
}
```

---

## 七、客户端改造方案

### 7.1 配置项扩展

```js
{
    source: 'remote', // 'local' | 'remote' | 'hybrid' | 'remote-only'
    defaultLang: 'zh-cn',
    langList: ['zh-cn', 'en-us'],

    remote: {
        bundleUrl: '/api/lang/bundle',
        diffUrl: '/api/lang/diff',       // 可选，无 diff 时走全量 bundle

        storagePrefix: 'lang_',
        bundleStorageKey: 'lang_bundle',
        versionStorageKey: 'lang_version',

        requestTimeout: 8000,
        bootTimeout: 3000,
        allowStaleCache: true,
        cacheMaxAge: 7 * 24 * 3600 * 1000,
    }
}
```

### 7.2 新增 `common/js/lang-loader.js`

```js
// common/js/lang-loader.js
import config from './config-external.js';

const STORAGE_KEYS = {
    bundle: `${config.remote.storagePrefix}bundle`,
    version: `${config.remote.storagePrefix}version`,
};

function readCache() {
    try {
        const bundleStr = uni.getStorageSync(STORAGE_KEYS.bundle);
        const version = uni.getStorageSync(STORAGE_KEYS.version);
        if (!bundleStr) return null;

        const parsed = JSON.parse(bundleStr);
        if (config.remote.cacheMaxAge && parsed.timestamp) {
            const age = Date.now() - parsed.timestamp;
            if (age > config.remote.cacheMaxAge && !config.remote.allowStaleCache) {
                return null;
            }
        }
        return { version, data: parsed.data };
    } catch (e) {
        return null;
    }
}

function writeCache(version, data) {
    try {
        uni.setStorageSync(STORAGE_KEYS.bundle, JSON.stringify({
            data,
            timestamp: Date.now(),
        }));
        uni.setStorageSync(STORAGE_KEYS.version, version);
    } catch (e) {
        console.warn('[i18n] cache write failed', e);
    }
}

async function fetchBundle(locale, platform, tenant) {
    const url = `${config.remote.bundleUrl}?locale=${locale}&platform=${platform}&tenant=${tenant}`;
    return new Promise((resolve, reject) => {
        uni.request({
            url,
            method: 'GET',
            timeout: config.remote.requestTimeout,
            success: (res) => {
                if (res.statusCode === 200 && res.data && res.data.code === 0) {
                    const payload = res.data.data;
                    resolve({
                        version: payload.version,
                        data: payload.tree,
                    });
                } else {
                    reject(new Error('bundle fetch failed'));
                }
            },
            fail: reject,
        });
    });
}

async function fetchDiff(locale, platform, tenant, fromVersion) {
    if (!config.remote.diffUrl) return null;
    const url = `${config.remote.diffUrl}?locale=${locale}&platform=${platform}&tenant=${tenant}&from_version=${fromVersion}`;
    return new Promise((resolve, reject) => {
        uni.request({
            url,
            method: 'GET',
            timeout: config.remote.requestTimeout,
            success: (res) => {
                if (res.statusCode === 200 && res.data && res.data.code === 0) {
                    resolve(res.data.data);
                } else {
                    reject(new Error('diff fetch failed'));
                }
            },
            fail: reject,
        });
    });
}

function applyDiff(tree, diff) {
    const result = JSON.parse(JSON.stringify(tree));
    for (const [key, value] of Object.entries(diff)) {
        const parts = key.split('.');
        let cursor = result;
        for (let i = 0; i < parts.length - 1; i++) {
            const part = parts[i];
            if (!cursor[part] || typeof cursor[part] !== 'object') {
                cursor[part] = {};
            }
            cursor = cursor[part];
        }
        if (value === null) {
            delete cursor[parts[parts.length - 1]];
        } else {
            cursor[parts[parts.length - 1]] = value;
        }
    }
    return result;
}

export async function loadLanguageTree(locale, platform, tenant) {
    const cache = readCache();

    if (!cache) {
        const bundle = await fetchBundle(locale, platform, tenant);
        writeCache(bundle.version, bundle.data);
        return bundle.data;
    }

    // 有缓存：先返回缓存，后台拉取更新
    fetchDiff(locale, platform, tenant, cache.version)
        .then(async (diff) => {
            if (!diff) {
                // 无 diff 接口或 diff 为空，直接拉全量 bundle 对比 version
                const bundle = await fetchBundle(locale, platform, tenant);
                if (bundle.version !== cache.version) {
                    writeCache(bundle.version, bundle.data);
                    uni.$emit('lang:updated', { locale, version: bundle.version });
                }
                return;
            }

            if (diff.changes) {
                const newTree = applyDiff(cache.data, diff.changes);
                writeCache(diff.version, newTree);
                uni.$emit('lang:updated', { locale, version: diff.version });
            }
        })
        .catch(() => {
            // 静默失败，继续使用缓存
        });

    return cache.data;
}
```

### 7.3 启动时序与首屏优化

remote-only 模式下，启动流程必须保证 `$lang()` 在首屏渲染前可用。推荐在 `App.vue` 的 `onLaunch` 中阻塞式加载 bundle：

```js
// App.vue
import { loadLanguageTree } from '@/common/js/lang-loader.js';

export default {
    onLaunch() {
        const locale = uni.getStorageSync('lang') || 'zh-cn';
        const platform = this.getPlatform();
        const tenant = this.getTenant();

        // 阻塞启动，直到 bundle 就绪
        this.$langReady = loadLanguageTree(locale, platform, tenant)
            .then(tree => {
                uni.$emit('lang:ready', { locale, tree });
            })
            .catch(err => {
                console.error('[i18n] launch bundle failed', err);
            });
    },

    onShow() {
        // 等待 bundle 就绪后再放行首屏
        return this.$langReady;
    }
};
```

页面级入口同步等待：

```js
// pages/index/index.vue
export default {
    async onLoad() {
        await getApp().$langReady;
        // 此时 $lang() 已可用
    }
};
```

**首屏时间优化**：

| 策略 | 说明 |
|---|---|
| 缓存优先启动 | 先读本地 storage 缓存并渲染，后台异步更新 |
| bundle 预加载 | 在启动页或 splash 时并行请求 bundle |
| 最小化首屏 key | 内嵌默认 bundle 仅含 TabBar / 启动页 / 错误提示，避免阻塞 |
| 请求超时控制 | `bootTimeout` 默认 3s，超时后使用缓存或兜底 |
| CDN 边缘缓存 | 5 分钟短缓存 + 版本号变化自动失效 |

### 7.4 修改 `common/js/lang.js`

在 `lang(field)` 的合并逻辑前增加 remote-only 分支：

```js
async function getMergedLang(locale, route) {
    if (langConfig.source === 'remote-only') {
        const tree = await loadLanguageTree(locale, currentPlatform, currentTenant);
        return tree;
    }

    // 原有 local / hybrid 逻辑
    const common = await import(`@/lang/${locale}/common.js`);
    const shared = await loadSharedPacks(locale);
    const page = await loadPagePack(locale, route);
    return deepMerge(common, shared, page, remoteOverrides);
}
```

### 7.5 离线降级策略

完全删除本地语言包后，必须处理以下异常场景：

| 场景 | 策略 |
|---|---|
| 有缓存且远端失败 | 继续使用缓存，记录 warning |
| 无缓存且远端失败 | 显示错误页/重试按钮，或fallback到内嵌默认 bundle |
| 远端返回非 200 | 使用缓存；无缓存则显示 loading 失败提示 |
| 远端返回空 tree | 视为异常，使用缓存或内嵌 bundle |
| 首次安装弱网 | 启动页等待 bundle，超时时提示用户 |

**内嵌默认 bundle**：

在 `common/js/lang-defaults.js` 中内嵌一份最小化的默认语言包（至少包含 TabBar、启动页、错误提示文案）：

```js
// common/js/lang-defaults.js
export const defaultBundle = {
    'zh-cn': {
        common: { loading: '加载中...', retry: '重试', networkError: '网络异常' },
        tabBar: { home: '首页', member: '我的' },
    },
    'en-us': {
        common: { loading: 'Loading...', retry: 'Retry', networkError: 'Network error' },
        tabBar: { home: 'Home', member: 'Me' },
    },
};
```

在 `loadLanguageTree` 中作为最后兜底：

```js
if (!cache) {
    try {
        const bundle = await fetchBundle(locale, platform, tenant);
        writeCache(bundle.version, bundle.data);
        return bundle.data;
    } catch (e) {
        console.error('[i18n] bundle fetch failed, fallback to embedded defaults');
        return defaultBundle[locale] || defaultBundle['zh-cn'];
    }
}
```

### 7.6 热更新与页面刷新机制

运营在 Admin 修改文案后，客户端不需要重启 App 即可生效。

**后台发布时生成版本**：

```sql
-- 发布覆写时更新 lang_bundle_versions 表
INSERT INTO lang_bundle_versions (locale, platform, tenant, version, created_at)
VALUES ('zh-cn', 'h5', 'default', UNIX_TIMESTAMP(), NOW())
ON DUPLICATE KEY UPDATE version = VALUES(version), created_at = VALUES(created_at);
```

**客户端轮询/推送更新**：

1. **定时轮询**：App 回到前台时，调用 `/api/lang/bundle` 对比 `version`；
2. **WebSocket / 长连接推送**：Admin 发布后，服务端向在线客户端推送 `lang:updated` 事件；
3. **页面刷新**：收到更新后，客户端写入缓存并触发全局事件：

```js
uni.$on('lang:updated', ({ locale, version }) => {
    // 通知当前页面刷新
    const pages = getCurrentPages();
    const current = pages[pages.length - 1];
    if (current && current.$vm && current.$vm.$forceUpdate) {
        current.$vm.$forceUpdate();
    }

    // 或全局提示用户
    uni.showToast({ title: '语言包已更新', icon: 'none' });
});
```

**强制刷新策略**：

- 对于 TabBar、导航标题等全局文案，更新后立即 `$forceUpdate`；
- 对于长列表中的静态文案，允许下一页加载时自然生效；
- 对于支付结果页等一次性页面，不强制刷新，避免用户困惑。

### 7.7 灰度发布

上线 remote-only 时，不要一次性全量切换：

1. **白名单灰度**：根据 userId / deviceId / 地区，仅对部分用户启用 `source: 'remote-only'`；
2. **版本灰度**：App 新版本先 5% 启用，观察 24 小时后再扩大；
3. **回滚开关**：后端/配置中心保留 `source` 切换能力，出问题立即切回 `local`；
4. **双写校验**：remote-only 用户同时走本地和远端，对比关键 key 是否一致并上报差异。

### 7.8 平台差异适配

不同平台的请求方式、缓存能力、包体积限制差异较大，需要分别处理。

**微信小程序**

| 差异点 | 处理方案 |
|---|---|
| 包体积限制 | bundle 不打包进小程序，启动时从远端拉取；内嵌默认 bundle 控制在 5KB 以内 |
| `uni.request` 域名 | bundle 接口域名必须加入小程序 request 合法域名 |
| `uni.getStorageSync` 容量 | 单用户 10MB 足够缓存 bundle；超出时清理旧缓存 |
| 并发限制 | `uni.request` 并发 10 条，bundle 请求优先级最高 |
| 后台切前台 | `onShow` 中检测版本，静默更新 |
| 弱网/无网 | 优先使用缓存，缓存失效时使用内嵌默认 bundle |

**H5**

| 差异点 | 处理方案 |
|---|---|
| localStorage | 同源策略下可长期缓存；注意隐身模式不可用 |
| Service Worker | 可缓存 bundle，实现离线访问 |
| CDN 跨域 | bundle 接口需配置 `Access-Control-Allow-Origin` |
| SSR/SEO | SSR 时服务端直接请求 `/api/lang/bundle` 注入 HTML，避免客户端闪烁 |
| 刷新页面 | 每次刷新重新请求 bundle，依赖 304/ETag 减少流量 |

**App**

| 差异点 | 处理方案 |
|---|---|
| 原生存储 | 优先使用 `plus.storage`，容量大且稳定 |
| 推送更新 | 可利用 uni-push 推送语言包更新通知 |
| 离线包 | 打包时内置最近一次 bundle，无网时直接使用 |

---

## 八、后台管理系统设计

后台只需管理**覆写层**，不需要管理所有 key：

### 8.1 核心功能

1. **Key 搜索与覆写**
   - 输入点分 key（如 `order.list.title`）；
   - 填写覆盖后的 value；
   - 选择生效维度（locale / platform / tenant）。

2. **从 base 导入 key**
   - 定期或手动把前端 `lang/` 文件同步到后台；
   - 后台展示所有 base key，方便运营人员选择要覆写的 key。

3. **版本与发布**
   - 每次发布生成新版本号；
   - 支持回滚到上一版本；
   - diff 接口根据版本号计算变更。

4. **多维度隔离**
   - 优先级：`tenant + platform` > `tenant` > `platform` > `global`。

### 8.2 为什么只管理覆写层

- 默认文案仍由前端 `lang/` 文件维护，开发流程不变；
- 运营只干预需要修改的 key，降低管理复杂度；
- 没有覆写时，系统零性能损耗（override tree 为空）。

---

## 九、测试与校验

### 9.1 一致性校验脚本

新增 `scripts/verify-remote-bundle.js`，对比远端 bundle 与本地合并结果：

```js
const fs = require('fs');
const path = require('path');
const http = require('http');

const BASE_URL = process.env.LANG_BUNDLE_URL || 'http://localhost/api/lang/bundle';
const LOCAL_LANG_DIR = path.resolve(__dirname, '../lang');

async function main() {
    const locales = ['zh-cn', 'en-us'];
    let hasError = false;

    for (const locale of locales) {
        const remoteTree = await fetchRemote(locale);
        const localTree = loadLocal(locale);

        const diff = compare(remoteTree, localTree);
        if (diff.length) {
            console.error(`[${locale}] 不一致 key:`, diff);
            hasError = true;
        } else {
            console.log(`[${locale}] 远端 bundle 与本地一致`);
        }
    }

    process.exit(hasError ? 1 : 0);
}

async function fetchRemote(locale) {
    return new Promise((resolve, reject) => {
        http.get(`${BASE_URL}?locale=${locale}&platform=h5`, (res) => {
            let data = '';
            res.on('data', chunk => data += chunk);
            res.on('end', () => {
                const json = JSON.parse(data);
                resolve(json.data.tree);
            });
        }).on('error', reject);
    });
}

function loadLocal(locale) {
    // 复用现有 i18n-check.js 中的本地合并逻辑
    // ...
}

function compare(a, b, path = '') {
    const diffs = [];
    // 递归比较...
    return diffs;
}

main();
```

### 9.2 CI 集成

在 CI 中增加校验步骤：

```yaml
# .github/workflows/i18n.yml
- name: Sync lang files to test server
  run: npm run sync:lang --env=test

- name: Verify remote bundle
  run: LANG_BUNDLE_URL=http://test.example.com/api/lang/bundle node scripts/verify-remote-bundle.js

- name: Run i18n check
  run: npm run i18n:check
```

### 9.3 线上巡检

定时脚本调用 `/api/lang/bundle`，检查：

- 返回码是否为 0；
- tree 是否非空；
- 关键 key（如 `common.submit`、`tabBar.home`）是否存在；
- 响应时间是否超过阈值。

### 9.4 与现有 i18n-check 的整合

项目已有 `npm run i18n:check` 脚本，用于校验 `zh-cn` 与 `en-us` 的 key 一致性。remote-only 模式下，该校验仍然有效，且可以扩展为：

1. **本地校验**：继续校验 `lang/zh-cn/` 与 `lang/en-us/` 的一致性；
2. **远端校验**：同步到服务端后，拉取 `/api/lang/bundle` 校验远端合并结果是否仍然一致；
3. **覆写层校验**：校验 `lang_overrides` 表中是否存在只覆盖了一个语言版本的 key。

扩展脚本 `scripts/verify-remote-bundle.js` 的核心逻辑：

```js
async function verifyBundleConsistency(localeA, localeB) {
    const treeA = await fetchRemote(localeA);
    const treeB = await fetchRemote(localeB);

    const flatA = flatten(treeA);
    const flatB = flatten(treeB);

    const onlyInA = Object.keys(flatA).filter(k => !(k in flatB));
    const onlyInB = Object.keys(flatB).filter(k => !(k in flatA));

    if (onlyInA.length || onlyInB.length) {
        console.error('远端 bundle 语言不一致:', { onlyInA, onlyInB });
        process.exit(1);
    }
}
```

在 CI 中增加：

```yaml
- name: Run local i18n check
  run: npm run i18n:check

- name: Verify remote bundle consistency
  run: node scripts/verify-remote-bundle.js
```

---

## 十、监控与告警

### 10.1 客户端埋点

| 事件 | 含义 | 告警条件 |
|---|---|---|
| `lang_bundle_success` | 成功拉取 bundle | — |
| `lang_bundle_fail` | 拉取失败 | 连续 N 次失败 |
| `lang_bundle_cache_hit` | 使用缓存启动 | 占比过高可能表示更新不及时 |
| `lang_bundle_duration` | bundle 请求耗时 | P99 > 2s |
| `lang_key_missing` | $lang() 返回空串 | 命中 raw key/空串 |

### 10.2 服务端监控

- `/api/lang/bundle` QPS、错误率、P99 延迟；
- CDN 命中率；
- bundle 文件大小趋势；
- override 表变更频率。

---

## 十一、迁移步骤

### 阶段 1：PHP 后端接入

1. 把前端 `lang/zh-cn/`、`lang/en-us/` 目录复制到服务端；
2. 实现 `/api/lang/bundle`，先让 `loadOverrides` 返回空数组；
3. 配置 CDN 和 gzip/br；
4. 验证返回的 tree 与本地合并结果一致。

### 阶段 2：客户端改造

1. 新增 `common/js/lang-loader.js`；
2. 修改 `common/js/lang.js`，支持 `source: 'remote-only'`；
3. App 启动流程接入 loader；
4. 内嵌默认语言兜底 bundle。

### 阶段 3：灰度验证

1. 保留本地 `lang/` 目录；
2. 配置 `source: 'remote'` 或 `hybrid`，对比 remote bundle 与本地结果；
3. 运行 `npm run i18n:check` 和 `node scripts/verify-p2-keys.js`；
4. 对白名单用户启用 `source: 'remote-only'`，观察一周；
5. 在测试环境删除本地语言包，验证功能正常。

### 阶段 4：正式上线

1. 逐步扩大 remote-only 用户比例；
2. 配置 `source: 'remote-only'` 为默认；
3. 构建脚本中移除 `lang/` 目录打包（或保留但不使用）；
4. 监控 bundle 接口成功率、首屏加载时间、缓存命中率。

### 阶段 5（可选）：启用 Admin 覆写

1. 创建 `lang_overrides` 表；
2. 实现 Admin 后台，允许运营人员覆写指定 key；
3. 验证覆写后客户端能正确展示。

---

## 十二、风险与回退

| 风险 | 影响 | 缓解措施 |
|---|---|---|
| bundle 接口挂掉 | 新用户无法进入应用 | 内嵌默认语言兜底；启用 CDN；多活部署 |
| bundle 体积过大 | 首屏慢、流量高 | 按平台裁剪；gzip/br；diff 更新 |
| 后台误改 key | 线上文案错误 | 发布前预览；版本回滚；灰度发布 |
| 缓存过期无网 | 老用户打开空白 | `allowStaleCache: true` |
| 多租户 key 冲突 | 文案串租户 | 查询时按 tenant / platform 优先级过滤 |
| 版本号不一致 | CDN/多机返回不同 bundle | 构建生成 `.version` 文件 |
| 本地开发困难 | 后端未启动时无法开发 | 本地环境 `source: 'local'` |
| CDN 缓存污染 | 用户看到旧版或被篡改文案 | 签名校验；URL 带版本号；HTTPS |
| 首屏 bundle 未就绪 | 页面先渲染后闪变 | App.vue 阻塞加载；内嵌首屏兜底 |
| 灰度配置错误 | 全量用户提前进入 remote-only | 配置中心双人复核；白名单逐步放量 |
| 覆写只改单一语言 | zh/en 文案不一致 | CI 远端一致性校验；Admin 强制双语言填写 |
| 小程序域名未配置 | 请求失败 | 上线前检查 request 合法域名 |
| storage 写满 | 缓存失败 | 捕获异常；清理旧缓存；降级内存缓存 |
| diff 接口异常 | 增量更新失败 | 回退全量 bundle；客户端自动重试 |
| 跨平台文案差异 | 某平台显示 raw key | 平台维度覆写；平台白名单校验 |

回退方案：

- 紧急情况下，客户端配置切回 `source: 'local'`，恢复使用本地 `lang/` 目录；
- 建议上线初期保留本地语言包，待 remote-only 稳定后再删除。

---

## 十三、关键结论

融合后的方案满足“删除本地语言包后效果一致”的目标：

1. **前端 `lang/` 文件作为 base**：部署到服务端，提供完整默认语言包；
2. **数据库/Admin 作为 override 层**：只管理需要覆写的 key；
3. **后端合并后返回统一 tree**：客户端只认一个接口、一种格式；
4. **构建/部署/版本/缓存/安全/监控全覆盖**：从开发到上线形成闭环；
5. **启动时序与首屏优化**：App.vue 阻塞加载 + 缓存优先，避免页面闪变；
6. **热更新与页面刷新**：Admin 发布后客户端无需重启即可生效；
7. **平台差异适配**：针对微信小程序、H5、App 分别处理缓存、域名、存储；
8. **签名与完整性校验**：防止 CDN 污染和中间人篡改；
9. **与 i18n-check 整合**：本地 + 远端双重校验，保证 zh/en 一致性；
10. **分阶段上线 + 灰度 + 回退**：降低切换风险；
11. **PHP 后端最小改动**：核心 bundle 接口几十行代码即可跑起来。