CM95 — CM93 → MySQL Importer

CM95 当前仓库的已验证基线，是一个将 CM93 数据解析、标准化并保存到 MySQL 5.7 的 importer。

当前基线：

commit: 9d56592cadf7e047fb059e5a8746188595a08b43
tag:    cm93-mysql-importer-baseline-v1
date:   2026-09-02

本阶段只覆盖：

CM93 source
→ binary parse
→ dictionary decode
→ geometry build / normalization
→ MySQL 5.7
→ audit / traceability

PBF 当前继续冻结，不属于本阶段范围。

---

1. 当前状态

CM93JAPAN / Dataset ID=1 已完成两套独立全库验收：

Geometry Audit:     OVERALL: PASS
Non-Geometry Audit: OVERALL: PASS

最终基线：

项目	数量 / 结果
Cells	784
Features	322465
Attributes	405153
Sounding points	275700
Coverages	1156
Area	81080
Area valid	81080 / 81080
Coverage valid	1156 / 1156
Feature repaired	55
Coverage repaired	3
Feature geometry issues	0
Coverage geometry issues	0
raw_geotype=16	4406
raw_geotype=16 issues	0
Area bbox mismatch	0
Source files checked	784
Source files missing	0
Source size mismatch	0
Source SHA-256 mismatch	0

---

2. 主要能力

Importer 当前处理并保存：

• CM93 Cell 扫描；
• CM93OBJ / CM93ATTR 字典；
• Cell header；
• vector / edge；
• 2D point；
• 3D sounding；
• Feature；
• Attribute；
• Point / Line / Area；
• Coverage；
• WGS offset；
• Sounding point；
• Feature bbox；
• raw feature / raw attribute；
• Cell 原始 table 分块；
• source SHA-256；
• import job / event；
• geometry issue / repaired 状态。

每个 Feature 必须保持：

dataset_id
cell_id
source_record_index

从数据库记录可追溯回原始 CM93 Cell 和 source record。

---

3. 生产代码

核心生产文件：

src/cm93db/cm93_binary.py
src/cm93db/cell_parser.py
src/cm93db/geometry.py
src/cm93db/importer.py
src/cm93db/audit.py
sql/001_schema_mysql57.sql

Geometry 和 importer 的当前行为已经通过全量数据验收。后续没有明确任务时，不应重写其主流程。

---

4. 数据库

目标数据库：

MySQL 5.7

Schema：

sql/001_schema_mysql57.sql

Importer 的 normalized SRID 为：

EPSG:4326

MySQL geometry 通过 WKB 写入，坐标使用 double precision。

不要假设 MySQL 8 的 Spatial / SRID 行为适用于本项目。

数据库连接配置以项目现有 .env.example / 配置模块为准。

---

5. 导入

Windows 项目环境示例：

cd D:\React\cm93-mysql-importer-starter

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

普通导入会根据：

chart_cell.import_status
source_size
source_sha256

跳过已经成功导入且源文件 SHA-256 未变化的 Cell。

典型输出：

SKIP ... (SHA-256 unchanged)

需要强制重新解析并写入所有选中 Cell 时：

& ".\.venv\Scripts\cm93db.exe" import D:\Ship\CM93V2\CM93JAPAN --reimport

--reimport 会清理每个 Cell 已有 payload 后重新生成，因此只应在明确需要全量重导时使用。

如果单个 Cell 因临时数据库连接错误等原因处于 FAILED，普通 import 默认会重试失败 Cell，同时跳过其余未变化的 DONE Cell。

---

6. Geometry 语义

6.1 坐标

CM93 raw coordinate 按 Cell header 参数转换到 Mercator 坐标，再转换为经纬度。

Coverage 的 _wgsox / _wgsoy 用于最终 geometry 的 WGS offset 修正。

最终数据库 geometry 使用 SRID 4326。

6.2 Line

Line 必须保留断开的多个 line parts，不得为了得到单条 LineString 而跨 discontinuity 人为连接。

6.3 Area / Coverage

当前冻结规则：

已经 OGC-valid

PASS-THROUGH

已经 valid 的 Polygon / MultiPolygon 不重新 normalization，不为了统一 ring 顺序而重建。

OGC-invalid

只有 invalid Area / Coverage 才执行：

boundary noding
→ polygonize_full
→ odd-even face selection
→ union selected faces
→ GEOS normalize
→ valid Polygon / MultiPolygon

该规则来自 CM93 实际 topology / fill semantics 的完整审计。

生产规则明确禁止直接使用：

make_valid()
ST_MakeValid()
buffer(0)

来覆盖原始 CM93 Polygon 语义。

Normalization 不允许创造原始 CM93 boundary linework 之外的新边界。

open ring、断裂 contour 等真实结构异常不能静默“修好”；无法安全 normalization 的 Coverage 必须阻止错误 Cell 落库。

6.4 raw_geotype=16

raw_geotype=16 是 CM93 正常的 parent/no-geometry 对象。

