199 lines
4.1 KiB
Markdown
199 lines
4.1 KiB
Markdown
# CargoRadar
|
|
|
|
CargoRadar is an MVP for tracking freight drivers from an Android app and
|
|
monitoring their latest positions from a web control screen.
|
|
|
|
## Current Shape
|
|
|
|
- `apps/server`: Node.js API server with no external runtime dependencies.
|
|
- `apps/web`: Static control web UI served by the API server.
|
|
- `apps/android`: Kotlin Android driver-app skeleton.
|
|
- `runtime-data`: Docker runtime data directory, created on first run.
|
|
|
|
## Run Locally
|
|
|
|
If Node.js is installed:
|
|
|
|
```powershell
|
|
node apps/server/src/server.js
|
|
```
|
|
|
|
Open:
|
|
|
|
```text
|
|
http://localhost:8080
|
|
```
|
|
|
|
The web screen has a `샘플 위치` button that posts a demo location with the
|
|
default `demo-token`.
|
|
|
|
## Run With Docker
|
|
|
|
```powershell
|
|
copy .env.example .env
|
|
docker compose up --build
|
|
```
|
|
|
|
Open:
|
|
|
|
```text
|
|
http://localhost:8080
|
|
```
|
|
|
|
On Synology NAS, the same `docker-compose.yml` can be used through Container
|
|
Manager or SSH. Keep `runtime-data` mounted so driver tokens and location
|
|
history survive container restarts.
|
|
|
|
For NAS, use `.env.nas.example` as the starting point and prefer port `18081`
|
|
behind Synology Reverse Proxy.
|
|
|
|
## Maintenance Scripts
|
|
|
|
Check server status:
|
|
|
|
```powershell
|
|
.\scripts\health-check.ps1 -BaseUrl "http://127.0.0.1:8080"
|
|
```
|
|
|
|
Send a demo location:
|
|
|
|
```powershell
|
|
.\scripts\post-demo-location.ps1 -BaseUrl "http://127.0.0.1:8080"
|
|
```
|
|
|
|
Back up runtime data:
|
|
|
|
```powershell
|
|
.\scripts\backup-runtime-data.ps1
|
|
```
|
|
|
|
## Kakao Map
|
|
|
|
The Kakao JavaScript key has a project default in the server config. You can
|
|
override it in `.env`:
|
|
|
|
```text
|
|
KAKAO_JAVASCRIPT_KEY=<override_key>
|
|
```
|
|
|
|
The REST API key and native app key are not needed for the current web map
|
|
screen.
|
|
|
|
In Kakao Developers, register every web origin that will open the control
|
|
screen. Useful early entries are:
|
|
|
|
```text
|
|
http://localhost:8080
|
|
http://127.0.0.1:8080
|
|
http://<NAS-LAN-IP>:18081
|
|
https://<NAS-domain>
|
|
```
|
|
|
|
If the origin is missing, Kakao's map SDK can return HTTP 403 and the control
|
|
screen will show a map-key/domain warning.
|
|
|
|
## Device Token
|
|
|
|
On first server start, the server creates:
|
|
|
|
```text
|
|
runtime-data/drivers.json
|
|
```
|
|
|
|
The default driver is:
|
|
|
|
```json
|
|
{
|
|
"driverId": "demo-driver",
|
|
"name": "Demo Driver",
|
|
"vehicleNo": "SEOUL-12-3456",
|
|
"token": "demo-token",
|
|
"enabled": true
|
|
}
|
|
```
|
|
|
|
Change the token before real use.
|
|
|
|
## API
|
|
|
|
Driver management:
|
|
|
|
```text
|
|
GET /api/v1/drivers
|
|
POST /api/v1/drivers
|
|
PATCH /api/v1/drivers/:driverId
|
|
DELETE /api/v1/drivers/:driverId
|
|
```
|
|
|
|
Upload a location:
|
|
|
|
```powershell
|
|
$body = @{
|
|
driverId = "demo-driver"
|
|
vehicleNo = "SEOUL-12-3456"
|
|
latitude = 37.5665
|
|
longitude = 126.9780
|
|
accuracy = 12
|
|
speed = 42
|
|
heading = 90
|
|
cargoName = "전자부품"
|
|
cargoWeight = "1.2t"
|
|
origin = "서울 상차지"
|
|
destination = "평택 물류센터"
|
|
recordedAt = (Get-Date).ToUniversalTime().ToString("o")
|
|
} | ConvertTo-Json
|
|
|
|
Invoke-RestMethod `
|
|
-Uri "http://localhost:8080/api/v1/locations" `
|
|
-Method Post `
|
|
-Headers @{ "X-Device-Token" = "demo-token" } `
|
|
-ContentType "application/json" `
|
|
-Body $body
|
|
```
|
|
|
|
Read latest locations:
|
|
|
|
```text
|
|
GET /api/v1/locations/latest
|
|
```
|
|
|
|
Read history:
|
|
|
|
```text
|
|
GET /api/v1/locations/history?driverId=demo-driver&limit=200
|
|
```
|
|
|
|
Realtime events:
|
|
|
|
```text
|
|
GET /api/v1/events
|
|
```
|
|
|
|
## Android
|
|
|
|
Open `apps/android` in Android Studio and run the `app` module.
|
|
|
|
- Emulator server URL: `http://10.0.2.2:8080`
|
|
- Real phone server URL: `http://<NAS-or-PC-LAN-IP>:8080`
|
|
- Driver ID and device token: use the values from the web `기사` tab.
|
|
|
|
For production, use HTTPS and disable Android cleartext traffic.
|
|
|
|
## Operation Flow
|
|
|
|
1. Start the server on a PC or Synology NAS.
|
|
2. Open the control web screen.
|
|
3. Register a driver in the `기사` tab.
|
|
4. Copy that driver's token into the Android app.
|
|
5. Start tracking from the Android app.
|
|
6. Confirm the latest location in the `위치` tab.
|
|
|
|
## Next Steps
|
|
|
|
- Replace JSONL storage with PostgreSQL/PostGIS when history queries become
|
|
important.
|
|
- Expand driver/vehicle management with search and editing.
|
|
- Add route playback and detailed location history filters.
|
|
- Add route, geofence, and delayed-reception alerts.
|
|
- Add Synology reverse proxy, HTTPS, and admin authentication for deployment.
|