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 }