Add Nexa BaZi naming contract checker

2026-06-03 22:24:07 +08:00
parent 926acb0fe8
commit cd10c418cf
7 changed files with 515 additions and 5 deletions
@@ -0,0 +1,78 @@
+# 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 兼容。
+```