# CLAUDE.md —— 给 AI 看的项目守则

> 本文件是仓库根目录给 AI 助手的强制约束文档。**做 i18n 改造前必须先读这份文件**，违反任意一条都会导致运行时崩溃或被审计拦截。

## 0 · 项目身份

- **uni-app 商城前端**（基于 Vue 2 + Webpack 5），多端编译（H5 / 微信小程序 / 鸿蒙元服务 / 支付宝 / 百度 / 头条）
- 主语言：简体中文（zh-cn），辅：en-us
- 构建入口：`main.js` + `common/js/lang.js` + `lang/<locale>.js`
- 鸿蒙 / 快应用独立工程，与根目录无代码关系，跳过

## 1 · i18n 铁律（必读 · 违反会 throw / 拦截 / 阻断）

### 1.1 唯一权威 lang 源
- **lang 包只在 `lang/en-us.js` + `lang/zh-cn.js` 两份文件里改**
- 旧的 `lang/en-us/**` 与 `lang/zh-cn/**` 281 个文件**已删除**（详见 `lang/DEPRECATED.md`，可用 `git restore` 恢复）
- 不允许重建旧的分散目录、不允许往里加 key
- 改两份文件必须**同步**：先 zh-cn，后 en-us，**两侧 key 必须一一对应**

### 1.2 命名空间强制
- 所有 key 必须以业务命名空间开头（`goods.*` / `member.*` / `order.*` 等）
- 扁平无前缀 key 一律重命名：`save` → `<namespace>.save`、`login` → `<namespace>.loginButton`
- 命名空间清单：`docs/i18n-taxonomy.md`
- 反例（禁止）：`save: '保存'` / `login: '登录'` / `title: '订单列表'`
- 正例：`common.save: '保存'` / `login.button: '登录'` / `order.list.title: '订单列表'`

### 1.3 禁止重复定义 key
- 新增前必须 `grep -r "<key>" lang/en-us.js lang/zh-cn.js`
- 已存在就**复用**，不允许再加一份
- 当前架构下没有 page module 这种"分散文件"，**物理上不可能重复**

### 1.4 运行时覆盖即 throw
- `common/js/lang.js` 的 `detectShadowing()` 在 merge 前检测 page 是否覆盖 common 已有 key，**直接 throw 阻断**
- 当前架构下 page 永远是空对象 `{}`，detectShadowing 仅作防御保留
- 任何 i18n 改造如果触发 throw，必须**改 key 名字**而不是覆盖
- 这是 hard rule，dev/prod 一视同仁

### 1.5 其他铁律
1. 禁止在一次 commit 里"先加 i18n 再回退硬编码"
2. 禁止改 CSS / 模板结构 / 与本次任务无关的代码
3. 禁止改写业务文案语义——diff 里"原值→新值"的语义变化必须 commit message 列"语义变更"段
4. 禁止把 `'+ '{{ $lang(...) }}'` 这种字面模板写到 JS 字符串里（运行时会显示字面）
5. 提交前必须跑 `python scripts/i18n_check.py`，全过才允许 commit
6. en-us 端禁止把 `Waitpay`/`Waitsend` 这种首字母大写英文单词当翻译——必须给完整短语如 `Pending Payment`

## 2 · 改动 i18n 时的标准流程

```
1. 读 docs/i18n-taxonomy.md 确认 key 归属命名空间
2. grep "<新 key>" lang/en-us.js lang/zh-cn.js 确认无重复
3. 同步改 lang/en-us.js 与 lang/zh-cn.js（同 key 同结构）
4. 调用侧改 $lang('oldKey') 为 $lang('newKey')
5. 跑 python scripts/i18n_check.py 验证（基础+严格+覆盖 三项全过）
6. commit
```

## 3 · 命名空间快速参考

| 前缀 | 归属 |
|------|------|
| `common.*` | 全站通用 |
| `tabBar.*` / `customer.*` | tabBar / 客服 |
| `goods.*` / `cart.*` / `order.*` / `pay.*` | 商品 / 购物车 / 订单 / 支付 |
| `member.*` | 个人中心 |
| `coupon.*` / `point.*` / `hongbao.*` | 营销资产 |
| `fenxiao.*` / `merch.*` | 分销 / 商家后台 |
| `login.*` / `register.*` / `find.*` | 登录 / 注册 / 找回密码 |
| `article.*` / `topics.*` / `notice.*` / `help.*` | 内容 |
| `chat.*` / `ai_chat.*` | 客服 / AI |
| `verification.*` / `recharge.*` / `diy.*` | 验证码 / 充值 / DIY |
| `bargain.*` / `pintuan.*` / `groupbuy.*` / `seckill.*` / `combo.*` / `presale.*` / `bale.*` | 营销活动 |

