CM95/docs/导入与审计.md

CM93 导入与审计操作说明

1. 适用环境

• Windows 11
• Python 3.12.10
• MySQL 5.7.34
• 已完成 cm93db db-init --create-database

2. 正式导入

如果 .env 已配置：

CM93_SOURCE_DIR=D:\Ship\CM93V2\CM93_2014

可直接运行：

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

也可显式给路径：

& ".\.venv\Scripts\cm93db.exe" import D:\Ship\CM93V2\CM93_2014

默认行为：

• 递归扫描 Z/A/B/C/D/E/F/G；
• 每个 cell 独立事务；
• DONE + 文件 SHA256 相同自动跳过；
• FAILED cell 下次自动重试；
• 保存 typed attributes；
• 保存标准化 WGS84 geometry；
• 保存 decoded CM93 原始 table block；
• _wgsox/_wgsoy 默认按 embedded policy 应用；
• 不 simplify / snap / quantize / round；
• 不自动 make_valid。

先小批验证

推荐正式 30,097 cell 前先跑：

& ".\.venv\Scripts\cm93db.exe" import --scale G --limit-cells 5

然后：

& ".\.venv\Scripts\cm93db.exe" audit --sample-cells 5

通过后再跑完整导入。

只导某些尺度

& ".\.venv\Scripts\cm93db.exe" import --scale G --scale F

强制重导

& ".\.venv\Scripts\cm93db.exe" import --force

3. 审计

快速审计

& ".\.venv\Scripts\cm93db.exe" audit --sample-cells 20

包括：

1. 数据库 cell / feature / attribute 计数；
2. 每个 DONE cell 的 source count 与数据库 count 对账；
3. Point / Line / Area geometry presence；
4. 随机重新解析源 CM93 cell；
5. 源 feature / attribute count 对比；
6. 从 MySQL ST_AsWKB 读回 geometry；
7. 与重新计算的 double precision geometry 做逐顶点比较；
8. sounding raw X/Y/Z、depth、lon/lat 比较。

默认坐标容差：

1e-12 degree

这个容差用于发现数据库序列化/写入造成的精度损失，不是让 importer 人为 round 到该精度。

全源最终审计

完整导入后：

& ".\.venv\Scripts\cm93db.exe" audit --all-source

这会重新解析所有 DONE cell，耗时明显高于随机抽样，但适合作为母数据库最终验收。

报告自动写入：

logs/audit-YYYYMMDD-HHMMSS.json

4. offset policy

正式母库默认：

--offset-policy embedded

含义：

1. _m_sor coverage 自身使用未偏移 cell 坐标建立；
2. 保存 _wgsox/_wgsoy 原始值；
3. 对能够匹配 coverage 的普通几何，在 CM93 Mercator 阶段减去对应 offset；
4. 然后使用 CM93 半长轴 6378388.0 转换 WGS84 lon/lat；
5. feature JSON 中记录实际应用的 offset 和 coverage match method。

为研究/对照可运行：

--offset-policy none

但不要把同一个 dataset 混用两种 policy。改变 policy 时应 --force 全部重导，并重新执行全源审计。

5. Geometry issue

源 CM93 中可能存在自交 polygon 等问题。

规则：

• raw record 永久保留；
• geometry_issue 记录 Shapely validity / ring assembly 问题；
• geometry_repaired=0；
• 当前版本不自动修复；
• 可以保存结构上可编码的 invalid WKB；
• 无法形成 geometry 时不伪造 geometry row。

第二阶段 PBF 如需要显示修复，应在发布层制定独立策略，不能修改母数据库事实。