zfusx
71 lines
4.1 KiB
Markdown
71 lines
4.1 KiB
Markdown
# Nexa 八字命名契约
|
|
|
|
本文件是 Nexa 八字系统的程序员命名契约。目标不是翻译给用户看，而是让 API、JSON、prompt 变量、模块 key、测试数据和文档中的八字命理词汇保持一致。
|
|
|
|
## 适用范围
|
|
|
|
- Provider / BFF / frontend API 字段。
|
|
- JSON schema、测试 fixture、调试数据。
|
|
- Prompt 变量、Context Vault、fallback schema。
|
|
- 模块 key、SSE path、registry key。
|
|
- 代码中的函数、变量、类名和枚举名。
|
|
|
|
## 分层原则
|
|
|
|
| 层级 | 命名风格 | 示例 | 说明 |
|
|
|---|---|---|---|
|
|
| API / JSON 字段 | `snake_case` | `day_master`, `ten_god_label` | 对外和跨语言最稳定 |
|
|
| 模块 key / registry key | `snake_case` | `daily_overview`, `monthly_luck_tag` | 已发布 key 需要迁移策略 |
|
|
| Python 字段/变量 | `snake_case` | `day_master_stem` | 跟 Python 社区一致 |
|
|
| JS/TS 局部变量 | `camelCase` | `dayMasterStem` | 仅限局部代码，不用于 JSON contract |
|
|
| Type / Class / Enum | `PascalCase` | `HeavenlyStem`, `EarthlyBranch`, `TenGod` | 类型名 |
|
|
| UI 中文 | 简体中文 | `日主`, `十神`, `流日` | 面向用户 |
|
|
| 英文显示名 | 标准术语 | `Day Master`, `Ten Gods`, `Annual Luck` | 面向英文 UI/文档 |
|
|
|
|
## Nexa 推荐字段
|
|
|
|
| 中文概念 | 推荐 API/JSON 字段 | Type/Enum | 说明 |
|
|
|---|---|---|---|
|
|
| 八字命盘 | `bazi_chart` | `BaziChart` | 完整排盘结构 |
|
|
| 四柱 | `pillars` | `Pillars` | 包含 year/month/day/hour |
|
|
| 年柱 | `year_pillar` | `Pillar` | 不要写 `year_column` |
|
|
| 月柱 | `month_pillar` | `Pillar` | 不要写 `month_column` |
|
|
| 日柱 | `day_pillar` | `Pillar` | 不要写 `day_column` |
|
|
| 时柱 | `hour_pillar` | `Pillar` | 不要写 `time_column` |
|
|
| 日主 | `day_master` | `DayMaster` | 可表示完整日主，如 `辛金` |
|
|
| 日主天干 | `day_master_stem` | `HeavenlyStem` | 只表示天干，如 `辛` |
|
|
| 天干 | `heavenly_stem` | `HeavenlyStem` | JSON 字段用 snake_case |
|
|
| 地支 | `earthly_branch` | `EarthlyBranch` | JSON 字段用 snake_case |
|
|
| 藏干 | `hidden_stems` | `HiddenStem` | list 字段用复数 |
|
|
| 十神 | `ten_god` | `TenGod` | 单个十神 |
|
|
| 十神 ID | `ten_god_label` | `TenGodLabel` | 若已上线为数字 ID，可保留但要写清映射 |
|
|
| 主导十神 | `dominant_ten_god` | `TenGod` | 不要写 `dominant_deity` |
|
|
| 五行 | `element` / `five_elements` | `FiveElement` | 单个用 `element`，集合用 `five_elements` |
|
|
| 五行强度 | `element_strengths` | `ElementStrengths` | map: wood/fire/earth/metal/water |
|
|
| 喜用元素 | `favorite_element` | `FiveElement` | Nexa 内部可用 favorite；若对齐通用词表可映射为 favorable |
|
|
| 第一喜用元素 | `primary_favorite_element` | `FiveElement` | 不要写 `Primary_Favorite_Element` |
|
|
| 第二喜用元素 | `secondary_favorite_element` | `FiveElement` | 不要写 `Secondary_Favorite_Element` |
|
|
| 用神 | `useful_god` | `UsefulGod` | 高阶概念，不等同喜用元素 |
|
|
| 大运 | `luck_pillar` | `LuckPillar` | 十年运柱 |
|
|
| 流年 | `annual_luck` | `AnnualLuck` | 避免和本命年柱混淆 |
|
|
| 流月 | `monthly_luck` | `MonthlyLuck` | 月运 |
|
|
| 流日 | `daily_luck` | `DailyLuck` | 日运 |
|
|
| 流日干支 | `flow_day_ganzhi` | `StemBranch` | 若已上线可保留；新字段建议 `daily_stem_branch` |
|
|
| 合冲刑害破 | `branch_relationship` | `BranchRelationship` | 不要混用 astrology/astral 命名 |
|
|
| 合盘 | `bazi_synastry` | `BaziSynastry` | 与占星 synastry 区分时加 `bazi_` 前缀 |
|
|
|
|
## 已发布字段处理
|
|
|
|
已发布 API 或前端依赖字段不能无迁移直接改名。处理顺序：
|
|
|
|
1. 标记为 `compat`：旧字段继续读取。
|
|
2. 新增推荐字段：例如同时返回 `day_master_stem`。
|
|
3. 在文档中声明旧字段 deprecated。
|
|
4. 前端/BFF 迁移完成后，再删除旧字段。
|
|
|
|
审查时不要只说“改名”。要说明影响面：API、fixture、prompt、前端 path、SSE key、数据库列、测试断言。
|
|
|
|
## 不做向量判断
|
|
|
|
本契约用于程序员纠错，必须可重复、可解释、可进入 CI。不要用向量相似度决定字段是否违规。向量搜索最多用于发现候选混名，最终仍必须落回本契约或 `nexa-forbidden-names.md`。
|