From fbf2dfdceed360bc3ab393fb1d3afc81d783ca08 Mon Sep 17 00:00:00 2001 From: ZF sun <34314687@qq.com> Date: Wed, 1 Jul 2026 18:00:28 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=88=A0=E9=99=A4=E8=BF=87=E6=97=B6?= =?UTF-8?q?=E7=9A=84CLAUDE.md=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 该文件是给AI助手的项目守则，当前仓库已不再需要该约束文档，移除该文件以清理仓库冗余内容 --- CLAUDE.md | 145 ------------------------------------------------------ 1 file changed, 145 deletions(-) delete mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 364b2ad..0000000 --- a/CLAUDE.md +++ /dev/null @@ -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/.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` → `.save`、`login` → `.loginButton` -- 命名空间清单：`docs/i18n-taxonomy.md` -- 反例（禁止）：`save: '保存'` / `login: '登录'` / `title: '订单列表'` -- 正例：`common.save: '保存'` / `login.button: '登录'` / `order.list.title: '订单列表'` - -### 1.3 禁止重复定义 key -- 新增前必须 `grep -r "" 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`（除非紧急） \ No newline at end of file