xuanzhi-service/server/.ai-specs/sys-specs/business-dictionary-spec.md

业务字典规范

适用范围

• 当任务是新增业务状态、类型、级别、来源、模式、分类等值域时，先读本文件。
• 本文件规定业务字典怎么写，统一分为 固定值域字典 和 动态值域字典 两类；不重复说明系统字典底层实现细节。

强制规则

• 业务字典是值域定义来源；禁止在代码中脱离字典单独发明枚举值域。
• 新增业务值域时，先写字典文档，再写表结构、接口、校验和前端展示。
• 具体业务字典必须写到 .ai-specs/doc-dict/ 下。
• 新增/修改业务字典时，必须同步维护初始化数据和当前版本升级 SQL；初始化数据覆盖新库，升级 SQL 覆盖老库。
• 一个 .md 文件只能写一个字典。
• 字典文件名必须等于字典编码，推荐路径：.ai-specs/doc-dict/<dict-code>.md。
• 字典编码使用 snake_case，固定格式 <module>_<field>，例如 device_status。
• <dict-code> 就是 <module>_<field>。
• 字典只分两类：固定值域字典 和 动态值域字典。
• 固定值域字典：当前业务已确认值域，字典项必须在文档中完整定义，并与代码枚举、接口校验、默认值、状态流转和展示映射保持同步。
• 动态值域字典：当前业务不固化值域，必须保留对应 .md 文档，但文档只说明字典编码、类型、来源、业务用途和逻辑边界，不要求在业务文档里枚举全部值项。
• 固定值域字典 通常需要同步代码枚举或常量定义；动态值域字典 默认不新增固定枚举常量。
• 固定值域字典 的字典项 Value 使用稳定 machine value；代码常量值必须与字典项 Value 完全一致。
• 代码判断统一使用 固定值域字典 的字典项 Value；禁止使用 Label 做逻辑分支。
• 固定值域字典 必须同步写入 source/system 初始化数据和 .ai-transition/database-upgrade-doc/<version>.sql 的 sys_dictionaries、sys_dictionary_details 数据。
• 动态值域字典 必须同步写入 source/system 初始化数据和 .ai-transition/database-upgrade-doc/<version>.sql 的 sys_dictionaries 主字典；默认不写固定字典项。
• 动态值域字典 禁止为了占位在文档或代码中伪造临时 Value、伪造枚举常量或伪造默认值。
• 已上线 固定值域字典 的编码和字典项 Value 默认不可变；下线优先禁用，不直接删除。
• 动态值域字典 如果后续参与默认值、状态流转、业务分支、稳定接口 contract 或展示映射，必须升级为 固定值域字典 并补齐字典项定义。
• 禁止出现数据库存 1/2/3，但没有对应字典文档说明语义。
• 禁止代码新增枚举值，但未同步字典文档和字典数据。

MD 模板

.ai-specs/doc-dict/.md 固定值域字典模板：

# <字典中文名>

- 模块：<module>
- 字典编码：`<module>_<field>`
- 字典类型：`固定值域字典`

| Label | Value | Sort | Status | Desc |
|:---|:---|:---|:---|:---|
| <中文名> | `<machine_value>` | 10 | true | <说明> |

动态值域字典模板：

# <字典中文名>

- 模块：<module>
- 字典编码：`<module>_<field>`
- 字典类型：`动态值域字典`
- 数据来源：`系统字典`
- 业务用途：<筛选 / 展示 / 聚合 / 其他>
- 逻辑约束：<不参与业务状态流转、默认值判断和分支逻辑等约束>

代码模板

固定值域字典代码模板：

package <module>

type <TypeName> string

const (
	<TypeName><Item1> <TypeName> = "<value_1>"
	<TypeName><Item2> <TypeName> = "<value_2>"
)

• 动态值域字典 默认不在业务代码里新增固定枚举常量；如需独立封装，优先封装查询、存在性校验和展示转换入口。

与 SQL 的关系

• 固定值域字典 字段先有值项定义，再进入表设计。
• 动态值域字典 字段先有字典说明文档，再进入表设计。
• 动态值域字典 字段进入 doc-sql 时，只记录字典编码、是否必填、索引和通用结构约束；禁止伪造固定值项、伪造默认值或伪造 CHECK IN (...)。
• 值域字段如何落库，按 .ai-specs/sys-specs/business-table-spec.md 执行。
• 字典数据升级 SQL 按 .ai-specs/sys-specs/database-upgrade-doc-spec.md 执行，必须考虑重复执行、人工已建数据和部分明细缺失。