# NavSea 任务说明（codex6）

## 任务名称
港湾区域叠加判定与分级栅格生成（日本全国）

## 任务编号
NAVSEA-TASK-PORT-AREA-OVERLAY-CLASSIFICATION-JP-001

## 任务类型
数据预处理 / 路由底库构建 / 港湾语义叠加

## 适用架构
- NavSea Architecture V11
- NavSea Codex System v6（codex6）

## 任务背景
上一阶段任务已确定：
- 使用日本国土地理院（GSI）基盤地図情報中的海岸线数据，作为日本全国海陆边界与硬阻塞判定的基础真值源。
- 该数据可区分部分海岸线形态，例如通常部、岩等接触部分、堤防等接触部分。

但仅靠海岸线数据，不能可靠区分：
- 港口区域内岸线
- 普通自然海岸线
- 商港/渔港/人工港湾周边可航行与受限水域

因此本任务单独建立“港湾区域叠加判定”模块，用于在既有海岸线硬阻塞格网基础上，叠加港湾区域、港域边界、人工岸线邻接关系，并生成供路由系统使用的港湾语义标签与分级栅格。

---

## 本任务目标
构建一套日本全国统一的“港湾区域叠加判定”预处理流水线，实现：

1. 将港湾区域数据导入并标准化。
2. 与 GSI 海岸线数据进行空间叠加。
3. 对海岸线附近及水域格子进行港湾语义分类。
4. 输出可供 NavSea 路由层直接读取的分级格网标签。
5. 支持不同区域精度策略：
   - 基础全国海域：200m × 200m
   - 港湾/近岸重点区：50m × 50m
   - 外海区域：50m × 50m（按用户当前要求执行）

> 注意：本任务不负责显示层渲染，不修改 MapLibre 显示瓦片，不直接修改现有海图展示流程。

---

## 用户要求（必须满足）

### 1. 语义要求
必须能区分至少以下类别：
- 普通海岸线附近水域
- 港湾区域内水域
- 港湾区域内人工岸线邻近水域
- 港湾边界邻近过渡水域
- 无法判定区域

### 2. 精度要求
必须支持分级网格：
- 日本全国基础层：`200m x 200m`
- 港湾重点层：`50m x 50m`
- 外海区域：`50m x 50m`

### 3. 架构要求
必须遵守 NavSea V11 与 codex6 协作规则：
- 不破坏既有架构边界
- 不把显示层 MVT/PBF 直接当作路由真值源
- 新增能力应作为独立预处理模块接入
- 输出独立路由底库，不污染显示数据

---

## 数据来源

### A. 主海岸线真值源
GSI 基盤地図情報（海岸線）
- C09-06.zip 和 C02-08.zip 港湾和渔港

用途：
- 海陆边界
- 海岸线类型辅助判定
- 人工岸线/自然岸线邻接判断

### B. 港湾语义源
国土数值信息（KSJ）港湾データ

用途：
- 港湾区域
- 港域边界线
- 港湾名
- 港湾种别
- 管理属性（若可用）

### C. 可选补充源
仅在后续验证确有需要时引入：
- 渔港数据
- 河口・運河相关数据
- 港内限制区/航路数据
- NavSea 现有矢量瓦片中的 harbour / pier / breakwater / seawall 图层

> 原则：GSI/KSJ 优先作为判定真值，MapLibre MVT 仅作补充，不反客为主。

---

## 最终输出目标

输出一套供 NavSea 路由模块使用的“港湾区域叠加语义格网”。

### 目标输出一：统一分类格网
每个格子至少要包含以下字段：

```ts
export type PortOverlayCell = {
  gridLevel: 50 | 200;
  cellId: string;
  bbox: [number, number, number, number];
  insidePortArea: boolean;
  nearPortBoundary: boolean;
  nearArtificialCoast: boolean;
  nearGeneralCoast: boolean;
  classification:
    | "PORT_WATER"
    | "PORT_COAST"
    | "GENERAL_COAST"
    | "PORT_TRANSITION"
    | "OPEN_WATER"
    | "UNKNOWN";
  sourceMask: number;
  confidence: number;
};
```

### 目标输出二：供路由使用的轻量索引
建议生成：
- `routing-port-overlay-japan-v1.bin`
- `routing-port-overlay-japan-v1.index.json`
- 或按区域分块的二进制 tile/chunk 文件

