# 数据字典

## `observations_standardized.parquet`

| 字段 | 类型 | 说明 |
|---|---|---|
| `observation_id` | `string` | 稳定的观测记录标识。 |
| `source_type` | `string` | `excel` 或 `pdf_text`。 |
| `collection` | `string` | 中国能源或中国电力。 |
| `edition_year` | `int16` | 年鉴版次年份，不一定等于数据年份。 |
| `source_id` | `string` | 来源文件标识。 |
| `source_relative_path` | `string` | 相对于原始 `data/` 的来源路径。 |
| `table_id` | `string` | 表或工作表标识，可连接 `table_catalog.csv`。 |
| `sheet_name` | `string` | Excel 工作表名；PDF 记录为空。 |
| `page` | `int16` | PDF 页序号；Excel 记录为空。 |
| `table_title` | `string` | 自动识别的表题。 |
| `metric_auto` | `string` | 自动拼接的指标标签，正式展示前宜按指标维表复核。 |
| `row_label` | `string` | 原表行标签。 |
| `column_label` | `string` | 原表列标签。 |
| `region_name` | `string` | 规范化地区名；无法可靠识别时为空。 |
| `region_code` | `string` | 国家/省级代码；全国为 CHN。 |
| `data_year` | `int16` | 观测所属年份；无法可靠解析时为空。 |
| `value` | `double` | 数值，未擅自换算单位。 |
| `unit_raw` | `string` | 来源中识别的原始单位。 |
| `unit_normalized` | `string` | 规范化单位标签。 |
| `unit_dimension` | `string` | 单位量纲分类。 |
| `quality_tier` | `string` | 自动质量分层。 |
| `quality_flags` | `string` | 用 `|` 分隔的自动抽取提示。 |
| `source_row` | `int32` | Excel 原始行号。 |
| `source_column` | `int16` | Excel 原始列号。 |
| `x0` | `float` | PDF 词/数值框左坐标。 |
| `y0` | `float` | PDF 词/数值框上坐标。 |
| `x1` | `float` | PDF 词/数值框右坐标。 |
| `y1` | `float` | PDF 词/数值框下坐标。 |

## `key_indicators_latest.parquet`

| 字段 | 类型 | 说明 |
|---|---|---|
| `metric_id` | `string` | 网站/API 稳定指标键。 |
| `metric_name_zh` | `string` | 中文指标名。 |
| `category` | `string` | capacity、generation 或 consumption。 |
| `energy_type` | `string` | total、hydro、thermal、nuclear、wind、solar。 |
| `measure` | `string` | value 或 share。 |
| `region_name` | `string` | 全国或省级地区名。 |
| `region_code` | `string` | 全国为 CHN，省级为 6 位代码。 |
| `year` | `int64` | 数据年份。 |
| `value` | `double` | 原年鉴数值。 |
| `unit` | `string` | 万千瓦、亿千瓦时或 %。 |
| `edition_year` | `int64` | 用于该值的最新可用年鉴版次。 |
| `source_relative_path` | `string` | 来源 PDF 相对路径。 |
| `source_page` | `int64` | 来源 PDF 页序号。 |
| `table_title` | `string` | 来源表题。 |
| `table_id` | `string` | 来源表标识。 |
| `quality_status` | `string` | 当前为结构化表自动抽取；仍建议发布前抽样复核。 |

## 主键与连接关系

- 统一观测层主键：`observation_id`。
- 表目录主键：`table_id`；统一观测层通过同名字段连接。
- 核心指标自然键：`metric_id + region_code + year`，已验证无重复。
- `edition_year` 是出版版次，`data_year/year` 是统计期，二者不能混用。
- 数值保持来源单位；如需换算，使用 `unit_dimension.csv` 的 `multiplier_to_base`，不要在原字段上覆盖。

## 质量等级

- `auto_extracted`：年份与单位均已自动解析，但不代表人工核验。
- `needs_year_review`：年份无法稳定解析，不能直接用于时间序列。
- `needs_unit_review`：单位缺失或不确定，不能直接跨表比较。
- `auto_extracted_structured_table`：核心指标来自结构稳定的近期 PDF 表，并保留来源页；发布前仍建议抽样核对。