wdh-home
1e33640629
Some checks failed
CI / init (pull_request) Has been cancelled
CI / Frontend node 18.16.0 (pull_request) Has been cancelled
CI / Backend go (1.22) (pull_request) Has been cancelled
CI / release-pr (pull_request) Has been cancelled
CI / devops-test (1.22, 18.16.0) (pull_request) Has been cancelled
CI / release-please (pull_request) Has been cancelled
CI / devops-prod (1.22, 18.x) (pull_request) Has been cancelled
CI / docker (pull_request) Has been cancelled
83 lines
4.4 KiB
Markdown
83 lines
4.4 KiB
Markdown
# 业务字典规范
|
||
|
||
## 适用范围
|
||
|
||
- 当任务是新增业务状态、类型、级别、来源、模式、分类等值域时，先读本文件。
|
||
- 本文件规定业务字典怎么写，统一分为 `固定值域字典` 和 `动态值域字典` 两类；不重复说明系统字典底层实现细节。
|
||
|
||
## 强制规则
|
||
|
||
- 业务字典是值域定义来源；禁止在代码中脱离字典单独发明枚举值域。
|
||
- 新增业务值域时，先写字典文档，再写表结构、接口、校验和前端展示。
|
||
- 具体业务字典必须写到 `.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` 执行，必须考虑重复执行、人工已建数据和部分明细缺失。
|