### 目标输出三：验证样本
至少输出以下区域的可视化验证结果：
- 东京湾
- 大阪湾
- 濑户内海重点港区
- 北海道沿岸样本区

---

## 核心判定模型

### 一、基础分类目标
必须至少实现以下 6 类：

```text
PORT_WATER        港湾区域内一般水域
PORT_COAST        港湾区域内且邻近人工岸线/码头/护岸的水域或格子
GENERAL_COAST     非港湾区域、邻近普通海岸线的水域或格子
PORT_TRANSITION   港湾边界附近过渡水域
OPEN_WATER        不属于港湾、也不邻近海岸线的开放水域
UNKNOWN           数据缺失或冲突无法可靠判定
```

### 二、建议判定逻辑

```text
1. 若格子与港湾区域面相交：
   -> insidePortArea = true

2. 若格子落入港湾边界线缓冲区：
   -> nearPortBoundary = true

3. 若格子与 GSI 海岸线相邻，且岸线类型为“堤防等接触部分”或其他人工岸线代理：
   -> nearArtificialCoast = true

4. 若格子与 GSI 海岸线相邻，且岸线类型为通常部/岩等接触部分：
   -> nearGeneralCoast = true
```

### 三、建议分类优先级

```text
if insidePortArea && nearArtificialCoast:
    classification = PORT_COAST
elif insidePortArea:
    classification = PORT_WATER
elif nearPortBoundary:
    classification = PORT_TRANSITION
elif nearGeneralCoast:
    classification = GENERAL_COAST
elif not nearGeneralCoast && not insidePortArea:
    classification = OPEN_WATER
else:
    classification = UNKNOWN
```

---

## 分级栅格策略（必须执行）

本任务必须采用分级网格，不允许全国只用单一粒度。

### Level 1：全国基础层
- 网格尺寸：`200m x 200m`
- 用途：全国范围初步港湾语义覆盖
- 主要服务：大范围路由预筛选、低成本索引

### Level 2：重点精细层
- 网格尺寸：`50m x 50m`
- 必须覆盖：
  - 港湾区域
  - 港湾边界缓冲区
  - 海岸线缓冲区
  - 外海区域（按当前用户要求）

### 精细层触发规则
建议任一满足即进入 50m 层：
- 进入港湾区域
- 距离港湾边界小于设定阈值
- 距离海岸线小于设定阈值
- 属于外海区域

### 注意
外海区域 50m × 50m 将显著增加数据量和预处理成本。
因此实现上必须支持：
- 分块构建
- 分块存储
- 区域化加载
- 不能假设全部一次性常驻内存

---

## 空间处理建议

### 1. 投影要求
不得直接在经纬度下用固定度数近似米网格。
必须先转换到米制投影后生成格网。

建议方案：
- 统一米制投影方案
- 或按区域分带处理后落格

### 2. 缓冲区建议
建议至少配置以下缓冲：
- 港湾边界缓冲区
- 海岸线邻接缓冲区
- 人工岸线增强缓冲区

缓冲值不要写死在代码中，必须参数化。

### 3. 判定方式
不允许只使用“格子中心点落入关系”完成判定。
必须支持至少一种更稳妥方法：
- 面积相交比例
- 最短距离
- 缓冲后相交

建议组合：
- 面相交用于区域类判断
- 距离判断用于边界/邻接类判断

---

## 输出标记建议

### A. 供规则引擎读取的主分类
```ts
export type PortOverlayClass =
  | "PORT_WATER"
  | "PORT_COAST"
  | "GENERAL_COAST"
  | "PORT_TRANSITION"
  | "OPEN_WATER"
  | "UNKNOWN";
```

### B. 供路由代价层使用的附加标签
```ts
export type PortOverlayFlags = {
  insidePortArea: boolean;
  nearPortBoundary: boolean;
  nearArtificialCoast: boolean;
  nearGeneralCoast: boolean;
  highConfidence: boolean;
};
```

### C. 供代价映射使用的建议
```text
PORT_COAST      -> 高代价或半禁行
PORT_WATER      -> 中高代价
PORT_TRANSITION -> 中代价
GENERAL_COAST   -> 中高代价
OPEN_WATER      -> 低代价
UNKNOWN         -> 高代价或待人工确认
```

> 本任务只负责语义输出，不在此任务中写死最终寻路代价函数。

