# 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 变量也属于接口契约，不应出现临时写法：

```yaml
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
```

不要写：

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

## 审查输出

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

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

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

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