- 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
128 lines
5.3 KiB
YAML
128 lines
5.3 KiB
YAML
openapi: 3.1.0
|
||
info:
|
||
title: farm-planning API
|
||
version: 1.0.0
|
||
description: >
|
||
คำนวณความต้องการน้ำของพืชและปริมาตรสระน้ำ (Julia + PostgreSQL)
|
||
ผลลัพธ์มีโครงเดียวกับ core/*.js เพื่อให้หน้าเว็บใช้แทนกันได้
|
||
ทุกครั้งที่คำนวณสำเร็จจะบันทึกใน calculation_runs (ถ้าเปิดการบันทึก)
|
||
servers:
|
||
- url: http://127.0.0.1:8000
|
||
description: local development
|
||
|
||
paths:
|
||
/api/v1/health:
|
||
get:
|
||
summary: สถานะบริการ + การเชื่อมต่อฐานข้อมูล
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
status: { type: string, example: ok }
|
||
api_version: { type: string, example: 1.0.0 }
|
||
formula_version: { type: string, example: "1.0" }
|
||
persist_runs: { type: boolean }
|
||
database:
|
||
type: object
|
||
properties:
|
||
connected: { type: boolean }
|
||
database: { type: string }
|
||
calculation_runs: { type: integer }
|
||
detail: { type: string }
|
||
|
||
/api/v1/meta:
|
||
get:
|
||
summary: รายการ endpoint และชื่อเดือนที่รองรับ
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
|
||
/api/v1/waters/calculate/plant:
|
||
post:
|
||
summary: น้ำที่พืชต้องการ (ETc = Kc × ETo)
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [eto_mm_per_day, crop_coefficient, area_rai, irrigation_efficiency_percent]
|
||
properties:
|
||
eto_mm_per_day: { type: number, minimum: 0.01, example: 3.71 }
|
||
crop_coefficient: { type: number, minimum: 0.01, example: 1.0 }
|
||
area_rai: { type: number, minimum: 0.01, example: 10 }
|
||
irrigation_efficiency_percent: { type: number, minimum: 1, maximum: 100, example: 75 }
|
||
client_version: { type: string, example: 2026.11.16.7 }
|
||
responses:
|
||
"200":
|
||
description: ผลลัพธ์ (โครงเดียวกับ core/crop_water.js)
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
value: { type: number, example: 79.15 }
|
||
unit: { type: string, example: cubic_metre_per_day }
|
||
steps:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
label: { type: string }
|
||
value: { type: number }
|
||
unit: { type: string }
|
||
warnings:
|
||
type: array
|
||
items: { type: string }
|
||
details:
|
||
type: object
|
||
properties:
|
||
eto_mm_per_day: { type: number }
|
||
etc_mm_per_day: { type: number }
|
||
net_m3_per_day: { type: number }
|
||
gross_m3_per_day: { type: number }
|
||
gross_m3_per_week: { type: number }
|
||
gross_m3_per_month: { type: number }
|
||
run_id:
|
||
type: [string, "null"]
|
||
description: uuid ของแถวใน calculation_runs (null ถ้าไม่ได้เปิดการบันทึก)
|
||
engine: { type: string, example: julia }
|
||
formula_version: { type: string, example: "1.0" }
|
||
"400":
|
||
description: ค่าที่ส่งมาไม่ถูกต้อง (ข้อความเป็นภาษาไทย)
|
||
|
||
/api/v1/capacities/reservoir:
|
||
post:
|
||
summary: ปริมาตรสระน้ำ (เรขาคณิต + น้ำฝนลงสระ)
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [top_length_m, top_width_m, depth_m, usable_depth_percent]
|
||
properties:
|
||
shape: { type: string, enum: [box, trapezoid], default: trapezoid }
|
||
top_length_m: { type: number, example: 40 }
|
||
top_width_m: { type: number, example: 30 }
|
||
depth_m: { type: number, example: 4 }
|
||
side_slope_horizontal_per_vertical: { type: number, default: 1.5 }
|
||
usable_depth_percent: { type: number, maximum: 100, example: 80 }
|
||
catchment_rai: { type: number, default: 0 }
|
||
rainfall_mm: { type: number, default: 0 }
|
||
runoff_coefficient: { type: number, default: 0.8 }
|
||
responses:
|
||
"200":
|
||
description: ผลลัพธ์ (โครงเดียวกับ core/pond.js)
|
||
|
||
components:
|
||
schemas:
|
||
Error:
|
||
type: object
|
||
properties:
|
||
error: { type: string }
|