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，所以你已有的数据库密码不会被覆盖。

然后执行：

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_sor coverage 数
• 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

---

精度原则

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