- service/: Julia HTTP API (HTTP.jl + LibPQ), formulas.jl as source of truth - service/db/001_init.sql: calculation_runs (append-only), provinces, eto_monthly - tests/golden/vectors.json: single fixture set enforced on both JS and Julia - .gitignore: keep secrets (DB env, contracts, financial records, ransomware note) out - AGENTS.md: document service commands and formula-change rule
79 lines
3.6 KiB
Markdown
79 lines
3.6 KiB
Markdown
# 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) เตรียมฐานข้อมูล
|
|
|
|
```bash
|
|
# สร้างฐาน (ใช้ 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) ตั้งค่า
|
|
|
|
```bash
|
|
cp service/.env.example service/.env
|
|
# แล้วแก้ FARM_DB_PASSWORD ใน service/.env เอง (ห้าม commit ไฟล์นี้)
|
|
```
|
|
|
|
ถ้าไม่ตั้งรหัส → service ยังรันได้ แต่ **ไม่บันทึกผลลง DB** และ `/api/v1/health` จะบอกว่าฐานข้อมูลไม่ได้เชื่อม
|
|
|
|
## 3) ติดตั้ง dependency ของ Julia (ครั้งแรกครั้งเดียว)
|
|
|
|
```bash
|
|
julia --project=service -e 'using Pkg; Pkg.add(["HTTP","JSON3","LibPQ"])'
|
|
```
|
|
|
|
## 4) รัน
|
|
|
|
```bash
|
|
julia --project=service service/src/server.jl
|
|
# ฟังที่ http://127.0.0.1:8000
|
|
```
|
|
|
|
ตรวจว่าใช้งานได้:
|
|
|
|
```bash
|
|
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) ทดสอบสูตร (ต้องผ่านทั้งสองฝั่ง)
|
|
|
|
```bash
|
|
julia --project=service service/test/runtests.jl # ฝั่ง Julia
|
|
node --test tests/*.test.mjs # ฝั่ง JS (รวม golden vectors)
|
|
```
|
|
|
|
## ไฟล์
|
|
|
|
```
|
|
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
|
|
└── .env.example ค่าที่ต้องตั้ง (คัดลอกเป็น .env เอง)
|
|
```
|
|
|
|
## กติกา
|
|
|
|
- **ห้ามเขียนสูตรซ้ำใน `server.jl`** — เรียก `Formulas` เท่านั้น
|
|
- แก้สูตร → แก้ `core/*.js` + `service/src/formulas.jl` + `tests/golden/vectors.json` พร้อมกัน แล้วรัน test ทั้งสองฝั่ง
|
|
- เพิ่ม field ในผลลัพธ์ = เพิ่มใน `openapi.yaml` ด้วย
|
|
- ค่าที่ผิด (<= 0, เกิน 100%) ต้องตอบ 400 พร้อมข้อความภาษาไทย ไม่ใช่ 500
|