bazi_translation/references/nexa-bazi-contract.md

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。