feat(investigation): preserve cumulative reference graphs

Accumulate investigation paths and preserve failed attempts across rounds. Keep graph annotations separate from execution state, synchronize the API contract, and consolidate documentation.
2026-11-11 19:10:41 +08:00
parent e47c61c121
commit b853b61a0b
38 changed files with 2445 additions and 147 deletions
@@ -0,0 +1,78 @@
+# `app/api/v1/endpoints/` 失效 API 排查与修正
+
+> 历史接口盘点，保留旧名称与修正依据。本文中的旧仓库名、URL 和替代建议不作为当前可用接口清单；现行规范见 [API 风格](../api-style.md)，实际契约见 [Server OpenAPI](../../contracts/server-v1.openapi.json)。
+
+排查范围：`app/api/v1/endpoints/`
+
+结论：本次共确认 5 个问题接口，处理结果如下：
+
+- **已删除 4 个未实现坏接口**
+- **已修正 1 个签名失配接口**
+
+> 路由统一前缀来自 `app/main.py:71`，以下完整路径均以 `/api/v1` 开头。
+
+## 处理结果
+
+| Method | API | 原问题 | 处理结果 |
+| --- | --- | --- | --- |
+| GET | `/api/v1/calculateregion/` | 调用时 `NameError`，底层无 `calculate_region` 实现 | **已删除** |
+| GET | `/api/v1/getallregions/` | 调用时 `NameError`，底层无 `get_all_regions` 实现 | **已删除** |
+| POST | `/api/v1/generateregion/` | 调用时 `NameError`，底层无 `generate_region` 实现 | **已删除** |
+| GET | `/api/v1/calculatedistrictmeteringarea/` | 调用时 `NameError`，仍指向已废弃旧 DMA 入口 | **已删除** |
+| GET | `/api/v1/calculateservicearea/` | endpoint 传 `time_index`，实现只接受 `name` | **已修正**，现返回全部时间步结果 |
+
+## 删除原因
+
+### 1. region 相关 3 个接口
+
+以下能力在当前 `wndb` / `tjnetwork` 中均不存在：
+
+- `calculate_region`
+- `get_all_regions`
+- `generate_region`
+
+`app/native/wndb/__init__.py` 当前只提供 region CRUD 和 util 能力，不提供 region 计算或批量查询能力。因此这 3 个接口继续保留只会在运行时失败。
+
+### 2. DMA 旧入口
+
+旧接口 `calculate_district_metering_area(...)` 已不存在，当前只保留 3 个明确变体：
+
+- `/api/v1/calculatedistrictmeteringareafornodes/`
+- `/api/v1/calculatedistrictmeteringareaforregion/`
+- `/api/v1/calculatedistrictmeteringareafornetwork/`
+
+因此旧入口 `/api/v1/calculatedistrictmeteringarea/` 已删除，避免前端继续误用历史接口。
+
+## 修正内容
+
+### `GET /api/v1/calculateservicearea/`
+
+原接口问题：
+
+- endpoint 定义保留 `time_index`
+- 实际实现 `calculate_service_area(name)` 只接收 `network/name`
+- 调用时会触发参数数量不匹配
+
+本次修正后：
+
+- 移除 `time_index` 查询参数
+- 返回类型改为 `list[dict[str, list[str]]]`
+- 接口语义改为：**返回全部时间步的服务区计算结果**
+
+## 当前可用替代接口
+
+DMA 计算请使用：
+
+- `/api/v1/calculatedistrictmeteringareafornodes/`
+- `/api/v1/calculatedistrictmeteringareaforregion/`
+- `/api/v1/calculatedistrictmeteringareafornetwork/`
+
+服务区计算请使用：
+
+- `/api/v1/calculateservicearea/`
+  现在返回全部时间步结果，不再接收 `time_index`
+
+## 变更文件
+
+- `app/api/v1/endpoints/network/regions.py`
+- `失效API排查.md`