refactor(frontend): normalize naming conventions

2026-06-13 13:07:16 +08:00
parent 6ff8886524
commit 0dea655f68
30 changed files with 87 additions and 33 deletions
@@ -0,0 +1,56 @@
+# Frontend Naming Audit
+
+DOC-004 audit for the internal `TJWaterFrontend_Refine` application.
+
+## Local frontend naming
+
+- Next.js route directories under `src/app` are already `kebab-case`: `audit-logs`, `health-risk-analysis`, `hydraulic-simulation`, `monitoring-place-optimization`, `network-simulation`, `scada-data-cleaning`, and `system-admin`.
+- Route groups and dynamic segments keep Next.js syntax: `(main)` and `[...nextauth]`.
+- Local ordinary module filenames now use `camelCase`, including `src/utils/breaksClassification.ts`, `src/components/chat/globalChatboxUtils.ts`, and `src/components/chat/globalChatboxVoice.ts`.
+- React component files remain `PascalCase.tsx`, including `src/app/RefineContext.tsx`, `src/components/chat/GlobalChatboxParts.tsx`, and domain directories under `src/components/olmap`.
+
+## API boundary naming
+
+Frontend request and response boundary fields intentionally keep backend/Agent wire names. Examples include `project_id`, `user_id`, `scheme_name`, `scheme_type`, `start_time`, `end_time`, `session_id`, `request_id`, and `keep_message_count`.
+
+Current direct API calls mostly use new `kebab-case` URL paths, including:
+
+- `/api/v1/admin/projects`
+- `/api/v1/audit/logs`
+- `/api/v1/projects/open`
+- `/api/v1/project-info`
+- `/api/v1/schemes`
+- `/api/v1/sensor-placement-schemes`
+- `/api/v1/burst-analysis`
+- `/api/v1/valve-isolation-analysis`
+- `/api/v1/flushing-analysis`
+- `/api/v1/contaminant-simulation`
+- `/api/v1/simulations/run-by-date`
+- `/api/v1/burst-detection/detect`
+- `/api/v1/burst-location/locate`
+- `/api/v1/scada/by-ids-field-time-range`
+- `/api/v1/composite/clean-scada`
+- `/api/v1/agent/chat/render-ref/{render_ref}`
+
+## Legacy URL inventory
+
+The frontend no longer calls these active legacy URLs directly. The backend still exposes them as deprecated compatibility aliases:
+
+| Current frontend URL | Files | Suggested target |
+| --- | --- | --- |
+| `/api/v1/openproject/` | `src/contexts/ProjectContext.tsx` | `/api/v1/projects/open` or `/api/v1/project/open` |
+| `/api/v1/project_info/` | `src/contexts/ProjectContext.tsx` | `/api/v1/project-info` |
+| `/api/v1/getallschemes/` | burst, burst simulation, contaminant, flushing scheme query components | `/api/v1/schemes` |
+| `/api/v1/getallsensorplacements/` | `src/components/olmap/MonitoringPlaceOptimization/SchemeQuery.tsx` | `/api/v1/sensor-placement-schemes` |
+| `/api/v1/sensorplacementscheme/create` | `src/components/olmap/MonitoringPlaceOptimization/OptimizationParameters.tsx` | `/api/v1/sensor-placement-schemes` |
+| `/api/v1/burst_analysis/` | `src/components/olmap/BurstSimulation/AnalysisParameters.tsx` | `/api/v1/burst-analysis` |
+| `/api/v1/valve_isolation_analysis/` | `src/components/olmap/BurstSimulation/ValveIsolation.tsx` | `/api/v1/valve-isolation-analysis` |
+| `/api/v1/flushing_analysis/` | `src/components/olmap/FlushingAnalysis/AnalysisParameters.tsx` | `/api/v1/flushing-analysis` |
+| `/api/v1/contaminant_simulation/` | `src/components/olmap/ContaminantSimulation/AnalysisParameters.tsx` | `/api/v1/contaminant-simulation` |
+| `/api/v1/runsimulationmanuallybydate/` | `src/components/olmap/core/Controls/Timeline.tsx` | `/api/v1/simulations/run-by-date` |
+
+Already migrated frontend code leaves comments showing older pre-`/api/v1` URLs in `src/components/olmap/core/Controls/Toolbar.tsx`; those comments are historical only and are not active calls.
+
+## Follow-up
+
+Continue tracking broad passive legacy backend routes under the shared legacy API compatibility strategy.