docs: rewrite all documentation to reflect current state
- Remove adminer references (service was removed) - Remove mermaid diagrams (ASCII only) - Remove hardcoded credentials (use env var references) - Update all Docker references to 4-container setup (app, postgres, web, pgadmin) - Document env-based admin credentials (ADMIN_EMAIL/ADMIN_PASSWORD) - Document parameterized queries (SQL injection fixed) - Document FCM topic routing by stationtype+level - Document siren stationtype=3 fix in sidesdecode.py - Document idempotent seeder (firstOrCreate) - Document reverse proxy setup in deployment guide - Remove Makefile references (Docker Compose only)
This commit is contained in:
root
@@ -1,203 +1,150 @@
|
||||
<!-- generated-by: gsd-doc-writer -->
|
||||
# Features & User Guide
|
||||
|
||||
## Feature Overview
|
||||
|
||||
SIDES provides the following feature areas:
|
||||
SIDES provides a web-based dashboard for monitoring rainfall, water levels, and siren activations at telemetry stations in the Sungai Kupang catchment. Features are grouped by access level: public pages (no login), authenticated user pages, admin-only management, and a REST API.
|
||||
|
||||
### 1. Public Dashboard (Map View)
|
||||
---
|
||||
|
||||
**Route**: `/` or `/dashboard`
|
||||
**Access**: Public (no auth required)
|
||||
**Controller**: `MapController::getCurrentData()`
|
||||
## Public Pages
|
||||
|
||||
Displays an interactive Leaflet.js map showing all monitoring stations with their current readings:
|
||||
- Station markers color-coded by status
|
||||
- Popup showing latest rainfall, water level, and siren data
|
||||
- Real-time station data from PostgreSQL
|
||||
These pages are accessible without authentication.
|
||||
|
||||
### 2. Rainfall Monitoring
|
||||
### Dashboard (Map View)
|
||||
|
||||
**Route**: `/rainfall`
|
||||
**Access**: Authenticated users
|
||||
**Controller**: `RainfallController::index()`
|
||||
| Route | Description |
|
||||
|---|---|
|
||||
| `GET /` or `GET /dashboard` | Interactive map powered by Leaflet.js. Displays all telemetry stations with their latest sensor readings. Served by `MapController`. |
|
||||
| `GET /stations` | Returns a JSON list of stations and current readings. Used by the map to populate markers. |
|
||||
| `GET /locale/{locale}` | Switches the application language. Supports `en` (English) and `bm` (Bahasa Malaysia). |
|
||||
|
||||
- Table showing rainfall data for all rainfall-enabled stations
|
||||
- Filter by station and date
|
||||
- Displays: hourly, daily, and 7-day historical values
|
||||
- Last data update timestamp
|
||||
---
|
||||
|
||||
### 3. Rainfall Graph
|
||||
## Authenticated User Pages
|
||||
|
||||
**Route**: `/rainfall/graph/{stationid}`
|
||||
**Access**: Authenticated users
|
||||
**Controller**: `RainfallController::rainfallGraph()`
|
||||
All routes below require a logged-in session (Laravel `auth` middleware).
|
||||
|
||||
- Interactive chart showing hourly rainfall for the selected station today
|
||||
- X-axis: time (HH:MM), Y-axis: rainfall value
|
||||
### General
|
||||
|
||||
### 4. Early Warning Threshold (IDF)
|
||||
| Route | Description |
|
||||
|---|---|
|
||||
| `GET /home` | Home page shown after login. |
|
||||
|
||||
**Route**: `/threshold`
|
||||
**Access**: Authenticated users
|
||||
**Controller**: `RainfallController::rainfallSum()`
|
||||
### Rainfall Monitoring
|
||||
|
||||
- 6-hour cumulative rainfall data for early warning
|
||||
- Shows hourly values and timestamps for each of the last 6 hours
|
||||
- Filter by station and date
|
||||
- Threshold graph data available via API
|
||||
| Route | Description |
|
||||
|---|---|
|
||||
| `GET /rainfall` | Tabular view of rainfall data with filters for station and date range. |
|
||||
| `GET /rainfall/graph/{stationid}` | Hourly rainfall chart for a specific station. |
|
||||
| `GET /rainfall/historical` | Historical hourly rainfall data (24 readings per day) with export option. |
|
||||
| `GET /rainfall/historical/export` | Exports historical rainfall data to an Excel file. |
|
||||
|
||||
### 5. Historical Rainfall
|
||||
### Water Level Monitoring
|
||||
|
||||
**Route**: `/rainfall/historical`
|
||||
**Access**: Authenticated users
|
||||
**Controller**: `RainfallController::historicalRainfall()`
|
||||
| Route | Description |
|
||||
|---|---|
|
||||
| `GET /waterlevel` | Current water level readings in a filterable table. |
|
||||
| `GET /waterlevel/graph/{stationid}` | Water level chart for a specific station. |
|
||||
| `GET /waterlevel/historical` | Historical water level data with threshold lines and export option. |
|
||||
| `GET /waterlevel/historical/export` | Exports historical water level data to an Excel file. |
|
||||
|
||||
- Detailed hourly rainfall breakdown (24 hours per row)
|
||||
- Filter by station and date range
|
||||
- Shows total 24h rainfall per day
|
||||
- **Export to Excel**: `/rainfall/historical/export`
|
||||
### Threshold & Early Warning
|
||||
|
||||
### 6. Water Level Monitoring
|
||||
| Route | Description |
|
||||
|---|---|
|
||||
| `GET /threshold` | 6-hour cumulative rainfall summary used for early warning (IDF-based). |
|
||||
| `GET /threshold/graphData/{stationid}/{dates}` | Returns threshold graph data for a station and date range. |
|
||||
|
||||
**Route**: `/waterlevel`
|
||||
**Access**: Authenticated users
|
||||
**Controller**: `WaterLevelController::index()`
|
||||
### Siren Status
|
||||
|
||||
- Table showing current water level readings
|
||||
- Displays: water level value, alert/warning/danger thresholds
|
||||
- Filter by station and date
|
||||
- Interactive water level graph
|
||||
| Route | Description |
|
||||
|---|---|
|
||||
| `GET /siren` | Current siren status across all stations (last 3 days). |
|
||||
| `GET /sirenhistory` | Paginated siren history, excluding "Normal" status, with PDF export option. |
|
||||
| `GET /export/siren-history/pdf` | Exports siren history to a PDF file. |
|
||||
|
||||
### 7. Historical Water Level
|
||||
### Notifications
|
||||
|
||||
**Route**: `/waterlevel/historical`
|
||||
**Access**: Authenticated users
|
||||
**Controller**: `WaterLevelController::wlHistory()`
|
||||
| Route | Description |
|
||||
|---|---|
|
||||
| `GET /notificationrf` | Today's rainfall notifications. |
|
||||
| `GET /notificationwl` | Today's water level notifications. |
|
||||
| `GET /notificationsiren` | Today's siren notifications. |
|
||||
| `GET /historyrf` | Historical rainfall notifications with PDF export. |
|
||||
| `GET /historywl` | Historical water level notifications with PDF export. |
|
||||
|
||||
- Hourly water level data for a selected station and date
|
||||
- Shows threshold levels alongside actual readings
|
||||
- **Export to Excel**: `/waterlevel/historical/export`
|
||||
### CCTV & Profile
|
||||
|
||||
### 8. Siren Monitoring
|
||||
| Route | Description |
|
||||
|---|---|
|
||||
| `GET /cctv` | CCTV camera links for water level stations. |
|
||||
| `GET /profile` | User profile management (Laravel Breeze). |
|
||||
|
||||
**Route**: `/siren`
|
||||
**Access**: Authenticated users
|
||||
**Controller**: `SirenController::index()`
|
||||
---
|
||||
|
||||
- Current siren status for all siren-equipped stations
|
||||
- Shows last 3 days of siren activations
|
||||
- Siren levels: Normal (N), Warning (L), Danger (H)
|
||||
## Admin Pages
|
||||
|
||||
### 9. Siren History
|
||||
These routes require both authentication and admin privileges (`admin` middleware).
|
||||
|
||||
**Route**: `/sirenhistory`
|
||||
**Access**: Authenticated users
|
||||
**Controller**: `SirenController::SirenHistory()`
|
||||
### Station Management
|
||||
|
||||
- Paginated history of all siren activations (excluding Normal)
|
||||
- **Export to PDF**: `/export/siren-history/pdf`
|
||||
| Route | Description |
|
||||
|---|---|
|
||||
| `GET /stationmanagement` | List all stations (paginated, 5 per page). |
|
||||
| `POST /stationmanagement/store` | Add a new station. |
|
||||
| `POST /stationmanagement/{stationid}/update` | Edit an existing station. |
|
||||
| `DELETE /stationmanagement/{stationid}/delete` | Delete a station. |
|
||||
|
||||
### 10. Notifications
|
||||
### User Management
|
||||
|
||||
**Rainfall Notifications**: `/notificationrf`
|
||||
**Water Level Notifications**: `/notificationwl`
|
||||
**Siren Notifications**: `/notificationsiren`
|
||||
**Access**: Authenticated users
|
||||
**Controller**: `NotificationController`
|
||||
| Route | Description |
|
||||
|---|---|
|
||||
| `GET /usermgmt` | List all users (paginated, 5 per page). |
|
||||
| `POST /usermgmt/store` | Create a new user. |
|
||||
| `POST /usermgmt/{userid}/update` | Edit user details. |
|
||||
| `POST /usermgmt/{userid}/updatePassword` | Reset a user's password. |
|
||||
| `DELETE /usermgmt/{userid}/delete` | Delete a user. |
|
||||
|
||||
- Shows today's threshold-triggered notifications
|
||||
- Grouped by type (rainfall, water level, siren)
|
||||
---
|
||||
|
||||
### 11. Notification History
|
||||
## Authentication
|
||||
|
||||
**Rainfall History**: `/historyrf`
|
||||
**Water Level History**: `/historywl`
|
||||
**Access**: Authenticated users
|
||||
**Controller**: `NotificationController`
|
||||
Provided by Laravel Breeze with Blade views.
|
||||
|
||||
- Paginated history of all notifications
|
||||
- **Export to PDF**:
|
||||
- `/export/rainfall-history/pdf`
|
||||
- `/export/waterlevel-history/pdf`
|
||||
| Route | Description |
|
||||
|---|---|
|
||||
| `GET /login` | Login form. |
|
||||
| `POST /login` | Authenticate credentials. |
|
||||
| `GET /register` | Registration form. |
|
||||
| `POST /register` | Create a new account. |
|
||||
| `GET /forgot-password` | Request a password reset link. |
|
||||
| `POST /forgot-password` | Send the reset link email. |
|
||||
| `GET /reset-password` | Password reset form. |
|
||||
| `POST /reset-password` | Submit new password. |
|
||||
| `POST /logout` | End the session. |
|
||||
|
||||
### 12. CCTV Links
|
||||
---
|
||||
|
||||
**Route**: `/cctv`
|
||||
**Access**: Authenticated users
|
||||
**Controller**: `cctvController::index()`
|
||||
## API Endpoints
|
||||
|
||||
- Lists stations with CCTV links (where `cctv_link` is not null and `waterlevel = 1`)
|
||||
- Links open external CCTV feeds
|
||||
All API endpoints are unauthenticated except `/api/login` which validates credentials.
|
||||
|
||||
### 13. Admin: Station Management
|
||||
### Data Retrieval
|
||||
|
||||
**Route**: `/stationmanagement`
|
||||
**Access**: Admin only (`access_level = 1`)
|
||||
**Controller**: `AdminController`
|
||||
| Method | Endpoint | Description |
|
||||
|---|---|---|
|
||||
| GET | `/api/station/current` | Current station readings. |
|
||||
| GET | `/api/station/rainfall` | Rainfall data. |
|
||||
| GET | `/api/station/waterlevel` | Water level data. |
|
||||
| GET | `/api/station/notification` | Latest notifications. |
|
||||
| GET | `/api/station/history` | Historical data. |
|
||||
| GET | `/api/station/siren` | Current siren status. |
|
||||
| GET | `/api/station/siren/history` | Siren history. |
|
||||
|
||||
- List all stations (paginated, 5 per page)
|
||||
- Add new station
|
||||
- Edit station details (name, district, coordinates, type flags, CCTV link)
|
||||
- Delete station
|
||||
- Shows station type counts (rainfall, water level, siren)
|
||||
### Actions
|
||||
|
||||
### 14. Admin: User Management
|
||||
|
||||
**Route**: `/usermgmt`
|
||||
**Access**: Admin only
|
||||
**Controller**: `AdminController`
|
||||
|
||||
- List all users (paginated, 5 per page)
|
||||
- Add new user
|
||||
- Edit user details (name, email, access level, block/unblock)
|
||||
- Reset user password
|
||||
- Delete user
|
||||
- Shows user counts by role
|
||||
|
||||
### 15. API Endpoints
|
||||
|
||||
**Prefix**: `/api/`
|
||||
**Auth**: Custom login (no token-based auth)
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
|----------|--------|-------------|
|
||||
| `/api/station/current` | GET | All stations with current data |
|
||||
| `/api/station/rainfall` | GET | Current rainfall data per station |
|
||||
| `/api/station/waterlevel` | GET | Current water level data per station |
|
||||
| `/api/station/notification` | GET | Today's notifications per station |
|
||||
| `/api/station/history` | GET | 3-day notification history |
|
||||
| `/api/station/siren` | GET | Current siren status |
|
||||
| `/api/station/siren/history` | GET | 3-day siren history |
|
||||
| `/api/login` | POST | Login (username + password) |
|
||||
| `/api/alert` | POST | Send FCM push notification |
|
||||
|
||||
### 16. Profile Management
|
||||
|
||||
**Route**: `/profile`
|
||||
**Access**: Authenticated users
|
||||
**Controller**: `ProfileController` (Breeze scaffold)
|
||||
|
||||
- Update name and email
|
||||
- Update password
|
||||
- Delete account
|
||||
|
||||
### 17. Localization
|
||||
|
||||
**Route**: `/locale/{locale}`
|
||||
**Access**: Public
|
||||
**Controller**: `LocaleController`
|
||||
|
||||
- Switch between English (`en`) and Bahasa Malaysia (`bm`)
|
||||
- Persisted in session
|
||||
- Applied via `LocalizationMiddleware` on every request
|
||||
|
||||
### 18. Authentication
|
||||
|
||||
**Routes**: `/login`, `/register`, `/forgot-password`, `/reset-password`
|
||||
**Access**: Guest only (for login/register)
|
||||
**Scaffold**: Laravel Breeze
|
||||
|
||||
- Email/password authentication
|
||||
- Password reset via email (Gmail SMTP)
|
||||
- Email verification
|
||||
- Session-based auth
|
||||
| Method | Endpoint | Description |
|
||||
|---|---|---|
|
||||
| POST | `/api/login` | Validates user credentials. |
|
||||
| POST | `/api/alert` | Submits an alert. |
|
||||
|
||||
Reference in New Issue
Block a user