# 八字代码命名规则

## 总原则

- 简体中文是概念主键；英文显示名和代码名是派生字段。
- 用户可见文本优先用 `terms.md` 的 `标准英文`，例如 `Favourable Element`。
- 代码 identifier 优先用 `terms.md` 的 `代码名`，例如 `favorableElement`。
- 项目内已有统一拼写时先保持一致；没有统一拼写时，代码默认美式 spelling，显示文本可保留书中英式 spelling。
- 类型名用 PascalCase：`HeavenlyStem`、`EarthlyBranch`、`FiveElement`。
- 变量、字段、函数用 camelCase：`dayMaster`、`luckPillar`、`getDayMaster()`。
- 枚举值建议用稳定拼音或大写常量：`jia`/`JIA`、`zi`/`ZI`，避免把 enum value 写成解释句。

## 高风险混淆

| 中文 | 正确用法 | 避免 | 原因 |
|---|---|---|---|
| 日主 | `dayMaster` | `dayOwner`, `dayLord`, `sunOwner` | 八字固定术语是 Day Master |
| 天干 | `heavenlyStem` | `skyStem`, `celestialTrunk` | Heavenly Stem 是标准术语 |
| 地支 | `earthlyBranch` | `groundBranch`, `terrestrialBranch` | Earthly Branch 是标准术语 |
| 大运 | `luckPillar` | `fortuneColumn`, `bigLuck` | 书中使用 Luck Pillar |
| 用神 | `usefulGod` | `useGod` | Useful God 是术语，不是动词短语 |
| 有利元素 | `favorableElement` | `luckyElement`, `goodElement` | 表示平衡元素，不只是好运元素 |
| 冲 | `clash` | `crash`, `rush` | `crash` 在程序里会误读为崩溃 |
| 金 | `metal` | `gold` | 五行金通常是 Metal，不是黄金 |
| 阴阳 | `yin`/`yang` 或 `polarity` | `negative`/`positive` | 阴阳不是正负数 |

## Review 流程

1. 先找项目中已有的 BaZi 词汇：`bazi`、`stem`、`branch`、`pillar`、`luck`、`god`、`wealth`、`resource`、`officer`。
2. 对照 `terms.md` 的 `代码名`，列出不一致项。
3. 优先修正公共 API、数据库字段、模型属性、文件名和 UI label。
4. 如果发现一个中文概念有多个英文名，选择一个保留，其余写迁移说明。
5. 如果发现英文名可能对应多个中文概念，不要直接重命名；先补 `pending-terms.md`。

## 输出格式

命名 review 应该直接给替换建议：

```text
path/to/file.ts:42 dayOwner -> dayMaster
原因：日主的标准术语是 Day Master，代码名为 dayMaster。
```

需要批量改名时，先列影响面：

```text
dayOwner appears in API response fields and tests; rename requires migration.
skyStem appears only in local variables; safe to replace with heavenlyStem.
```

## 可接受的项目差异

- 如果项目已经全部使用 `favourableElement`，可以保持英式拼写，但不要和 `favorableElement` 混用。
- 如果 enum 已经使用中文字符值，例如 `stem: "甲"`，可以保留；代码侧仍应把类型命名为 `HeavenlyStem`。
- 如果 UI 面向中文用户，label 可以用中文，但代码仍应使用 approved code name。
- 如果系统同时支持紫微斗数，不要复用 BaZi 的 `chart`、`pillar`、`star` 类型名，避免跨体系污染。

## 什么时候不要自动改

- `用神`、`喜神`、`忌神` 在不同流派和层级中含义可能不同。
- `透干`、`通根`、`合化` 牵涉具体算法定义。
- `空亡`、`神煞`、`格局` 类术语需要先确认项目采用的体系。
- 已发布 API、数据库列、序列化字段需要兼容策略，不应只改源代码 identifier。