6.0 KiB
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_sorcoverage_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，所以你已有的数据库密码不会被覆盖。
然后执行：
cd D:\React\cm93-mysql-importer-starter
& ".\.venv\Scripts\python.exe" -m pip install -e .
& ".\.venv\Scripts\cm93db.exe" --help
确认出现 import 和 audit。
2. .env
确保：
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. 环境/数据库检查
& ".\.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 实际写入：
& ".\.venv\Scripts\cm93db.exe" import --scale G --limit 10
然后立即审计同一批：
& ".\.venv\Scripts\cm93db.exe" audit --scale G --limit 10 --precision-samples 32
目标：
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 后：
& ".\.venv\Scripts\cm93db.exe" import
程序逐 cell 工作。已经 DONE 且 SHA-256 未变化 的 cell 自动跳过，因此中断后重新执行同一命令即可续导。
FAILED cell 默认在下一次执行时重试。
6. 全量审计
& ".\.venv\Scripts\cm93db.exe" audit --precision-samples 256
这会重新读取 CM93 源文件，并与数据库逐 cell 对比：
- SHA-256
- Feature 数
- Attribute 数
- Point geometry 数
- Line geometry 数
- Area geometry 数
_m_sorcoverage 数- Sounding point 数
- raw table 保存字节数
- 未知 object / attribute
- 抽样 WKB 双精度 round-trip
更严格的 geometry validity 检查
& ".\.venv\Scripts\cm93db.exe" audit --precision-samples 256 --validate-geometry
--validate-geometry 会额外用 Shapely 全量检查拓扑，明显更重。CM93 中存在自相交/边界类 contour 并不自动等于解析错误，因此这项结果作为信息单独显示，不会静默修复原 geometry。
7. 常用控制
只处理 F/G：
cm93db import --scale F --scale G
只处理一个 cell：
cm93db import --cell 04501075.G
cm93db audit --cell 04501075.G --precision-samples 16
强制重导：
cm93db import --cell 04501075.G --reimport
只审计源文件 parser，不访问数据库内容：
cm93db audit --source-only
正式母库不建议使用 --no-raw-tables。如果有意不保存 raw table，审计时需显式：
cm93db audit --allow-missing-raw
精度原则
- CM93 raw X/Y 保持 16-bit 原始语义。
- Cell easting/northing header 值使用 double。
- CM93 Mercator 半长轴固定
6378388.0。 _wgsox/_wgsoy以米为单位，在 Mercator→经纬度之前按 CM93 Transform 语义减去。- MySQL geometry 由 WKB 写入；WKB 坐标为 IEEE-754 8-byte double。
- importer 阶段不 simplify、不 quantize、不 snap、不 round。
- Polygon 不自动
make_valid。 - 原始 decoded table + raw feature/attribute 与标准化 geometry 同时保留。
- PBF 将来是可重新生成的发布格式，不能反向影响母数据库精度。
详见 docs/精度规范.md 和 docs/CM93解析与审计设计.md。
Codex 接手
Codex 不需要重新实现 parser。先读：
AGENTS.mdcodex/ARCHITECTURE.mdcodex/20_导入与审计接手.md
后续主要职责是：在你的 Win11 + MySQL 5.7.34 + CM93JAPAN 实际环境运行 pilot、分析失败 cell、修正真实兼容问题，并保留精度/审计边界。