78 lines
4.3 KiB
Markdown
78 lines
4.3 KiB
Markdown
# Backend Naming Audit
|
|
|
|
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/cache utilities: `takesnapshotforoperation`, `syncwithserver`, `clearrediskey`, `queryredis`
|
|
- 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.
|