bazi_translation/references/nexa-naming-rules.md

Nexa 八字程序员命名规则

最高优先级

1. JSON/API 字段使用 snake_case。
2. 八字体系字段不得混入占星术语，除非该模块确实属于占星产品线。
3. 十神不要翻译成 deity、god、star 作为接口字段。对外字段用 ten_god，用户文案可写中文十神名。
4. favorite_element 是 Nexa 喜用元素字段；useful_god 是用神字段。两者不要互换。
5. 已上线字段必须走兼容迁移，不做无提示破坏性重命名。

推荐命名

类别	推荐	避免	说明
日主	day_master	Day_Master, dayOwner, self_lord	API/JSON 用 snake_case
日主天干	day_master_stem	DayMaster_Stem, dayMasterStem in JSON	JSON 禁止 mixed case
主导十神	dominant_ten_god	Dominant_Deity, dominant_star	十神不是 deity
喜用元素	primary_favorite_element	Primary_Favorite_Element, primary_useful_god	喜用元素不等同用神
五行强度	element_strengths	Element_Strengths, energy_strengths	明确是五行强度
大运	luck_pillar	fortune_column, big_luck	八字术语是 Luck Pillar
流年	annual_luck	flowing_year, annual_pillar	避免和本命年柱混淆
流日	daily_luck	flow_day when used as event concept	若表示干支可写 daily_stem_branch
刑冲合害	branch_relationship	astral_event	八字地支关系不是占星事件

模块 key

模块 key 是前后端契约，不是标题文案。命名要表达数据职责：

当前/候选	建议	备注
daily_overview	保留	已清晰，非术语问题
monthly_luck_tag	保留	已上线可保留
daily_luck_mantra	保留	产品文案 key，可保留
daily_fortune_insights	daily_luck_insights	新增模块建议用 luck；已上线则兼容迁移
key_astral_event	key_bazi_event 或 key_energy_event	八字首页避免 astral
home_image_module	保留或改为业务中性名	不属于术语违规

Prompt 变量

Prompt 变量也属于接口契约，不应出现临时写法：

destiny_symbols_context:
  birth_date: "1999-09-09"
  day_master_stem: "辛"
  primary_favorite_element: "金"
  secondary_favorite_element: "水"
  element_strengths:
    wood: 10
    fire: 35
    earth: 12
    metal: 22
    water: 8

不要写：

DayMaster_Stem: "辛"
Primary_Favorite_Element: "金"
Dominant_Deity: "七杀"

审查输出

输出必须具体到替换建议：

path/file.md:14 DayMaster_Stem -> day_master_stem [error]
原因：Nexa JSON/prompt contract 使用 snake_case；日主天干字段为 day_master_stem。

如果是已发布字段，输出迁移提醒：

key_astral_event -> key_bazi_event [review]
原因：八字模块不应使用 astral；若前端已依赖，先新增新 key 并保留旧 key 兼容。