当前正确语义：

geometry_type      = META
geometry           = NULL
geometry_issue     = NULL
geometry_repaired  = 0

它不是 "geometry missing" 错误，也不进入 geometry_invalid_count。

当前 Dataset ID=1 共验证：

4406 / 4406

全部为正常 parent/no-geometry。

6.5 bbox

Area 发生 normalization 后：

feature bbox = final normalized geometry.bounds

不能继续使用 normalization 前可能包含 retraced connector 的 bounds。

---

7. geometry_repaired / geometry_issue

geometry_repaired=1 表示 importer 对原 OGC-invalid CM93 polygon 执行冻结 normalization，并得到了最终 valid Polygon/MultiPolygon。

geometry_issue 只用于：

• geometry 真正缺失但该 primitive 应存在 geometry；
• geometry empty；
• open ring / 结构异常；
• normalization 无法安全完成；
• 其他真实 geometry 异常。

正常 META parent/no-geometry 不属于 issue。

当前已验证：

Feature repaired  = 55
Coverage repaired = 3
Feature issues    = 0
Coverage issues   = 0

Coverage 同时也是 _m_sor Feature，所以不要简单把 55 + 3 当作 58 个独立 CM93 source Feature。

---

8. Raw source 保留

标准化 geometry 不得破坏原始输入证据。

必须长期保留：

chart_feature.raw_feature_blob
chart_feature.raw_attribute_blob
chart_raw_record
source_record_index

chart_raw_record 使用分块保存原始 Cell table，并在 metadata 中记录：

chunk_index
chunk_count
total_bytes

这保证后续仍可重新核对 parser 与 CM93 原始二进制。

---

9. 长期回归验收

正式长期验收工具：

tools/cm93_mysql_final_geometry_audit.py
tools/cm93_mysql_non_geometry_final_audit.py

Geometry 全库验收

& ".\.venv\Scripts\python.exe" .\tools\cm93_mysql_final_geometry_audit.py `
  --host 127.0.0.1 `
  --port 3306 `
  --user root `
  --database cm93_chart `
  --dataset-id 1

当前 CM93JAPAN 基线应得到：

Cells                  : 784
Features               : 322465
Feature repaired       : 55
Coverage repaired      : 3
Feature issues         : 0
Coverage issues        : 0
Geotype16 total        : 4406
Geotype16 issues       : 0
Area total             : 81080
Area valid             : 81080
Area bbox mismatch     : 0
Coverage total         : 1156
Coverage valid         : 1156
Failure count          : 0
OVERALL: PASS

非 Geometry 全库验收

& ".\.venv\Scripts\python.exe" .\tools\cm93_mysql_non_geometry_final_audit.py `
  --host 127.0.0.1 `
  --port 3306 `
  --user root `
  --database cm93_chart `
  --dataset-id 1 `
  --source-root "D:\Ship\CM93V2\CM93JAPAN"

当前 CM93JAPAN 基线应得到：

Cells                   : 784
Features                : 322465
Attributes              : 405153
Soundings               : 275700
Coverages               : 1156

Cell count mismatch     : 0
Feature check failures  : 0
Dictionary failures     : 0
Attribute failures      : 0
Coverage failures       : 0
Sounding failures       : 0
JSON/relation failures  : 0
Raw failures            : 0

Source files checked    : 784
Source files missing    : 0
Source size mismatch    : 0
Source SHA256 mismatch  : 0

Failure count           : 0
OVERALL: PASS

任何实质性修改以下部分后，都应重新执行对应验收：

• binary parser；
• dictionary decode；
• geometry build；
• Area/Coverage normalization；
• WGS offset；
• importer DB mapping；
• raw preservation；
• Feature / Attribute / Sounding / Coverage 关系；
• bbox；
• schema。

---

10. 历史调查脚本

仓库中保留了本次 importer 调查过程中产生的 V 系列审计脚本。

它们用于记录问题定位过程，不再作为日常回归入口。

日常回归只使用：

tools/cm93_mysql_final_geometry_audit.py
tools/cm93_mysql_non_geometry_final_audit.py

历史调查脚本不要被新的生产代码 import，也不要把历史审计结果作为运行时依赖。

---

11. Git 冻结基线

当前正式可回退点：

commit 9d56592cadf7e047fb059e5a8746188595a08b43
tag    cm93-mysql-importer-baseline-v1

该 tag 表示：

CM93 → MySQL importer validated baseline

tag 应保持不可变。

后续改动在 main 上正常提交；需要对比时，以此 tag 作为 importer normalization 前后已验证基线。

---

12. 当前不做的事情

当前 importer 阶段不包括：

• PBF 生成；
• PBF schema；
• PBF renderer；
• PBF API；
• 为 PBF 改写 MySQL importer；
• 为了下游显示而损失 raw CM93 数据；
• 对原始 CM93 文件进行写回。

PBF 只有在单独明确启动下一阶段后才进入设计和实现。