# 业务字典规范

## 适用范围

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

## 强制规则

- 业务枚举就是业务字典。禁止在代码中脱离字典单独发明枚举值域。
- 新增业务值域时，先写字典文档，再写表结构、接口、校验和前端展示。
- 具体业务字典必须写到 `.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/<dict-code>.md
```md
# <字典中文名>

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

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

## 代码模板

```go
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` 执行。