6.4 KiB
AGENTS.md — CM95 / CM93 → MySQL Importer
1. 当前项目状态
当前 CM93 → MySQL importer 已完成 CM93JAPAN Dataset ID=1 的全量验证。
冻结基线：
commit: 9d56592cadf7e047fb059e5a8746188595a08b43
tag: cm93-mysql-importer-baseline-v1
最终验收：
Geometry Audit: OVERALL: PASS
Non-Geometry Audit: OVERALL: PASS
PBF 当前继续冻结。
2. 核心原则
- 真实源码优先，不根据历史报告猜测当前实现。
- 修改旧文件前必须先读取当前实际文件。
- 不重新设计已经通过验收的 importer 主流程，除非任务明确要求。
- 生产数据链必须保持可追溯、可回归。
- MySQL 目标环境按 MySQL 5.7 处理，不假设 MySQL 8 Spatial 行为。
- PBF 不属于当前 importer 维护任务，除非明确启动 PBF 阶段。
3. 冻结生产文件
以下是当前已验证的核心文件：
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：
PASS-THROUGH
不得为了 canonical 风格、ring 顺序或代码统一而重建。
4.2 Invalid polygon normalization
只有 OGC-invalid Area / Coverage 才允许：
boundary noding
→ polygonize_full
→ odd-even face selection
→ union selected faces
→ GEOS normalize
→ valid Polygon / MultiPolygon
禁止用下列方法直接覆盖原始 CM93 Polygon：
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。
必须保持：
geometry_type = META
geom = None / NULL
geometry_issue = None / NULL
geometry_repaired = False / 0
禁止重新生成：
geometry_issue = "geometry missing"
禁止增加：
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
必须保留：
raw_feature_blob
raw_attribute_blob
chart_raw_record
source_record_index
任何 normalization 都只改变标准化 geometry 表达，不改变原始 CM93 二进制证据。
Feature 必须可追溯：
dataset_id
cell_id
source_record_index
6. Database Contract
目标：
MySQL 5.7
Normalized geometry：
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的记录数不是简单独立相加关系。
当前基线：
Feature repaired = 55
Coverage repaired = 3
Geometry issues = 0
9. 当前验收基线
CM93JAPAN / Dataset ID=1：
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. 必做回归
长期工具：
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 关系。
验收目标：
OVERALL: PASS
不能用“抽样看起来正常”代替全库 audit。
11. 历史审计脚本
仓库根目录现有 V 系列脚本属于调查历史。
允许：
- 保留；
- 人工复查；
- 用于追溯决策来源。
禁止：
- 让生产代码 import 它们；
- 把它们当运行时依赖；
- 以旧 V 输出覆盖当前数据库事实；
- 因为历史脚本报告过旧问题，就假设当前 importer 仍存在同一问题。
长期回归以 tools/ 下两个 final audit 为准。
12. 文档规则
修改行为后同步更新：
README.md
AGENTS.md
docs/CM93_Importer冻结基线_v1.md
文档必须区分：
- 当前生产行为；
- 历史调查结论；
- 已关闭问题；
- 尚未启动的未来阶段。
不得继续把已经解决的问题写成“当前待处理”。
13. Git 规则
当前稳定 tag：
cm93-mysql-importer-baseline-v1
不得移动或重写该 tag。
后续变更：
- 在当前
main基础上修改； - 验证；
- commit；
- push；
- 必要时再创建新的版本 tag。
不要把与当前任务无关的本地文件一起提交。
14. PBF
当前：
PBF = OUT OF SCOPE / FROZEN
除非用户明确启动 PBF 阶段：
- 不新增 PBF schema；
- 不新增 PBF exporter；
- 不修改 importer 为 PBF 服务；
- 不以 PBF 需求反向破坏当前 MySQL/raw 数据模型。