完整清单见 `docs/i18n-taxonomy.md`。

## 4 · 占位符语法（唯一支持）

- 位置风格：`{0}`、`{1}`、`{2}`
- 例：`discountDesc: '专享{0}折'` → 调用 `$lang('discountDesc', '9')` 得 `'专享9折'`
- 命名风格 `{name}` **不支持**
- `%s`/`%d` **不支持**

## 5 · 检测 / 校验命令

```bash
# 一键跑全部审计（基础 + 严格 + 覆盖）
python scripts/i18n_check.py

# Windows 等价入口
scripts\i18n_check.bat

# bash 等价入口
./scripts/i18n_check.sh

# 子命令
python scripts/i18n_check.py basic    # 只跑 i18n_audit.py
python scripts/i18n_check.py strict   # 只跑 i18n_strict_audit.py
python scripts/i18n_check.py shadow   # 只跑 i18n_class_c.py

# 应用调用侧改写（先用 dry-run 看 scope）
python scripts/i18n_rewrite_calls.py          # dry-run，不改文件
python scripts/i18n_rewrite_calls.py --apply  # 真正改写

# 清理死 key
python scripts/i18n_clean_dead.py             # dry-run
python scripts/i18n_clean_dead.py --apply     # 真删
```

等价 npm scripts（package.json 里也定义了）：
```bash
npm run i18n:check      # 等价 python scripts/i18n_check.py
npm run i18n:audit      # 等价 python scripts/i18n_audit.py
npm run i18n:strict     # 等价 python scripts/i18n_check.py strict
npm run i18n:apply      # 等价 python scripts/i18n_rewrite_calls.py --apply
npm run i18n:merge      # 等价 python scripts/i18n_merge.py
npm run i18n:clean-dead # 等价 python scripts/i18n_clean_dead.py --apply
```

## 6 · 历史教训（避免再犯）

| commit | 错误类型 | 教训 |
|--------|----------|------|
| f258987 | 把前 9 个 commit 的 i18n 一刀切删掉 | "先加 i18n 再全删"是白做 |
| 750ed2d | `customerService.noServiceOffline` + `common.noCustomerService` 同义不同 key | 同义 key 必须合并 |
| 47098bd | `saveSuccess` / `yuan` / `searchResultCount` 在 common/member/article 三处定义 | 同 key 三处重复=后续无法判断权威 |
| cb81aad | `level.vue:221` 写出 `+ '{{ $lang(...) }}'` 字面字符串 | JS 字符串里 `{{ }}` 不执行 |
| e9483e2 | 删除 `lang/zh-cn/agreement/contenr.js` 没确认是否被引用 | 删除文件前先 grep 引用 |
| b30ba91 | `this.$lang('order.noOrderInfo')` 但同 commit 没添加 key | 先加 key 再改调用点 |

完整复盘见 `docs/i18n-rules.md` 与各 `docs/i18n-*-audit.json`。

## 7 · 运行时的硬卡点

| 卡点 | 行为 |
|------|------|
| `common/js/lang.js#detectShadowing` | page 覆盖 common → throw（防御性保留，新架构下不会触发） |
| `python scripts/i18n_check.py` | 跑全部审计，发现问题输出 docs/i18n-*-audit.json |
| `vue.config.js#I18nGuardPlugin` | 生产构建 → 跑 class_c 审计 + 失败阻断（可 `SKIP_I18N_GUARD=1` 紧急绕过） |

## 8 · 不要做的事（清单）

- ❌ 不要重建 `lang/en-us/` 或 `lang/zh-cn/` 分散目录
- ❌ 不要在 `*.vue` 里写 `'login'` 这种无前缀扁平 key（写成 `common.login` / `login.button`）
- ❌ 不要在 `main.js` / `common/js/lang.js` 里加新逻辑绕过 throw
- ❌ 不要删 `lang/DEPRECATED.md` 或 `lang/_migration-map.json`
- ❌ 不要在生产构建里设 `SKIP_I18N_GUARD=1`（除非紧急）