# CM93 → MySQL 高精度母数据库导入器 v0.2.0

## 目标

本工程完成第一阶段：

**CM93 Z/A/B/C/D/E/F/G → 完整解析 → MySQL 5.7.34 母数据库 → 源/库双重审计。**

本阶段不生成 PBF。PBF 是第二阶段，可从本母数据库反复生成。

## 固定环境

- Windows 11
- pyenv-win
- Python **3.12.10**
- MySQL **5.7.34**
- 当前 CM93 日本数据目录：`D:\Ship\CM93V2\CM93JAPAN`
- 标准化几何：经纬度/WGS84 语义，SRID 4326
- 坐标计算：Python double / MySQL WKB double

## 已实现

- CM93 256-byte substitution decode
- 10-byte prolog + 128-byte header
- 文件长度完整性检查
- vector table
- 2D point table
- 3D sounding table
- feature table
- object dictionary
- typed attribute dictionary / attribute blob
- Point / Line / Area / Sounding
- edge reverse flag
- Area contour/ring 组装
- `_m_sor` coverage
- `_wgsox/_wgsoy` 保存与标准化坐标修正
- CM93 6378388.0 m Mercator
- typed MySQL attributes
- raw feature / raw attribute
- 解码后的全部 CM93 table 分块保存
- 每 cell 独立事务
- DONE 自动跳过
- FAILED 默认重试
- 全目录断点续导
- import job / event 日志
- 源文件重新解析审计
- 数据库逐 cell 数量审计
- raw 数据字节完整性审计
- SHA-256 审计
- MySQL WKB 双精度回读审计

## 已验证的真实 CM93 小样本

开发时对用户提供的 147 个真实 CM93 cell 执行完整 parser 回归：

- Cell: 147/147 PASS
- Feature: 100,621
- Attribute: 112,746
- 未发生 record 越界或文件尾剩余
- header attribute-byte count 与解析结果一致
- header geometry-ref count 与解析结果一致
- header related-pointer count 与解析结果一致
- decoded raw table 字节合计与原文件长度一致

MySQL 写入需要在目标 Windows/MySQL 5.7.34 上做 pilot 验收；本包提供对应命令和审计。

---

# 1. 升级已有 v0.1.x 工程

如果原目录已经有正确的 `.venv` 和 `.env`，把 v0.2.0 ZIP 中整个 `cm93-mysql-importer-starter` 目录覆盖到原工程即可。

ZIP 不包含 `.env`，所以你已有的数据库密码不会被覆盖。

然后执行：

```powershell
cd D:\React\cm93-mysql-importer-starter
& ".\.venv\Scripts\python.exe" -m pip install -e .
& ".\.venv\Scripts\cm93db.exe" --help
```

确认出现 `import` 和 `audit`。

# 2. .env

确保：

```text
CM93_DB_HOST=127.0.0.1
CM93_DB_PORT=3306
CM93_DB_NAME=cm93_chart
CM93_DB_USER=你的用户
CM93_DB_PASSWORD=你的密码
CM93_DB_CHARSET=utf8mb4
CM93_SOURCE_DIR=D:\Ship\CM93V2\CM93JAPAN
```

`scan / inspect-dicts / import / audit` 现在都可以省略路径，自动读取 `CM93_SOURCE_DIR`。

# 3. 环境/数据库检查

```powershell
& ".\.venv\Scripts\cm93db.exe" env-check
& ".\.venv\Scripts\cm93db.exe" db-check
& ".\.venv\Scripts\cm93db.exe" scan
& ".\.venv\Scripts\cm93db.exe" inspect-dicts
```

# 4. 先做 G 层 10-cell pilot

不要第一次就直接跑完整日本数据。先验证 MySQL 实际写入：

```powershell
& ".\.venv\Scripts\cm93db.exe" import --scale G --limit 10
```

然后立即审计同一批：

```powershell
& ".\.venv\Scripts\cm93db.exe" audit --scale G --limit 10 --precision-samples 32
```

目标：

```text
source_parse_failed   : 0
db_missing_cells      : 0
db_not_done_cells     : 0
count_mismatches      : 0
hash_mismatches       : 0
raw_preservation_bad  : 0
unknown_objects       : 0
unknown_attributes    : 0
precision_failed      : 0
RESULT                : PASS
```

# 5. 全量导入日本数据

Pilot PASS 后：

```powershell
& ".\.venv\Scripts\cm93db.exe" import
```

程序逐 cell 工作。已经 `DONE` 且 **SHA-256 未变化** 的 cell 自动跳过，因此中断后重新执行同一命令即可续导。

FAILED cell 默认在下一次执行时重试。

# 6. 全量审计

```powershell
& ".\.venv\Scripts\cm93db.exe" audit --precision-samples 256
```

这会重新读取 CM93 源文件，并与数据库逐 cell 对比：

- SHA-256
- Feature 数
- Attribute 数
- Point geometry 数
- Line geometry 数
- Area geometry 数
- `_m_sor` coverage 数
- Sounding point 数
- raw table 保存字节数
- 未知 object / attribute
- 抽样 WKB 双精度 round-trip

## 更严格的 geometry validity 检查

```powershell
& ".\.venv\Scripts\cm93db.exe" audit --precision-samples 256 --validate-geometry
```

`--validate-geometry` 会额外用 Shapely 全量检查拓扑，明显更重。CM93 中存在自相交/边界类 contour 并不自动等于解析错误，因此这项结果作为信息单独显示，不会静默修复原 geometry。

# 7. 常用控制

只处理 F/G：

```powershell
cm93db import --scale F --scale G
```

只处理一个 cell：

```powershell
cm93db import --cell 04501075.G
cm93db audit --cell 04501075.G --precision-samples 16
```

强制重导：

```powershell
cm93db import --cell 04501075.G --reimport
```

只审计源文件 parser，不访问数据库内容：

```powershell
cm93db audit --source-only
```

正式母库**不建议**使用 `--no-raw-tables`。如果有意不保存 raw table，审计时需显式：

```powershell
cm93db audit --allow-missing-raw
```

---

# 精度原则

1. CM93 raw X/Y 保持 16-bit 原始语义。
2. Cell easting/northing header 值使用 double。
3. CM93 Mercator 半长轴固定 `6378388.0`。
4. `_wgsox/_wgsoy` 以米为单位，在 Mercator→经纬度之前按 CM93 Transform 语义减去。
5. MySQL geometry 由 WKB 写入；WKB 坐标为 IEEE-754 8-byte double。
6. importer 阶段不 simplify、不 quantize、不 snap、不 round。
7. Polygon 不自动 `make_valid`。
8. 原始 decoded table + raw feature/attribute 与标准化 geometry 同时保留。
9. PBF 将来是可重新生成的发布格式，不能反向影响母数据库精度。

详见 `docs/精度规范.md` 和 `docs/CM93解析与审计设计.md`。

# Codex 接手

Codex 不需要重新实现 parser。先读：

- `AGENTS.md`
- `codex/ARCHITECTURE.md`
- `codex/20_导入与审计接手.md`

后续主要职责是：在你的 Win11 + MySQL 5.7.34 + CM93JAPAN 实际环境运行 pilot、分析失败 cell、修正真实兼容问题，并保留精度/审计边界。