# 业务字典规范

## 适用范围

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

## 强制规则

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

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

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

动态值域字典模板：
```md
# <字典中文名>

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

## 代码模板

固定值域字典代码模板：
```go
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` 执行，必须考虑重复执行、人工已建数据和部分明细缺失。