초기 관제 시스템 뼈대 구성

docs/ARCHITECTURE.md

@@ -0,0 +1,29 @@
+# Architecture
+
+```mermaid
+flowchart LR
+    phone["Android driver app"] -->|POST /api/v1/locations| api["CargoRadar API"]
+    api --> latest["latest-locations.json"]
+    api --> history["locations.jsonl"]
+    web["Control web"] -->|GET latest/history| api
+    api -->|SSE /api/v1/events| web
+```
+
+## MVP Data Flow
+
+1. The Android app starts a foreground location service.
+2. The service uploads location JSON with `X-Device-Token`.
+3. The server validates the token against `drivers.json`.
+4. The server stores the newest location per driver and appends history.
+5. The control web reads the latest positions and listens for SSE updates.
+
+## Storage
+
+The MVP uses simple files:
+
+- `drivers.json`: driver registry and device tokens.
+- `latest-locations.json`: current position by driver.
+- `locations.jsonl`: append-only location history.
+
+This keeps the first version easy to deploy on Synology NAS. PostgreSQL with
+PostGIS is the planned upgrade path once route/history queries become central.

docs/SYNOLOGY.md

@@ -0,0 +1,108 @@
+# Synology Deployment
+
+## Container Manager
+
+1. Copy this repository or the NAS deploy ZIP to the NAS.
+2. Extract it into a persistent folder, for example
+   `/docker/cargoradar`.
+3. Create `.env` from `.env.example`.
+4. Set `CARGORADAR_PORT` and, if needed, `ADMIN_TOKEN`.
+5. Create a Container Manager project from `docker-compose.yml`.
+6. Keep `runtime-data` mapped to persistent NAS storage.
+
+## Environment
+
+```text
+CARGORADAR_PORT=8080
+ADMIN_TOKEN=
+KAKAO_JAVASCRIPT_KEY=ea26ed8ef3cf2960e9c36f1c161dadb5
+```
+
+For NAS deployment, start from `.env.nas.example` instead. The recommended NAS
+host port is `18081` because `18080` is already forwarded for `opendaw`.
+
+```text
+CARGORADAR_PORT=18081
+ADMIN_TOKEN=change_this_admin_token
+KAKAO_JAVASCRIPT_KEY=ea26ed8ef3cf2960e9c36f1c161dadb5
+```
+
+`ADMIN_TOKEN` can stay blank during local MVP testing. For NAS exposure, set it.
+If opening the app directly by port, use:
+
+```text
+http://<NAS-LAN-IP>:18081/?adminToken=<ADMIN_TOKEN>
+```
+
+The better public route is Synology Reverse Proxy:
+
+```text
+https://cargoradar.comtropy.synology.me -> http://127.0.0.1:18081
+```
+
+## Kakao Domain Entries
+
+Register every origin that opens the control screen:
+
+```text
+http://localhost:8080
+http://127.0.0.1:8080
+http://<NAS-LAN-IP>:18081
+https://cargoradar.comtropy.synology.me
+https://<NAS-domain>
+```
+
+## Android URL
+
+On the same LAN, use:
+
+```text
+http://<NAS-LAN-IP>:18081
+```
+
+When reverse proxy and HTTPS are ready, use:
+
+```text
+https://cargoradar.comtropy.synology.me
+```
+
+## Smoke Test
+
+After deployment, run from a PC that can reach the NAS:
+
+```powershell
+.\scripts\health-check.ps1 -BaseUrl "http://<NAS-LAN-IP>:18081" -AdminToken "<ADMIN_TOKEN>"
+.\scripts\post-demo-location.ps1 -BaseUrl "http://<NAS-LAN-IP>:18081"
+```
+
+Then open the control screen and confirm that the demo location appears in the
+`위치` tab.
+
+## Local Package
+
+Create a NAS-ready ZIP from the repository root:
+
+```powershell
+.\scripts\package-nas-deploy.ps1
+```
+
+Upload the resulting `dist/cargoradar-nas-*.zip` to the NAS and extract it into
+the deployment folder.
+
+## Current Router Context
+
+Known forwarding entries:
+
+```text
+50001 -> 192.168.200.129:5000  DSM HTTP
+50002 -> 192.168.200.129:5001  DSM HTTPS
+80    -> 192.168.200.129:80    Web Station / reverse proxy
+443   -> 192.168.200.129:443   HTTPS reverse proxy
+3000  -> 192.168.200.129:3000  Gitea
+2222  -> 192.168.200.129:2222  Gitea SSH
+50022 -> 192.168.200.129:22    SSH
+18080 -> 192.168.200.129:18080 opendaw
+```
+
+Do not use `18080` for CargoRadar. Prefer a NAS-only host port such as `18081`
+and publish it through reverse proxy on `443`.