Freeze validated CM93 importer baseline docs and audits

2026-09-02 10:28:23 +08:00
parent 9d56592cad
commit 0ca1f63320
6 changed files with 2366 additions and 245 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,61 +1,354 @@
-# Codex / AI Agent 项目规则
+# AGENTS.md — CM95 / CM93 → MySQL Importer

-## 当前目标
+## 1. 当前项目状态

-第一阶段已经具备 `CM93 → MySQL` 完整导入与审计代码。当前工作是用真实 `CM93JAPAN` 数据运行、诊断和修复实际兼容问题。
+当前 CM93 → MySQL importer 已完成 CM93JAPAN Dataset ID=1 的全量验证。

-**不要提前实现 PBF。**
+冻结基线：

-## 固定基线
-
- Windows 11
- Python 3.12.10
- MySQL 5.7.34-log
- CM93 根目录：`D:\Ship\CM93V2\CM93JAPAN`
- DB Schema：`sql/001_schema_mysql57.sql`
-
-## 不可破坏规则
-
-1. 禁止 MySQL 8 专用 SQL。
-2. 禁止 float32 存最终经纬度。
-3. 禁止 importer simplify/snap/quantize/round geometry。
-4. 禁止自动 make_valid 后覆盖原 Polygon。
-5. raw decoded tables、raw feature、raw attribute 必须可保留。
-6. `_wgsox/_wgsoy` 必须保存。
-7. 每个 feature 必须可追溯 dataset/cell/source_record_index。
-8. 未知 object/attribute 不得静默跳过；无法确定长度时 cell 必须 FAILED。
-9. parser 任一 header/count/EOF 不一致时 cell 必须 FAILED。
-10. 每个 cell 独立事务；失败不得破坏其他 DONE cell。
-11. DONE cell 支持续导跳过。
-12. 不复制 OpenCPN GPL 源文件或类实现；保持独立实现。
-13. PBF 不属于当前阶段。
-
-## 实际运行顺序
-
-```powershell
-cm93db env-check
-cm93db db-check
-cm93db scan
-cm93db inspect-dicts
-cm93db import --scale G --limit 10
-cm93db audit --scale G --limit 10 --precision-samples 32
+```text
+commit: 9d56592cadf7e047fb059e5a8746188595a08b43
+tag:    cm93-mysql-importer-baseline-v1
 ```

-Pilot PASS 后再全量。
+最终验收：

-## 修复要求
+```text
+Geometry Audit:     OVERALL: PASS
+Non-Geometry Audit: OVERALL: PASS
+```

-发现失败时，优先保留一个具体失败 cell 作为回归输入，并报告：
+PBF 当前继续冻结。

- cell 路径
- parser stage
- byte position/record index
- header source counts
- 实际异常
- 修改前后审计结果
+---

-不得通过 catch-and-skip 使任务“看起来完成”。
+## 2. 核心原则

-## 文档
+1. 真实源码优先，不根据历史报告猜测当前实现。
+2. 修改旧文件前必须先读取当前实际文件。
+3. 不重新设计已经通过验收的 importer 主流程，除非任务明确要求。
+4. 生产数据链必须保持可追溯、可回归。
+5. MySQL 目标环境按 MySQL 5.7 处理，不假设 MySQL 8 Spatial 行为。
+6. PBF 不属于当前 importer 维护任务，除非明确启动 PBF 阶段。

-项目说明、报告、设计记录使用中文；代码稳定标识符、数据库字段使用英文。
+---
+
+## 3. 冻结生产文件
+
+以下是当前已验证的核心文件：
+
+```text
+src/cm93db/geometry.py
+src/cm93db/importer.py
+sql/001_schema_mysql57.sql
+```
+
+没有明确任务时，不得重写 geometry / importer 主流程。
+
+如必须修改，完成后必须运行长期回归验收。
+
+---
+
+## 4. Geometry Contract
+
+### 4.1 Valid geometry
+
+已经 OGC-valid 的 Area / Coverage：
+
+```text
+PASS-THROUGH
+```
+
+不得为了 canonical 风格、ring 顺序或代码统一而重建。
+
+### 4.2 Invalid polygon normalization
+
+只有 OGC-invalid Area / Coverage 才允许：
+
+```text
+boundary noding
+→ polygonize_full
+→ odd-even face selection
+→ union selected faces
+→ GEOS normalize
+→ valid Polygon / MultiPolygon
+```
+
+禁止用下列方法直接覆盖原始 CM93 Polygon：
+
+```text
+make_valid()
+ST_MakeValid()
+buffer(0)
+```
+
+Normalization 必须满足：
+
+- 不创造原始 boundary linework 之外的新边界；
+- 最终必须是 non-empty valid Polygon/MultiPolygon；
+- 无法安全完成时保留 issue / 拒绝错误 Coverage；
+- raw source 永远保留。
+
+### 4.3 raw_geotype=16
+
+`raw_geotype=16` 是正常 CM93 parent/no-geometry。
+
+必须保持：
+
+```text
+geometry_type      = META
+geom               = None / NULL
+geometry_issue     = None / NULL
+geometry_repaired  = False / 0
+```
+
+禁止重新生成：
+
+```text
+geometry_issue = "geometry missing"
+```
+
+禁止增加：
+
+```text
+geometry_invalid_count
+```
+
+不得人为创建空 geometry。
+
+### 4.4 bbox
+
+normalized Area 的 bbox 必须来自最终保存的 geometry.bounds。
+
+### 4.5 Coverage
+
+Coverage 参与 WGS offset 判断，因此 unresolved invalid Coverage 不允许静默落库并继续参与 offset 选择。
+
+---
+
+## 5. Raw Source Contract
+
+必须保留：
+
+```text
+raw_feature_blob
+raw_attribute_blob
+chart_raw_record
+source_record_index
+```
+
+任何 normalization 都只改变标准化 geometry 表达，不改变原始 CM93 二进制证据。
+
+Feature 必须可追溯：
+
+```text
+dataset_id
+cell_id
+source_record_index
+```
+
+---
+
+## 6. Database Contract
+
+目标：
+
+```text
+MySQL 5.7
+```
+
+Normalized geometry：
+
+```text
+SRID 4326
+WKB double precision
+```
+
+不要：
+
+- 把 MySQL 8 的 SRID column constraint 当成 MySQL 5.7；
+- 依赖 MySQL 8-only spatial behavior；
+- 擅自修改 schema 来迁就临时测试；
+- 把 geometry 直接塞回 `chart_feature` 代替现有独立 geometry tables。
+
+---
+
+## 7. Import Contract
+
+正常 import：
+
+- DONE + source size 相同 + SHA-256 相同 → SKIP；
+- FAILED 默认允许普通 import 重试；
+- `--reimport` 才强制重新解析并写入。
+
+不要为了测试方便修改 SHA-256 skip 逻辑。
+
+单 Cell 写库必须保持事务语义；失败时不得留下半个 Cell payload。
+
+---
+
+## 8. Counter Contract
+
+`geometry_invalid_count`：
+
+- 只统计实际 unresolved geometry issue；
+- 正常 META/no-geometry 不统计。
+
+`geometry_repaired_count`：
+
+- 统计通过冻结 normalization 得到最终有效 polygon 的 Feature；
+- 与 Coverage 表自身 `geometry_repaired` 的记录数不是简单独立相加关系。
+
+当前基线：
+
+```text
+Feature repaired  = 55
+Coverage repaired = 3
+Geometry issues   = 0
+```
+
+---
+
+## 9. 当前验收基线
+
+CM93JAPAN / Dataset ID=1：
+
+```text
+Cells                   784
+Features                322465
+Attributes              405153
+Soundings               275700
+Coverages               1156
+
+Area                    81080
+Area valid              81080
+Coverage valid          1156
+Area bbox mismatch      0
+
+Feature repaired        55
+Coverage repaired       3
+Feature geometry issues 0
+Coverage geometry issues 0
+
+raw_geotype=16          4406
+geotype16 issues        0
+
+Source files checked    784
+Source missing          0
+Source size mismatch    0
+Source SHA256 mismatch  0
+```
+
+---
+
+## 10. 必做回归
+
+长期工具：
+
+```text
+tools/cm93_mysql_final_geometry_audit.py
+tools/cm93_mysql_non_geometry_final_audit.py
+```
+
+修改以下任一项后，必须重新运行相关全库验收：
+
+- parser；
+- edge / point / sounding decode；
+- geometry build；
+- Coverage；
+- WGS offset；
+- odd-even normalization；
+- bbox；
+- DB mapping；
+- raw preservation；
+- schema；
+- Feature / Attribute / Sounding / Coverage 关系。
+
+验收目标：
+
+```text
+OVERALL: PASS
+```
+
+不能用“抽样看起来正常”代替全库 audit。
+
+---
+
+## 11. 历史审计脚本
+
+仓库根目录现有 V 系列脚本属于调查历史。
+
+允许：
+
+- 保留；
+- 人工复查；
+- 用于追溯决策来源。
+
+禁止：
+
+- 让生产代码 import 它们；
+- 把它们当运行时依赖；
+- 以旧 V 输出覆盖当前数据库事实；
+- 因为历史脚本报告过旧问题，就假设当前 importer 仍存在同一问题。
+
+长期回归以 `tools/` 下两个 final audit 为准。
+
+---
+
+## 12. 文档规则
+
+修改行为后同步更新：
+
+```text
+README.md
+AGENTS.md
+docs/CM93_Importer冻结基线_v1.md
+```
+
+文档必须区分：
+
+- 当前生产行为；
+- 历史调查结论；
+- 已关闭问题；
+- 尚未启动的未来阶段。
+
+不得继续把已经解决的问题写成“当前待处理”。
+
+---
+
+## 13. Git 规则
+
+当前稳定 tag：
+
+```text
+cm93-mysql-importer-baseline-v1
+```
+
+不得移动或重写该 tag。
+
+后续变更：
+
+1. 在当前 `main` 基础上修改；
+2. 验证；
+3. commit；
+4. push；
+5. 必要时再创建新的版本 tag。
+
+不要把与当前任务无关的本地文件一起提交。
+
+---
+
+## 14. PBF
+
+当前：
+
+```text
+PBF = OUT OF SCOPE / FROZEN
+```
+
+除非用户明确启动 PBF 阶段：
+
+- 不新增 PBF schema；
+- 不新增 PBF exporter；
+- 不修改 importer 为 PBF 服务；
+- 不以 PBF 需求反向破坏当前 MySQL/raw 数据模型。