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