bazi_translation/references/naming-rules.md

八字代码命名规则

总原则

• 简体中文是概念主键；英文显示名和代码名是派生字段。
• 用户可见文本优先用 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 应该直接给替换建议：

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

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

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。