docs: 删除过时的CLAUDE.md文档
该文件是给AI助手的项目守则，当前仓库已不再需要该约束文档，移除该文件以清理仓库冗余内容
This commit is contained in:
145
CLAUDE.md
145
CLAUDE.md
@@ -1,145 +0,0 @@
|
||||
# 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`（除非紧急）
|
||||
Reference in New Issue
Block a user