초기 관제 시스템 뼈대 구성

README.md

@@ -0,0 +1,194 @@
+# 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>:8080
+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
+  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.