服务端

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

@@ -0,0 +1,53 @@
+# 业务字典规范
+
+## 适用范围
+
+- 当任务是新增业务状态、类型、级别、来源、模式、分类等值域时，先读本文件。
+- 本文件只规定新增业务字典怎么写，不重复说明系统字典实现细节。
+
+## 强制规则
+
+- 业务枚举就是业务字典。禁止在代码中脱离字典单独发明枚举值域。
+- 新增业务值域时，先写字典文档，再写表结构、接口、校验和前端展示。
+- 具体业务字典必须写到 `.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` 执行。