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

为确保跨系统数据交互的稳定性与一致性，所有业务数据落库必须遵循 "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

```sql
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

```json
{
  "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`：数据入口与治理架构