多数据库格式支持与统一数据规范

为确保跨系统数据交互的稳定性与一致性，所有业务数据落库必须遵循 “Golden Record” 统一规范。本规范定义标准字段命名、类型约束及必填性校验逻辑，适用于 PostgreSQL、MySQL、MongoDB、Elasticsearch 与离线文件存储等场景。

1. 统一数据规范与必填字段

1.1 基础字段定义

字段名	数据类型	必填	说明与约束
id	BigInt/String	是	全局唯一标识。推荐使用雪花算法(Snowflake)生成的 64 位整数，或 UUID v4。
biz_id	String	是	业务主键(如订单号、用户 ID)，支持幂等性校验。
created_at	Timestamp	是	创建时间，统一存储为 UTC+8，精度至少到秒。
updated_at	Timestamp	是	更新时间，随数据变更自动刷新。
version	Integer	是	乐观锁版本号，初始值为 1，每次更新自增。
is_deleted	Boolean/Int	是	软删除标识。0=正常，1=已删除。物理删除需经归档流程。
source	String	否	数据溯源字段，记录数据来源系统或采集点。

1.2 设计原则

命名规范
- 采用 snake_case(下划线命名)，禁止驼峰。
- 布尔值字段建议以 is_ 或 has_ 开头。
- 避免使用数据库保留字(如 order, group)。
类型与校验
- 金额涉及计算使用 Decimal，展示使用 String。
- 枚举值必须在 Schema 中定义允许值列表。
- JSON 字段需限制嵌套层级不超过 3 层以保证查询性能。

2. 多数据库格式映射与适配

不同存储引擎在数据类型与索引机制上存在差异。下表列出核心字段在主流数据库及文件格式中的映射实践。

2.1 类型映射表

标准类型	PostgreSQL	MySQL	MongoDB	Elasticsearch	Parquet
ID (Int64)	BIGINT	BIGINT	Long / ObjectId	long	INT64
String	TEXT	VARCHAR(N)	String	keyword / text	BINARY (UTF8)
JSON	JSONB	JSON	Object	object / nested	STRUCT / MAP
Timestamp	TIMESTAMPTZ	DATETIME(6)	Date	date	INT96 / INT64

2.2 差异化适配策略

事务与一致性
- RDBMS (PG/MySQL)：强事务支持，适用于核心交易数据。
- MongoDB：支持多文档事务(4.0+)，但建议优先单文档原子性。
- Elasticsearch：最终一致性，需配合重试机制与版本号控制。
索引与分区
- MySQL：必须有主键，大表建议按时间 Range 分区。
- Elasticsearch：区分 keyword(精确) 与 text(分词)，按天/月滚动索引。
- Parquet：按 dt(日期)目录分区，利用 RowGroup 过滤。

3. 标准 Schema 与示例定义

以下展示通用 “文档实体 (Doc Entity)” 标准 Schema 及实现示例。

3.1 PostgreSQL DDL

CREATE TABLE docs (
  id BIGINT PRIMARY KEY,
  biz_id VARCHAR(64) NOT NULL UNIQUE,
  title TEXT NOT NULL,
  content JSONB DEFAULT '{}',
  status SMALLINT DEFAULT 0,
  tags TEXT[],
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW(),
  version INT DEFAULT 1,
  is_deleted BOOLEAN DEFAULT FALSE
);
CREATE INDEX idx_docs_biz_id ON docs(biz_id);
CREATE INDEX idx_docs_tags ON docs USING GIN(tags);

3.2 Elasticsearch Mapping

{
  "mappings": {
    "properties": {
      "id": { "type": "long" },
      "biz_id": { "type": "keyword" },
      "title": { "type": "text", "analyzer": "ik_max_word" },
      "content": { "type": "object" },
      "status": { "type": "integer" },
      "tags": { "type": "keyword" },
      "created_at": { "type": "date" },
      "version": { "type": "integer" }
    }
  }
}

3.3 数据流向架构

建议与数据入口与同步架构统一设计，参见 docs/25-ingestion-architecture.md 与 docs/28-crawling-and-sync.md。

4. 数据质量与一致性策略

在分布式异构存储环境中，保证数据的一致性与完整性是首要挑战。采用 “事前防御 + 事后对账” 的双重保障策略。

4.1 写入阶段：幂等与去重

利用 biz_id 作为唯一键进行数据库层唯一性约束。
对无事务支持的存储(如 Kafka)，使用内容哈希作为去重指纹。

4.2 同步阶段：延迟与重试

消息队列乱序到达时比较 updated_at 或 version，仅允许高版本覆盖低版本(Last Write Wins)。
对 ES 等最终一致性存储，失败触发重试并记录告警。

4.3 校验阶段：T+1 对账

每日凌晨运行离线对账作业，比对源库(MySQL)与目标库(ES/Hive)的数据总量与抽样指纹。
发现差异自动触发修补任务。

4.4 生命周期：归档与冷热分离

超过 365 天的数据自动迁移至冷存储(如 OSS/S3 Parquet)。
热库仅保留高频访问数据。

4.5 一致性校验流程

一致性校验与对账策略详见 docs/28-crawling-and-sync.md。

5. 发布与版本管理

本规范文档发布与版本管理统一走知识库文档系统接口：

接口与鉴权：docs/18-docs-rest-api.md
迭代记录模板：docs/21-iteration-template.md
文档管理流程：docs/17-docs-management.md

6. 关联文档

docs/06-domain-model-and-data-dictionary.md：领域字段与口径对齐
docs/05-data-pipeline-and-quality.md：清洗与标准化策略
docs/25-ingestion-architecture.md：数据入口与治理架构

26-multi-db-spec.md