Initial import of NavSea pbf project

NavSea_Geometry_Enablement.md

@@ -0,0 +1,107 @@
+# NavSea Geometry Enablement
+
+## 目的
+
+为 `navsea_detection_objects` 补上真实 geometry，并在数据库中启用真正的空间索引能力。
+
+## 当前现状
+
+当前 `pbf_analysis` 库中没有真实坐标 geometry 列，只有：
+
+- `feature_id`
+- `z/x/y`
+- `vt_layer`
+- `geom_type`
+
+因此当前系统只能做：
+
+- 语义分类
+- tile 级查询优化
+- 基于 `z/x/y` 的近似空间诊断
+
+不能做：
+
+- 真正的半径查询
+- 真正的航线走廊查询
+- 真正的船首前方空间查询
+- 真正的 `SPATIAL INDEX` 查询计划
+
+## 启用方式
+
+使用脚本：
+
+```bash
+.venv/bin/python navsea_geometry_enable.py
+```
+
+默认要求数据库中存在 staging 表：
+
+```text
+feature_geometry_stage
+```
+
+可以通过环境变量改名：
+
+```bash
+NAVSEA_GEOMETRY_SOURCE_TABLE=your_table .venv/bin/python navsea_geometry_enable.py
+```
+
+## 支持的 staging 结构
+
+脚本支持以下任一输入形式：
+
+### 1. 直接 geometry 列
+
+```sql
+feature_id BIGINT
+geometry GEOMETRY
+```
+
+### 2. WKT
+
+```sql
+feature_id BIGINT
+geometry_wkt LONGTEXT
+```
+
+### 3. WKB
+
+```sql
+feature_id BIGINT
+geometry_wkb BLOB
+```
+
+### 4. 点坐标
+
+```sql
+feature_id BIGINT
+lon DOUBLE
+lat DOUBLE
+```
+
+仅适用于 Point 类对象。
+
+## 脚本输出
+
+如果 staging 表满足要求，脚本会创建：
+
+- `navsea_feature_geometry`
+- `navsea_detection_objects_spatial`
+
+其中：
+
+- `navsea_feature_geometry` 保存真实 geometry，并建立 `SPATIAL KEY idx_geometry`
+- `navsea_detection_objects_spatial` 是 `navsea_detection_objects` 的空间版只读视图
+
+## 推荐的后续查询
+
+当 geometry 可用后，可以在 `navsea_detection_objects_spatial` 上执行：
+
+- 半径查询
+- 航线缓冲带查询
+- 前方扇形查询
+- 空间相交 / 邻近查询
+
+## 当前阻塞
+
+当前唯一阻塞不是脚本，而是缺少 geometry staging 数据源。