# 飞球 ETL 数据库手册

> 模块专属的表级文档、字段映射、扩展表说明。
> DDL 基线见项目级 `docs/database/ddl/`，变更记录已归档至 `_archived/`。

## 目录结构

```
database/
├── ODS/
│   ├── main/       — ODS 表级文档（BD_manual_*.md）
│   └── mappings/   — API JSON → ODS 字段映射（mapping_*.md）
├── DWD/
│   ├── main/       — DWD 主表文档
│   ├── Ex/         — DWD 扩展表文档
│   └── changes/    — DWD 层变更记录
├── DWS/
│   ├── main/       — DWS 汇总表文档
│   └── changes/    — DWS 层变更记录
├── ETL_Admin/
│   └── main/       — meta schema 表文档
├── cross_layer/    — ODS→DWD 跨层字段映射（从 docs/database/ 迁入）
└── _archived/      — 过时的变更记录、DDL 对比报告、已删除表文档
```

## 文档类型

| 类型 | 命名规则 | 说明 |
|------|---------|------|
| 表级文档 | `BD_manual_{表名}.md` | 字段说明、主键、业务含义 |
| 扩展表文档 | `BD_manual_{表名}_ex.md` | SCD2 扩展字段、溢出字段 |
| 字段映射 | `mapping_{API端点}_{ODS表名}.md` | API JSON 字段 → ODS 列的映射关系 |
| 跨层映射 | `BD_Manual_{ODS表名}.md` | ODS → DWD 字段映射、装载方式、业务含义 |

## 与项目级文档的关系

| 内容 | 位置 | 说明 |
|------|------|------|
| DDL 基线 | `docs/database/ddl/` | 从数据库自动导出，按 schema 分文件 |
| 业务库 BD_Manual | `docs/database/BD_Manual_*.md` | zqyy_app 表结构、FDW、RLS 视图 |
| ODS→DWD 跨层映射 | 本目录 `cross_layer/BD_Manual_*.md` | ODS 表 → DWD 表字段映射 |
| 表级字段说明 | 本目录 `*/main/BD_manual_*.md` | 单表字段详情 |
| API→ODS 字段映射 | 本目录 `ODS/mappings/` | API JSON → ODS 列映射 |
| DWD/DWS 层变更记录 | 本目录 `DWD/changes/`、`DWS/changes/` | 加列、新表等变更说明 |