领域数据字典规则

适用于多系统协同项目中的字段统一、枚举统一、命名统一与口径对齐。

规则文件内容

请复制以下内容，保存为 .cursor/rules/domain-data-dictionary.mdc：

---
description: 领域数据字典、字段命名、枚举语义与兼容映射规则
globs: src/domain/**, src/modules/**/dto/**, docs/data-dictionary/**
---

# 领域数据字典业务规则

## 1. 核心原则
- **一词一义**：同一业务概念只能有一个标准定义。
- **命名一致**：同语义字段在跨系统中保持统一命名。
- **变更可追溯**：字典变更必须有版本与发布记录。

## 2. 字段命名规则
- 主键统一使用 `id`，外键使用 `{entity}_id`。
- 时间字段统一使用 `*_at`（ISO8601）。
- 状态字段统一使用 `status`，枚举值全小写下划线。

## 3. 枚举治理规则
- 每个枚举值必须有中文释义与业务含义。
- 废弃枚举需标记 `deprecated_at`，禁止直接删除。
- 新增枚举需评估兼容影响并更新映射表。

```ts
interface DictionaryItem {
  domain: string;
  fieldName: string;
  dataType: string;
  enumValues?: string[];
  description: string;
  version: string;
}

4. 空值与默认值规则

• 区分 null（未知）与空字符串（已知为空）。
• 默认值必须在字典中声明来源与理由。
• 禁止业务层隐式补默认值。

5. 跨系统映射规则

• 建立 source_field -> standard_field 映射。
• 映射冲突需进入评审流程。
• 映射层禁止承载业务计算逻辑。

6. 发布与校验规则

• 字典发布采用版本号 major.minor.patch。
• 上线前必须跑字段完整性校验。
• 未登记字段禁止进入生产接口。

7. 审计与协同规则

• 字段新增/修改需记录 owner 与审批单号。
• 关键字典每月做一次一致性巡检。
• 对外接口字段变更需提前公告窗口。

8. 数据模型约束

• domain_dictionary 必须包含：domain, field_name, data_type, description, version, status
• dictionary_enum_values 必须包含：dictionary_id, enum_value, display_name, deprecated_at
• field_mappings 必须包含：source_system, source_field, standard_field, mapping_rule, version

9. 实施注意事项

• 建议将字典转为可机读 JSON/YAML，并自动生成文档。
• 对高频字段建议配置 lint 规则，阻止命名漂移。
• 数据字典应纳入代码评审清单。

## 适用场景

- 多系统字段对齐
- 数据中台建模
- 业务对象定义治理

## scripts 可执行校验版本（P3）

- **脚本路径**：`yihuohao/proven/dev-assets/cursor-skills/scripts/check-data-dictionary.cjs`
- **输入文件**：`fields/mappings` JSON（字段定义、枚举与映射）

```bash
node yihuohao/proven/dev-assets/cursor-skills/scripts/check-data-dictionary.cjs ./domain-dictionary.json

• 校验结果：命名、枚举、映射规则不满足时返回退出码 2。