---

## 推荐目录结构（建议，不强制）

```text
navsea/
  tools/
    port-overlay-grid-builder/
      README.md
      src/
        loaders/
        normalizers/
        classifiers/
        grid/
        exporters/
      config/
      samples/
  data/
    source/
      gsi/
      ksj/
    derived/
      routing-grids/
      validation/
```

---

## 模块边界

### 本任务负责
- 港湾数据读取
- 港湾区域标准化
- 与海岸线叠加
- 分级格网生成
- 分类输出
- 验证样本输出

### 本任务不负责
- MapLibre 地图显示改造
- 实时路径搜索算法本体
- UI 呈现
- 航道/水深/桥净空等其他语义融合

---

## 开发阶段拆分

### Phase 1：数据审计与标准化
目标：确认 GSI + KSJ 的字段结构与可用于判定的关键属性。

交付物：
- 数据字段审计报告
- 统一内部字段映射表
- 样本区域导入脚本

### Phase 2：空间叠加与分类规则实现
目标：实现港湾区域、港湾边界、海岸线邻接的空间判定。

交付物：
- 叠加模块
- 分类模块
- 样本区验证输出

### Phase 3：分级格网与导出
目标：生成 200m/50m 双层格网输出，并提供路由可读索引。

交付物：
- 二进制或分块索引输出
- 校验脚本
- 抽样验证报告

### Phase 4：NavSea 接入准备
目标：定义与现有 routing 模块的接入边界。

交付物：
- 接口约定文档
- 数据版本规则
- 后续融合任务建议

---

## 验收标准

### 必须通过
1. 能正确导入并读取 GSI 海岸线与 KSJ 港湾数据。
2. 能完成港湾区域与海岸线的空间叠加。
3. 能输出六类基础分类结果。
4. 能生成 200m 与 50m 两级格网。
5. 能在东京湾与大阪湾样本区输出可人工核查结果。
6. 输出结构可被后续路由模块直接消费。

### 不通过条件
以下任一成立则视为未完成：
- 仅使用中心点判定
- 未支持 50m 精细层
- 未把港湾区域与普通海岸语义分开
- 结果仍依赖 MapLibre MVT 在线查询
- 输出格式不能稳定复现

---

## 风险与注意事项

### 1. 港湾数据边界语义可能与显示地图不完全一致
必须以预处理真值源为准，不以显示层瓦片视觉效果为准。

### 2. 50m 全覆盖数据量会很大
必须分块，不得设计为一次性全量内存方案。

### 3. 人工岸线识别可能并不完全等于码头语义
本任务先实现“人工岸线邻近”判定，不夸大为“所有码头设施已识别”。

### 4. UNKNOWN 不能被默认为 OPEN_WATER
对无法确定区域，默认应保守处理。

---

## 与已有任务关系
本任务是以下任务的扩展任务：
- 日本全国海岸线硬阻塞栅格生成任务

关系说明：
- 前任务解决“海陆边界与硬阻塞真值”
- 本任务解决“港湾区域语义与海岸线语义叠加”
- 后续可继续扩展到：
  - 水深层
  - 航道层
  - 港内限制区
  - 桥净空层
  - 养殖区层

---

## Codex 执行要求

### 必须遵守
1. 所有新文件必须符合 NavSea V11 / codex6 规范。
2. 新建 `.ts/.tsx` 文件时，必须包含项目约定的 logger 初始化。
3. 不允许臆测未知项目结构。
4. 新文件由 AI 提供文件路径和完整代码。
5. 修改旧文件前，必须先由用户提供原文件内容，再返回完整替换版本。
6. 不引入未知依赖，不擅自改变既有模块边界。

### 输出要求
后续进入编码阶段时，AI 必须：
- 明确文件路径
- 提供完整替换内容
- 在文件头加入清晰版本标注
- 保持可直接复制使用

---

## 建议后续子任务
1. 港湾数据字段审计任务
2. 海岸线类型归一化任务
3. 50m/200m 分级格网生成器任务
4. 港湾叠加分类器任务
5. 港湾语义验证样本导出任务
6. Routing 消费接口定义任务

---

## 一句话定义
本任务的目标不是“在地图上看起来像港口”，而是：

**基于官方海岸线与港湾区域数据，为 NavSea 构建可用于路由判断的港湾语义分级格网。**