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,79 @@
+# Backend Naming Audit
+
+> 历史接口盘点，保留旧名称与修正依据。本文中的旧仓库名、URL 和替代建议不作为当前可用接口清单；现行规范见 [API 风格](../api-style.md)，实际契约见 [Server OpenAPI](../../contracts/server-v1.openapi.json)。
+
+DOC-003 audit for the internal `TJWaterServerBinary` backend.
+
+## Scope
+
+Reviewed FastAPI route decorators under `app/api/v1/endpoints`, router prefixes in `app/api/v1/router.py`, and public request/response schema fields in `app/api` and `app/domain`.
+
+The backend is mounted only under `/api/v1` from `app/main.py`; the old no-prefix router include remains commented out.
+
+## Current Good Surface
+
+These newer routes already follow the naming rule for public HTTP paths:
+
+- Metadata/admin: `/api/v1/admin/projects`, `/api/v1/admin/users/sync`, `/api/v1/admin/projects/{project_id}/members`
+- Audit: `/api/v1/audit/logs`, `/api/v1/audit/logs/count`
+- Agent auth: `/api/v1/agent/auth/context`
+- Business APIs: `/api/v1/burst-detection/detect`, `/api/v1/burst-location/locate`, `/api/v1/leakage/identify`
+- Time-series APIs: `/api/v1/scada/by-ids-time-range`, `/api/v1/scada/by-ids-field-time-range`, `/api/v1/composite/clean-scada`
+- Project data APIs: `/api/v1/scada-info`, `/api/v1/scheme-list`, `/api/v1/burst-locate-result`
+- Web integrations: `/api/v1/web-search`, `/api/v1/geocode`
+
+Path template parameters such as `{project_id}`, `{user_id}`, `{device_id}`, `{scheme_name}`, and `{link_id}` intentionally remain `snake_case`.
+
+## Legacy URL Categories
+
+### Keep With Compatibility
+
+These now have `kebab-case` aliases. The frontend has been migrated to the replacement paths; keep the old paths as deprecated compatibility aliases for Agent planning, tests, customer scripts, or external callers:
+
+| Current URL | Suggested replacement |
+| --- | --- |
+| `/api/v1/openproject/` | `/api/v1/projects/open` |
+| `/api/v1/project_info/` | `/api/v1/project-info` |
+| `/api/v1/getallschemes/` | `/api/v1/schemes` |
+| `/api/v1/getallsensorplacements/` | `/api/v1/sensor-placement-schemes` |
+| `/api/v1/sensorplacementscheme/create` | `/api/v1/sensor-placement-schemes` |
+| `/api/v1/burst_analysis/` | `/api/v1/burst-analysis` |
+| `/api/v1/valve_isolation_analysis/` | `/api/v1/valve-isolation-analysis` |
+| `/api/v1/flushing_analysis/` | `/api/v1/flushing-analysis` |
+| `/api/v1/contaminant_simulation/` | `/api/v1/contaminant-simulation` |
+| `/api/v1/runsimulationmanuallybydate/` | `/api/v1/simulations/run-by-date` |
+
+### Broad Legacy Surface
+
+These route groups expose many command-style concatenated paths. They should not be copied into new work; replace only when a caller migration is planned:
+
+- Project lifecycle: `listprojects`, `createproject`, `deleteproject`, `isprojectopen`, `closeproject`, `copyproject`, `importinp`, `exportinp`, `readinp`, `dumpinp`, `lockproject`, `unlockproject`
+- Network object CRUD: `addjunction`, `getjunctionelevation`, `setpipediameter`, `getvalvesetting`, and similar junction/pipe/pump/tank/reservoir/valve routes
+- Region/DMA/VD commands: `calculatedistrictmeteringareaforregion`, `getdistrictmeteringarea`, `generatevirtualdistrict`, and related routes
+- SCADA native CRUD: `getscadadevice`, `setscadadevicedata`, `cleanscadaelement`, and related routes
+- Snapshot/synchronization utilities: `takesnapshotforoperation`, `syncwithserver`
+- Advanced simulation endpoints with underscore paths: `pressure_regulation`, `daily_scheduling_analysis`, `network_update`, `pressure_sensor_placement_kmeans`
+
+### Direct Cleanup Candidates
+
+These are likely safe only after confirming no caller uses them:
+
+- `/api/v1/test_dict/`: development/test utility in `misc.py`.
+- `/api/v1/takenapshotforcurrentoperation`: typo compatibility path; keep deprecated if any client may still call it.
+- `/api/v1/getpumpenergyproperties//` and `/api/v1/setpumpenergyproperties//`: double-slash paths in options endpoints.
+
+## Field Naming
+
+Most public JSON, query, and SSE fields are already `snake_case`, including `project_id`, `user_id`, `scheme_name`, `scheme_type`, `start_time`, `end_time`, `device_ids`, `session_id`, and `request_id`.
+
+Known legacy exception:
+
+- `BurstAnalysis.burst_ID` in `app/api/v1/endpoints/simulation.py` should become `burst_id` on a new API contract. Preserve `burst_ID` only for the legacy body shape.
+
+Headers keep standard HTTP casing:
+
+- `X-Project-Id`
+
+## Recommendation
+
+Do not rename existing legacy routes in place. For each active legacy route, keep the new `kebab-case` alias as the documented path, keep the old route marked deprecated, migrate remaining Agent/customer/script callers, then remove only after a documented compatibility window.