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

业务字典规范

适用范围

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

强制规则

• 业务枚举就是业务字典。禁止在代码中脱离字典单独发明枚举值域。
• 新增业务值域时，先写字典文档，再写表结构、接口、校验和前端展示。
• 具体业务字典必须写到 .ai-specs/doc-dict/ 下。
• 一个 .md 文件只能写一个字典。
• 字典文件名必须等于字典编码，推荐路径：.ai-specs/doc-dict/<dict-code>.md。
• 字典编码使用 snake_case，固定格式 <module>_<field>，例如 device_status。
• <dict-code> 就是 <module>_<field>。
• 字典项 Value 使用稳定 machine value；代码常量值必须与字典项 Value 完全一致。
• 代码判断统一使用字典项 Value；禁止使用 Label 做逻辑分支。
• 已上线字典的编码和字典项 Value 默认不可变；下线优先禁用，不直接删除。
• 禁止出现数据库存 1/2/3，但没有对应字典文档说明语义。
• 禁止代码新增枚举值，但未同步字典文档和字典数据。

MD 模板

.ai-specs/doc-dict/.md

# <字典中文名>

- 模块：<module>
- 字典编码：`<module>_<field>`

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

代码模板

package <module>

type <TypeName> string

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

与 SQL 的关系

• 值域字段先有字典定义，再进入表设计。
• 值域字段如何落库，按 .ai-specs/sys-specs/business-table-spec.md 执行。