Files
sprinkler-calculation/service

service — farm-planning API (Julia + PostgreSQL)

คำนวณสูตรทั้งหมดด้วย Julia แล้วคุยกับเว็บผ่าน HTTP/JSON · สูตรชุดเดียวกับ core/*.js โดยมี golden vectors (tests/golden/vectors.json) บังคับให้สองฝั่งได้เลขตรงกัน

ต้องมีอะไรก่อน

ของ เวอร์ชัน หมายเหตุ
Julia 1.10+ winget install --id Julialang.Julia -e
PostgreSQL 14+ เครื่องนี้มี 17 อยู่แล้ว (พอร์ต 5432)

1) เตรียมฐานข้อมูล

# สร้างฐาน (ใช้ psql ของ PostgreSQL 17)
"/c/Program Files/PostgreSQL/17/bin/createdb.exe" -U postgres farm_planning
"/c/Program Files/PostgreSQL/17/bin/psql.exe" -U postgres -d farm_planning -f service/db/001_init.sql

2) ตั้งค่า

cp service/.env.example service/.env
# แล้วแก้ FARM_DB_PASSWORD ใน service/.env เอง (ห้าม commit ไฟล์นี้)

ถ้าไม่ตั้งรหัส → service ยังรันได้ แต่ ไม่บันทึกผลลง DB และ /api/v1/health จะบอกว่าฐานข้อมูลไม่ได้เชื่อม

3) ติดตั้ง dependency ของ Julia (ครั้งแรกครั้งเดียว)

julia --project=service -e 'using Pkg; Pkg.add(["HTTP","JSON3","LibPQ"])'

4) รัน

julia --project=service service/src/server.jl
# ฟังที่ http://127.0.0.1:8000

ตรวจว่าใช้งานได้:

curl -s http://127.0.0.1:8000/api/v1/health
curl -s -X POST http://127.0.0.1:8000/api/v1/waters/calculate/plant \
  -H 'Content-Type: application/json' \
  -d '{"eto_mm_per_day":3.71,"crop_coefficient":1.0,"area_rai":10,"irrigation_efficiency_percent":75}'
# → value 79.15 (ตรงกับ core/crop_water.js)

5) ทดสอบสูตร (ต้องผ่านทั้งสองฝั่ง)

julia --project=service service/test/runtests.jl   # ฝั่ง Julia
node --test tests/*.test.mjs                       # ฝั่ง JS (รวม golden vectors)

6) รันด้วย Docker (เว็บ + API + PostgreSQL พร้อมกัน)

พอร์ตทุกตัวมาจาก .env ที่ราก repo — ไม่มีเลขพอร์ตฝังในไฟล์ config

cp .env.example .env          # แล้วตั้ง DB_PASSWORD (compose ไม่ยอม start ถ้าว่าง)
docker compose build
docker compose up -d
docker compose ps             # รอจนเห็น Up (healthy)
curl -s http://127.0.0.1:8097/healthz                  # ok
curl -s http://127.0.0.1:8000/api/v1/health            # database.connected = true
ตัวแปรใน .env ค่าเริ่มต้น ใช้ทำอะไร
WEB_CONTAINER_PORT 8080 พอร์ตที่ nginx ฟังในคอนเทนเนอร์ (แทนค่าใน deploy/nginx.conf.template)
WEB_HOST_PORT 8097 พอร์ตที่เปิดออกเครื่อง (8080 ถูกตัวอื่นยึด · 8095 ถูก idealroute-web ยึด)
API_CONTAINER_PORT 8000 พอร์ตที่ Julia ฟังในคอนเทนเนอร์ (FARM_API_PORT) + ปลายทางของ /api/
API_HOST_PORT 8000 พอร์ตที่เปิด API ออกเครื่อง (ใช้ตรวจ/ทดสอบตรง)
DB_HOST_PORT 5433 พอร์ต PostgreSQL ออกเครื่อง (5432 ในเครื่องมีอยู่แล้ว)
DB_NAME / DB_USER / DB_PASSWORD farm_planning / postgres / ว่าง ฐานข้อมูล (สคีมาจาก service/db/001_init.sql ตอนสร้างครั้งแรก)
FARM_PERSIST_RUNS true false = ไม่บันทึก calculation_runs
FARM_CORS_ORIGIN * prod ให้ใส่ origin จริง
  • เว็บเรียก API ผ่าน path เดียวกัน (/api/... → proxy ไปคอนเทนเนอร์ api) จึงไม่ติด CORS
  • ไฟล์ static ถูก COPY เข้า image — แก้หน้าเว็บแล้วต้อง docker compose up -d --build
  • ฐานข้อมูลอยู่ใน named volume pgdata · ล้างทั้งหมด: docker compose down -v

ไฟล์

service/
├── src/formulas.jl   สูตร pure function (ไม่มี DB/HTTP) — แหล่งความจริง
├── src/db.jl         LibPQ + บันทึก calculation_runs
├── src/server.jl     HTTP.jl router + CORS + JSON
├── db/001_init.sql   สคีมา (calculation_runs, provinces, eto_monthly, view)
├── test/runtests.jl  ทดสอบด้วย golden vectors ชุดเดียวกับ JS
├── openapi.yaml      สัญญา API
├── Dockerfile        image ของ API (julia:1.13-bookworm + libpq5)
└── .env.example      ค่าที่ต้องตั้ง (คัดลอกเป็น .env เอง)

ราก repo/
├── Dockerfile        image เว็บ static (nginx:alpine)
├── docker-compose.yml  web + api + db (พอร์ตจาก .env)
├── deploy/nginx.conf.template  listen ${WEB_CONTAINER_PORT} + proxy /api/
└── .env.example      พอร์ต/ฐานข้อมูลของ compose

กติกา

  • ห้ามเขียนสูตรซ้ำใน server.jl — เรียก Formulas เท่านั้น
  • แก้สูตร → แก้ core/*.js + service/src/formulas.jl + tests/golden/vectors.json พร้อมกัน แล้วรัน test ทั้งสองฝั่ง
  • เพิ่ม field ในผลลัพธ์ = เพิ่มใน openapi.yaml ด้วย
  • ค่าที่ผิด (<= 0, เกิน 100%) ต้องตอบ 400 พร้อมข้อความภาษาไทย ไม่ใช่ 500