CM93 MySQL importer validated baseline

README.md

@@ -0,0 +1,236 @@
+# 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、修正真实兼容问题，并保留精度/审计边界。