167 lines
7.3 KiB
Markdown
167 lines
7.3 KiB
Markdown
# AT Transit — Full Stack
|
|
|
|
ระบบค้นเส้นทางรถโดยสาร / ตู้รถ / จุดจอด ภาคใต้
|
|
Postgres (PostGIS + JSONB) · SeaweedFS · Rust + Axum · Next.js · nginx
|
|
|
|
## เริ่มต้นใช้งานเร็วสุด
|
|
|
|
```bash
|
|
cd web-at-transit
|
|
cp .env.example .env # ตรวจ SQL_DB_PASSWORD ฯลฯ
|
|
docker compose up --build
|
|
```
|
|
|
|
ตัวอย่าง endpoint:
|
|
- หน้าเว็บ: <http://localhost:8000>
|
|
- API: <http://localhost:8000/api/route-groups>
|
|
- ไฟล์ที่อัปโหลด: <http://localhost:8000/files/...>
|
|
|
|
## Deploy บน Dokploy
|
|
|
|
ถ้า deploy ผ่าน Dokploy และแยก `backend` กับ `frontend` เป็นคนละ service:
|
|
|
|
- อย่าใช้โหมด `Docker Stack` / `Swarm`
|
|
- ให้ใช้ service แบบ `Dockerfile` หรือ `Image`
|
|
- backend ใช้ build context `backend/` และ Dockerfile `backend/Dockerfile`
|
|
- frontend ใช้ build context `frontend/` และ Dockerfile `frontend/Dockerfile`
|
|
|
|
สาเหตุของ error นี้:
|
|
|
|
```text
|
|
This node is not a swarm manager
|
|
```
|
|
|
|
คือ Dokploy กำลังพยายาม deploy แบบ Swarm (`docker stack` / `docker service`) แต่เครื่อง target ไม่ได้เปิด Swarm manager และ repo นี้ไม่ได้ต้องการ Swarm
|
|
|
|
### Backend service
|
|
|
|
ตั้งค่า internal port เป็น `8080`
|
|
|
|
env ที่ต้องมี:
|
|
|
|
```bash
|
|
SQL_DB_URL=postgres://itmeadmin:Admin%40Pass001%23%21@infra-postgres:5432/at-transit
|
|
STORAGE_URL=http://seaweed-filer:8888
|
|
STORAGE_BUCKET=transit
|
|
STORAGE_PUBLIC_BASE=/files
|
|
BIND_ADDR=0.0.0.0:8080
|
|
RUST_LOG=info,sqlx=warn,tower_http=info
|
|
CORS_ALLOW_ORIGINS=https://<your-frontend-domain>
|
|
SEED_ASSETS_DIR=/seed-assets
|
|
```
|
|
|
|
ถ้าจะ mount รูป seed ให้ mount path `storage/seed-assets` ไปที่ `/seed-assets` แบบ read-only
|
|
|
|
### Frontend service
|
|
|
|
ตั้งค่า internal port เป็น `3000`
|
|
|
|
build args / env ที่ต้องมี:
|
|
|
|
```bash
|
|
NEXT_PUBLIC_API_BASE=/api
|
|
NEXT_PUBLIC_FILE_BASE=/files
|
|
INTERNAL_API_BASE=http://<backend-service-name>:8080/api
|
|
BACKEND_INTERNAL_URL=http://<backend-service-name>:8080
|
|
STORAGE_INTERNAL_URL=http://seaweed-filer:8888
|
|
STORAGE_BUCKET_PATH=/buckets/transit
|
|
PORT=3000
|
|
```
|
|
|
|
ถ้ามี reverse proxy หน้า Dokploy ให้ route:
|
|
|
|
- `/api` ไป backend
|
|
- `/files` ไป backend
|
|
- `/` ไป frontend
|
|
|
|
## โครงสร้างโฟลเดอร์
|
|
|
|
```
|
|
app/
|
|
├─ docker-compose.yml 5 services: db, seaweedfs, backend, frontend, proxy
|
|
├─ nginx.conf reverse-proxy + /files cache 1 ปี
|
|
├─ backend/ Rust + Axum + SQLx (1 endpoint = 1 folder)
|
|
│ └─ src/api/<endpoint>/{mod,dto,repo,service,handler}.rs
|
|
├─ frontend/ Next.js App Router + react-leaflet
|
|
└─ storage/seed-assets/ วางรูปเพื่อ ingest ครั้งแรกอัตโนมัติ
|
|
```
|
|
|
|
## Backend ↔ Frontend แยกขาด
|
|
|
|
ทั้งสองฝั่งถูกแยก codebase, Dockerfile, และ env
|
|
และ "คุย" กันด้วย REST JSON ผ่าน nginx เท่านั้น
|
|
ไม่มีการแชร์โค้ดหรือ type ระหว่างกัน (frontend ประกาศ type ใน `src/lib/api.ts` ตาม contract)
|
|
|
|
## Endpoint Map (15 เส้น)
|
|
|
|
| Method | Path | Folder |
|
|
|--------|------|--------|
|
|
| GET | `/api/provinces` | `list_provinces` |
|
|
| GET | `/api/route-groups` | `list_route_groups` |
|
|
| GET | `/api/routes?group=&province=` | `list_routes` |
|
|
| GET | `/api/routes/:route_id` | `get_route` |
|
|
| GET | `/api/routes/:route_id/stops` | `list_route_stops` |
|
|
| GET | `/api/stops?bbox=&q=` | `list_stops` |
|
|
| GET | `/api/stops/:stop_code` | `get_stop` |
|
|
| GET | `/api/schedules?route_id=&stop_id=&stop_code=` | `list_schedules` |
|
|
| POST | `/api/images` (multipart) | `upload_image` |
|
|
| GET | `/api/images?entity_type=&entity_id=` | `list_images` |
|
|
| DELETE | `/api/images/:id` | `delete_image` |
|
|
| GET | `/files/*path` | `proxy_file` |
|
|
| POST | `/api/visits` | `record_visit` |
|
|
| GET | `/api/visits/summary` | `get_visits_summary` |
|
|
| GET | `/api/visits/by-page?path=&since=` | `get_visits_by_page` |
|
|
|
|
## JSONB Field Guide
|
|
|
|
| ตาราง | คอลัมน์ | ตัวอย่างคีย์ |
|
|
|------|--------|-------------|
|
|
| `routes` | `contact` | `phones[{label,number}]`, `email`, `line_id`, `office_hours` |
|
|
| `routes` | `metadata` | `headway_minutes`, `first_departure`, `last_departure`, `fare_baht`, `notes`, `tags[]` |
|
|
| `stations` | `attributes` | `has_ticketing`, `has_restroom`, `cover_type`, `landmark_note` |
|
|
| `stations` | `metadata` | `alias_names[]`, `nearest_landmark`, `accessibility` |
|
|
| `schedules` | `variants` | `weekday_only`, `weekend_only`, `holiday_only`, `notes` |
|
|
| `images` | `meta` | `mime`, `size_bytes`, `width`, `height`, `alt_th`, `sha256`, `pending_gc` |
|
|
| `sponsors` | `meta` | `description_th`, `tier`, `display_url` |
|
|
|
|
ทุกคอลัมน์ JSONB มี GIN `jsonb_path_ops` index สำหรับ `@>` / `@?` queries.
|
|
|
|
## วิธีอัปโหลดรูป
|
|
|
|
หนึ่ง multipart POST:
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8000/api/images \
|
|
-F entity_type=route \
|
|
-F entity_id=SU01 \
|
|
-F kind=photo \
|
|
-F alt_th="รถตู้สาย SU01" \
|
|
-F display_order=0 \
|
|
-F file=@/path/to/photo.jpg
|
|
```
|
|
|
|
ระบบจะ:
|
|
1. ส่งไฟล์ไป SeaweedFS filer (`/buckets/transit/<entity_type>/<entity_id>/<filename>`)
|
|
2. ตรวจขนาดภาพด้วย crate `image` (width/height) และคำนวณ sha256
|
|
3. บันทึกแถวใน `transit.images` พร้อม metadata JSONB
|
|
|
|
หรือวางไฟล์ลง `storage/seed-assets/<entity_type>/<entity_id>/...`
|
|
แล้ว backend จะ ingest อัตโนมัติเมื่อ images ยังว่าง
|
|
|
|
## Flow Nodes (อ้างอิงตามจริงในโค้ด)
|
|
|
|
| โหนด | หน้า | การ action สำคัญ |
|
|
|------|------|--------------------|
|
|
| **N1** | `/` (Home) | คลิกการ์ดหมวด → `/routes?group=` · คลิกการ์ดจังหวัด → `/routes?province=` |
|
|
| **N2** | `/routes` (รายการเส้นทาง) | คลิกการ์ดเส้นทาง → `/routes/[routeId]` |
|
|
| **N3** | `/routes/[routeId]` | คลิก "ดูแบบขยาย" → `/routes/[routeId]/expanded` · คลิกชื่อจุดจอด → `/stops/[stopId]` |
|
|
| **N3b** | `/routes/[routeId]/expanded` | แกลเลอรีภาพ · เบอร์โทร · เมตาดาตา |
|
|
| **N4** | `/stops` (รายการจุดจอด + แผนที่) | popup marker → `/stops/[stopId]` · คลิกการ์ด → `/stops/[stopId]` |
|
|
| **N4b** | `/stops/[stopId]` | คลิกเส้นทาง → `/routes/[routeId]` |
|
|
|
|
ทุกหน้ายิง `POST /api/visits` ด้วย `visitor_id` UUID v4 ใน `localStorage`
|
|
|
|
## Image Flow Overview
|
|
|
|
ดูภาพรวมการไหลของหน้าและ action ทั้งหมดใน `flow-overview.md` (mermaid diagram)
|