# CM93 导入与审计操作说明

## 1. 适用环境

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

## 2. 正式导入

如果 `.env` 已配置：

```text
CM93_SOURCE_DIR=D:\Ship\CM93V2\CM93_2014
```

可直接运行：

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

也可显式给路径：

```powershell
& ".\.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 前先跑：

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

然后：

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

通过后再跑完整导入。

### 只导某些尺度

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

### 强制重导

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

## 3. 审计

### 快速审计

```powershell
& ".\.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 比较。

默认坐标容差：

```text
1e-12 degree
```

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

### 全源最终审计

完整导入后：

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

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

报告自动写入：

```text
logs/audit-YYYYMMDD-HHMMSS.json
```

## 4. offset policy

正式母库默认：

```text
--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。

为研究/对照可运行：

```powershell
--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 如需要显示修复，应在发布层制定独立策略，不能修改母数据库事实。