diff --git a/IDEA.md b/IDEA.md new file mode 100644 index 0000000..ba7d9f6 --- /dev/null +++ b/IDEA.md @@ -0,0 +1 @@ +you are irrigation hydrology hidrualic and geotechical ENGINEERING and Programer fontend is vue.js and backend is julia and use api.jl diff --git a/SYSTEM-DESIGN.md b/SYSTEM-DESIGN.md index 44ecda3..c7e8cf8 100644 --- a/SYSTEM-DESIGN.md +++ b/SYSTEM-DESIGN.md @@ -1,369 +1,335 @@ -# SYSTEM DESIGN — hydraucal / sprinkler-calculation +# SYSTEM-DESIGN — irrcal / farm-planning -> เวอร์ชัน 0.1 (16 พ.ย. 2026) · สถานะ: ออกแบบหลังสำรวจ repo จริง · เอกสารนี้เป็น "แบบก่อสร้าง" ไม่ใช่รายงานสถานะ +> เวอร์ชัน 0.2 (23 พ.ย. 2026) · แทน v0.1 (เก็บที่ `archive/SYSTEM-DESIGN.v0.1-20261116.md`) +> ที่มา: `IDEA.md` (Vue หน้าเว็บ + Julia API) + สภาพจริงของ repo ที่วัดเมื่อ 23 พ.ย. 2026 +> เอกสารนี้เป็น "แบบก่อสร้าง" · ค่าหน้าตาอยู่ที่ `DESIGN.md` · กติกาทำงานอยู่ที่ `AGENTS.md` --- -## 1. บริบทและเป้าหมาย +## 1. ผลิตภัณฑ์ -เว็บ `farm-planning` เป็นเครื่องมือช่วยตัดสินใจเรื่องน้ำในแปลงเกษตร (คำนวณขนาดสระ, ปริมาณน้ำของพืช, ระบบน้ำหยด/สปริงเกลอร์, คูส่ง-คูระบาย, บ่อหน่วงน้ำ) ปัจจุบันเป็น static site ยุค 2019 ที่พึ่ง Start Bootstrap "Creative" + Bootstrap 4 และตัวคำนวณยังเป็นไฟล์ JS ที่ไม่ทำงาน +ระบบเดียว 3 งาน ที่วันนี้กระจายอยู่ 3 สแตก: -เป้าหมายของ repo `hydraucal`: +| งาน | ของวันนี้ | ผู้ใช้ | ที่อยู่ในเป้าหมาย | +|---|---|---|---| +| W1 เครื่องคำนวณน้ำในแปลง | static SPA (vanilla + Bootstrap 4) | เกษตรกร/เจ้าหน้าที่ส่งเสริม | Vue view ในแอปหลัก + Julia API | +| W2 บทความชลประทานเบื้องต้น 15 หัวข้อ | `farm-blog/` (Vue 3 + Vite + Bootstrap 5) | ผู้เริ่มศึกษา | Vue view ในแอปหลัก | +| W3 ตำราวิศวกรรมชลประทาน 10 บท | `intro-irre/` (static, build ด้วย Python) | นักศึกษา/วิศวกร | คงเป็น static ใต้ `/docs/` | -| เป้าหมาย | คำอธิบาย | -|---|---| -| G1 ใช้งานได้จริง | หน้าเว็บทุกหน้าต้องเปิดได้ ไม่มี asset 404 ไม่มี JS error | -| G2 คำนวณถูกและตรวจสอบได้ | สูตรแยกเป็นโมดูลบริสุทธิ์ (pure) มี unit test เทียบค่าอ้างอิง | -| G3 ข้อมูลอ่านได้โดยมนุษย์ | JSON คีย์เต็มคำ ไม่มี `field2`/`field3` แบบ export จาก Excel | -| G4 ต่อยอดเป็น PWA + API | ใช้ offline ได้ และมี backend รับงานคำนวณหนัก/เก็บโปรเจกต์ | +เป้าหมายเชิงวิศวกรรม (วัดได้): + +| # | เป้าหมาย | ตัวชี้วัด | +|---|---|---| +| G1 | คำนวณถูกและตรวจย้อนได้ | ทุกฟังก์ชันคืน `steps[]` + `warnings[]` · golden vectors ตรงกัน JS ↔ Julia | +| G2 | ใช้ได้แม้ออฟไลน์ | เปิดหน้าเดิมได้โดยไม่ต้องมีเน็ต หลังโหลดครั้งแรก · ป้ายบอกว่าใครคำนวณ | +| G3 | สูตรแหล่งเดียว | สูตรมี 2 สำเนาเท่านั้น (`formulas.jl` = ความจริง, `core/*.js` = ออฟไลน์) และถูกล็อกด้วย golden test | +| G4 | ข้อมูลมนุษย์อ่านได้ | JSON คีย์เต็มคำ + หน่วยในชื่อคีย์ + `label_th` + `source_reference` | +| G5 | ขยายหน้าได้ไม่ต้องรื้อ | เพิ่มหน้า = เพิ่ม route + view ไม่แตะ router เดิม | --- -## 2. สถานะปัจจุบัน (วัดจริงจาก repo) +## 2. สภาพปัจจุบัน (วัดจริง 23 พ.ย. 2026, commit 4f74a50 + ของที่ยังไม่ commit) -| รายการ | ค่า | -|---|---| -| ไฟล์ทั้งหมด (ไม่รวม `.git`) | 2,560 ไฟล์ | -| ขนาด | 296 MB | -| commit | **0** (repo ว่างตอน clone, ไฟล์ถูกคัดลอกเข้ามาภายหลัง) | -| HTML ที่เป็นหน้าใช้งานจริง | 2 (`index.html` ราก, `coding/index.html` สำเนา) | -| CSS สำเร็จรูป | ไม่มี `creative.min.css` ที่ `index.html` เรียก | -| ข้อมูล JSON | 11 ไฟล์ใน `open data/JSON/` (ETo 5 ไฟล์ใช้ได้ 138 แถว = 116 จังหวัดที่มีข้อมูล, Kc 3 ไฟล์เสีย) | -| โมดูลคำนวณ | 4 ไฟล์ stub (`water demand.js`, `ETo; Penman-Monteith.js`, `data collection.js`, `test.js`) | -| API ที่เคยออกแบบ | `coding/logic/farm-planning.postman_collection.json` — 16 endpoint | -| โครงสร้าง DB | `SQL/` ว่าง (มีแต่ `desktop.ini`) | +| ชั้น | ของจริงในรีโป | สถานะ | +|---|---|---| +| เชลล์เว็บ | `index.html` + `app/router.js` (hash router) + `app/pwa.js` + `partials/*.html` 8 ไฟล์ | ทำงาน · ไม่มี build | +| CSS | `assets/css/app.css` (โทเคน `DESIGN.md`) + `css/creative.css` + `css/legacy.css` + `coding/vendor/bootstrap 4.2.1` | ทำงาน · มี Bootstrap 4 ค้าง + jQuery | +| สูตร JS | `core/crop_water.js` (81 บรรทัด), `core/pond.js` (125) | ทำงาน · 2 สูตร | +| สูตร Julia | `service/src/formulas.jl` (168) | ทำงาน · 2 สูตรเดียวกัน | +| API | `service/src/server.jl` (HTTP.jl, 181) — GET `/health`, GET `/meta`, POST `/waters/calculate/plant`, POST `/capacities/reservoir` | ทำงาน · CORS เปิด · ไม่มี auth | +| DB | `service/db/001_init.sql` — `calculation_runs` (append-only jsonb), `provinces`, `eto_monthly`, view `calculation_runs_daily` | สคีมามี · ยังไม่มี seed ETo | +| ข้อมูล | `data/climate/eto_by_region.json` 116 จังหวัด × 12 เดือน (2,011 บรรทัด) | ใช้ในหน้า crop-water | +| Test | `tests/core.test.mjs`, `tests/golden.test.mjs`, `tests/golden/vectors.json` · `service/test/runtests.jl` | ผ่าน | +| PWA | `sw.js` VERSION 2026.11.16.7 · PRECACHE ~45 ไฟล์ · network-first(text) / cache-first(img) | ทำงาน | +| farm-blog | Vue 3.5 + Vite 8 + Bootstrap 5.3 + SCSS overrides · `src/{App.vue,router,views/HomeView,components,data/topics.js}` · **เป็น git repo ซ้อน** (commit f767c9c) | ใช้งานได้ · หน้าเดียว | +| intro-irre | 10 บท + `tools/{extract,build}.py` + `data/{nav,search}.json` + 423 รูป (32 MB) | ใช้งานได้ · static | +| ของค้าง | `coding/` (30 MB), `css/`, template ซ้ำ 3 ชุด, `---/`, `_readme.txt` | ยังไม่ย้ายเข้า `archive/` | -### โครงสร้างระดับบนสุดที่ปะปนกันอยู่ - -``` -hydraucal/ -├── index.html ← หน้าเว็บ (ซ่อมแล้วในงานนี้) -├── css/ ← creative.css (compile จาก coding/scss) + legacy.css [เพิ่มใหม่] -├── coding/ ← ซอร์สเดิม: html, css, js, scss, vendor, logic/ -├── flat icon/ logo/ font/ image ประกอบ/ profile&backgroud/ -├── Document/ ← เอกสารวิธีคำนวณ 16 หัวข้อ (docx/pdf/xlsx) -├── open data/ ← JSON + Spreadsheet (ETo, Kc) -├── PWA-fam-plans/ ← docker compose ทดลอง (joomla, postgres, nodejs, golang) -├── e-book/ แรงบันดาลใจ/ แนวทางการหาเงิน/ หลักฐาน*/ อื่นๆ/ ← ไฟล์ส่วนตัว/อ้างอิง ไม่ใช่ซอร์ส -├── startbootstrap-*/ ---/ ← template สำเนา 3 ชุด (ซ้ำ) -└── _readme.txt ← ⚠️ ไฟล์เรียกค่าไถ่ransomware (ดู §10 R1) -``` +สรุป: **สแตกซ้อน 3 ชุด** (vanilla BS4 / Vue BS5 / static docs) · ตรรกะคำนวณซ้ำ 2 ภาษา · หน้าเว็บยังไม่เรียก API เลย --- -## 3. ปัญหาที่ต้องแก้ (เรียงตามผลกระทบ) +## 3. ปัญหาสถาปัตยกรรมที่ต้องแก้ | # | ปัญหา | หลักฐาน | ผลกระทบ | |---|---|---|---| -| P1 | path ของ asset พังทั้งหน้า | `../vendor/...`, `/flat_icon/...`, `..dist/clipboard.min.js` ไม่มีอยู่จริง | หน้าเว็บไม่มีสไตล์ ไม่มีไอคอน | -| P2 | ไฟล์ CSS หลักหาย | `creative.min.css` ไม่มีใน repo (เหลือแต่ `coding/scss/*.scss`) | hero/nav/การ์ดเสียรูปแบบ | -| P3 | markup ไม่ถูกต้อง | `
` ครอบ `
` เกิน 2 ตัว | เบราว์เซอร์จัด DOM เอง ผลลัพธ์ไม่แน่นอน | -| P4 | JS อ้าง element ที่ไม่มี | `custom.js` เรียก `#myBtn` ทุก scroll | `TypeError` ทุกครั้งที่เลื่อนหน้า | -| P5 | ข้อมูล Kc เสีย | 3 ไฟล์ Thai chars = 0, control escape 200+ | คำนวณปริมาณน้ำของพืชไม่ได้ | -| P6 | โฟลเดอร์/ไฟล์ชื่อไทย + เว้นวรรค | `logo ใหม่/`, `flat icon/retention pond.svg` | URL ต้อง encode, deploy บน server/Linux เสี่ยงพัง | -| P7 | ไม่มี git history | commit = 0 | ย้อนกลับไม่ได้ ตรวจ diff ไม่ได้ | -| P8 | ขยะปนซอร์ส | `~WRL0005.tmp` 356 KB, `.download` 155 ไฟล์, template ซ้ำ 3 ชุด, `desktop.ini` 71 ไฟล์ | repo หนัก, หาไฟล์จริงยาก | +| A1 | 3 frontend stack | `index.html` (BS4+jQuery), `farm-blog/` (Vue+BS5), `intro-irre/` (static) | แก้ดีไซน์ต้องแก้ 3 ที่ · โทเคนสี 2 ชุด (`#2563eb` / `#1d6ce2`) | +| A2 | หน้าเว็บไม่อ่าน API | `partials/*.html` import `core/*.js` ตรง ๆ | DB ไม่มีข้อมูลจริง · `run_id` ไม่ถูกใช้ · สูตร 2 ภาษาไม่มีใครเทียบตอนรัน | +| A3 | สูตร 2 สำเนาไม่มีด่าน | `formulas.jl` ↔ `core/*.js` | แก้ข้างเดียว = ผลเพี้ยนเงียบ ๆ (กันด้วย golden test เท่านั้น) | +| A4 | ไม่มี schema ข้อมูล | `data/` มี JSON เดียว ไม่มี `schema/` | ข้อมูลเพี้ยนแบบ Kc เดิมหลุดกลับมาได้ | +| A5 | ETo ไม่มี endpoint | `server.jl` ไม่มี `/provinces` | หน้าเว็บโหลด JSON 2,011 บรรทัดมากรองเองทุกครั้ง | +| A6 | ไม่มีเส้นทาง deploy | ไม่มี nginx config / systemd / Dockerfile / CI | "รันบนเครื่องได้" ยังไม่เท่ากับ "ขึ้นเซิร์ฟเวอร์ได้" | +| A7 | farm-blog เป็น repo ซ้อน | `farm-blog/.git` | commit รากไม่เห็นประวัติ blog · push พลาดง่าย | +| A8 | repo มีความลับค้างใน history | `_readme.txt` (ransomware note), `PWA-fam-plans/v.3.8.yaml` (รหัส DB plaintext) | repo public → ต้องหมุนรหัส + ตัดสินเรื่อง history | +| A9 | 32 MB รูปตำราในรีโป | `intro-irre/assets/figures` | clone/push ช้า ไม่เกี่ยวกับงานคำนวณ | --- ## 4. หลักการออกแบบ -1. **แยกชั้นชัด**: เนื้อหา (HTML) / รูปแบบ (CSS) / ตรรกะคำนวณ (JS module) / ข้อมูล (JSON) / บริการ (API) — ห้ามให้สูตรคณิตศาสตร์อยู่ใน HTML หรือ inline script -2. **สูตรต้องทดสอบได้**: ฟังก์ชัน pure รับ input object คืน `{ value, unit, steps, warnings }` — `steps` ไว้แสดงที่มาของผลลัพธ์ให้เกษตรกรเห็น (ตรวจสอบย้อนกลับได้) -3. **ไม่พึ่ง CDN ในส่วนวิกฤต**: ฟอนต์/ตัวนับผู้ชมอยู่นอก repo ได้ แต่ CSS/JS ที่ทำให้หน้าทำงานต้องอยู่ใน repo -4. **ข้อมูลเป็น JSON คีย์เต็มคำ** กลุ่ม → ชนิด → รายการ (แบบเดียวกับที่ใช้ในโปรเจกต์ transit) -5. **ชื่อไฟล์/โฟลเดอร์ ASCII** ทั้งหมด (ไฟล์ไทยเดิมเก็บใน `archive/`) +1. **หนึ่ง frontend หนึ่งภาษา** — Vue 3 + Vite + Bootstrap 5.3 (SCSS overrides) เท่านั้น · ไม่มี jQuery ไม่มี Bootstrap 4 ในแอปใหม่ +2. **สูตรอยู่ที่เดิม ไม่ย้ายเข้า component** — `core/*.js` (pure ES module) และ `service/src/formulas.jl` · view ทำหน้าที่แค่เก็บ input → เรียก → วาดผล +3. **ผลลัพธ์มีโครงเดียวทุกเอนจิน** — `{ value, unit, steps[], warnings[], engine, formula_version, run_id? }` สลับแหล่งคำนวณได้โดย UI ไม่ต้องแก้ +4. **ออฟไลน์เป็นสภาพปกติ ไม่ใช่ของแถม** — ทุกสูตรที่เปิดใช้ต้องรันในเบราว์เซอร์ได้ และให้ผลตรงกับเซิร์ฟเวอร์ (golden) +5. **ข้อมูลผู้ใช้ห้ามแต่ง** — Kc, ราคาพืช, ค่าระบายน้ำ ที่ระบบไม่มีแหล่งอ้างอิง ให้ผู้ใช้กรอกและแสดงที่มา (กฎเดียวกับ `AGENTS.md`) +6. **ค่าออกแบบอยู่ที่ `DESIGN.md` ที่เดียว** — สี ฟอนต์ รัศมี ระยะ · component ห้าม hardcode hex --- ## 5. สถาปัตยกรรมเป้าหมาย ``` -┌──────────────────────────────────────────────────────────────┐ -│ ชั้นนำเสนอ web/ (static, ไม่มี build) │ -│ index.html · pages/*.html · assets/{css,js,img} │ -│ PWA: manifest.webmanifest + sw.js (precache เฉพาะที่ใช้) │ -└───────────────┬──────────────────────────────────────────────┘ - │ import (ES module, relative path) -┌───────────────▼──────────────────────────────────────────────┐ -│ ชั้นตรรกะ core/ (pure JS, ไม่แตะ DOM) │ -│ units · evapotranspiration · water_balance · reservoir │ -│ irrigation_drip · irrigation_sprinkler · channel · basin │ -│ water_value · scheduling │ -│ ทุกโมดูล: (input) → { value, unit, steps[], warnings[] } │ -└───────────────┬──────────────────────────────────────────────┘ - │ fetch (JSON, read-only) -┌───────────────▼──────────────────────────────────────────────┐ -│ ชั้นข้อมูล data/ (JSON มนุษย์อ่านได้ + JSON Schema) │ -│ crops/crop_coefficient.json · climate/eto_by_region.json │ -│ hydrology/province_runoff.json · prices/crop_price.json │ -└───────────────┬──────────────────────────────────────────────┘ - │ (เฟส 3, ถ้าต้องการเก็บโปรเจกต์/คำนวณหนัก) -┌───────────────▼──────────────────────────────────────────────┐ -│ ชั้นบริการ service/ (HTTP API) │ -│ POST /api/v1/waters/calculate/* · POST /api/v1/capacities │ -│ GET /api/v1/provinces · /api/v1/crops │ -│ เก็บผลคำนวณ + export PDF (แทน postman collection เดิม) │ -└──────────────────────────────────────────────────────────────┘ +┌────────────────────────────────────────────────────────────────────┐ +│ ชั้นนำเสนอ app/ (Vue 3 + Vite) │ +│ views: home · crop-water · pond · irrigation · glossary · blog │ +│ blog/:slug · contact · credits │ +│ state: composables/useCalculation.js (เลือกเอนจิน + สถานะ) │ +│ PWA: manifest + sw.js (precache จาก manifest ที่ build สร้าง) │ +└──────────┬───────────────────────────────────┬─────────────────────┘ + │ ออนไลน์: fetch JSON │ ออฟไลน์/API ล่ม: import +┌──────────▼───────────────────┐ ┌───────────▼─────────────────────┐ +│ ชั้นบริการ service/ (Julia) │ │ ชั้นสูตรออฟไลน์ core/*.js │ +│ api.jl HTTP.jl router │ │ crop_water.js · pond.js (+อนาคต) │ +│ formulas.jl สูตร pure │ │ pure ES module · ไม่แตะ DOM │ +│ db.jl LibPQ │ └─────────────────────────────────┘ +│ PostgreSQL │ +└──────────┬───────────────────┘ + │ อ่าน/เขียน +┌──────────▼────────────────────────────────────────────────────────┐ +│ ชั้นข้อมูล data/*.json (มนุษย์อ่านได้) + data/schema/*.schema.json │ +│ eto_by_region.json · crop_coefficient.json · crop_price.json │ +└───────────────────────────────────────────────────────────────────┘ + + ┌ เนื้อหาคงที่: content/docs (10 บท) → copy เข้า dist/docs ``` -เหตุผลที่ยัง **ไม่ต้องมี build step**: หน้าเว็บมี 10-13 หน้า, JS รวมไม่ถึง 100 KB — ใช้ ES module ตรง ๆ ได้ ลดความซับซ้อนของ toolchain (ถ้าภายหลังต้องการ bundle ค่อยเพิ่ม Vite โดยไม่ต้องรื้อโครง) +### 5.1 เลือกเอนจิน (เขียนเป็นโค้ดเดียว ใช้ทุกหน้า) + +| ลำดับ | เงื่อนไข | เอนจิน | UI แสดง | +|---|---|---|---| +| 1 | `/api/v1/health` ตอบใน 1.5 วิ (แคชผล 60 วิ) | `julia` | "คำนวณโดยเซิร์ฟเวอร์ · สูตร 1.0" + `run_id` | +| 2 | ออฟไลน์ / API ล่ม / timeout | `js-offline` | "คำนวณในเครื่องนี้ (ออฟไลน์)" | +| 3 | ผู้ใช้กด "คำนวณซ้ำบนเซิร์ฟเวอร์" | บังคับ `julia` | เหมือนข้อ 1 | + +ผลทั้งสองทางต้องเท่ากัน (ทดสอบด้วย `tests/golden/vectors.json`) · ถ้าไม่เท่า = bug ไม่ใช่ "แล้วแต่เครื่อง" + +### 5.2 การตัดสินใจหลัก (ADR ย่อ) + +| # | ตัดสินใจ | ทางที่ตัดทิ้ง | เหตุผล | +|---|---|---|---| +| D1 | Vue 3 + Vite เป็นแอปเดียว (แทน vanilla SPA) | คง vanilla ต่อ | 3 สแตกซ้อนคือต้นเหตุ A1 · farm-blog พิสูจน์แล้วว่า Vue+Vite ทำงานในเครื่องนี้ได้ | +| D2 | Bootstrap 5.3 ผ่าน SCSS overrides | คง Bootstrap 4 + jQuery | ลด payload, ไม่มี jQuery, คุมโทเคนสีจาก `_bootstrap-overrides.scss` | +| D3 | Julia คงเป็น HTTP.jl ตรง ๆ (ไฟล์ `api.jl`) | ย้ายไป Genie/Oxygen | 4 endpoint ยังไม่ต้องใช้ framework · เพิ่ม dependency = เพิ่มจุดพัง | +| D4 | router เป็น hash (`#/`) | history mode | deploy บน static/nginx ได้โดยไม่ต้อง rewrite · ตรงกับที่ farm-blog ทำ | +| D5 | ตำรา 10 บท คงเป็น static ใต้ `/docs/` | แปลงเป็น Vue view | 32 MB รูป + anchor 423 รูป · แปลงเป็น SPA ได้แต่ไม่ได้อะไรกลับมา | +| D6 | `farm-blog` ยุบเป็น repo เดียว | คงเป็น submodule | ประวัติย่อยเก็บด้วย `git bundle` ไว้ `archive/` | --- ## 6. โครงสร้างโฟลเดอร์เป้าหมาย + mapping ``` -hydraucal/ -├── web/ -│ ├── index.html ← จาก index.html (ซ่อมแล้ว) -│ ├── pages/ -│ │ ├── pond_calculation.html ← ยังไม่มี (poolcal.html เดิมหาย) -│ │ ├── water_value.html -│ │ ├── crop_water.html -│ │ ├── irrigation_pressure.html -│ │ ├── glossary.html -│ │ └── ... -│ ├── assets/css/{creative.css,legacy.css,custom.css} -│ ├── assets/js/{app.js, pages/*.js} -│ ├── assets/img/{icons,logos,photos} -│ ├── manifest.webmanifest -│ └── sw.js -├── core/ ← ใหม่ทั้งหมด -│ ├── units.js -│ ├── evapotranspiration.js -│ ├── water_balance.js -│ ├── reservoir.js -│ ├── irrigation_drip.js -│ ├── irrigation_sprinkler.js -│ ├── channel.js -│ ├── basin.js -│ ├── water_value.js -│ └── scheduling.js -├── data/ -│ ├── schema/*.schema.json -│ ├── crops/{crop_coefficient.json,crop_list.json} -│ ├── climate/eto_by_region.json -│ ├── hydrology/province_runoff.json -│ └── prices/crop_price.json -├── service/ ← เฟส 3 +irrcal/ +├── app/ Vue 3 + Vite (แอปเดียว) +│ ├── index.html +│ ├── src/ +│ │ ├── main.js App.vue +│ │ ├── router/index.js hash router + meta.title +│ │ ├── views/{HomeView,CropWaterView,PondView,IrrigationView, +│ │ │ GlossaryView,BlogView,BlogPostView,ContactView,CreditsView}.vue +│ │ ├── components/{CalcForm,ResultCard,StepsTable,WarnList,EngineBadge, +│ │ │ SiteHeader,SiteFooter,ToolRow,TopicCard}.vue +│ │ ├── composables/{useCalculation,useEngineStatus,usePwaInstall}.js +│ │ ├── api/client.js fetch + timeout + error shape +│ │ ├── data/topics.js เนื้อหา blog (จาก farm-blog) +│ │ └── assets/{main.scss,_bootstrap-overrides.scss,_app.scss} +│ └── vite.config.js alias @core → ../core, copy docs +├── core/ สูตร JS (แหล่งออฟไลน์) — เหมือนเดิม +├── data/ JSON + schema/ +├── content/docs/ ตำรา 10 บท (จาก intro-irre, ไม่ build ใน Vite) +├── service/ +│ ├── src/{api.jl,formulas.jl,db.jl} +│ ├── db/001_init.sql +│ ├── test/runtests.jl │ ├── openapi.yaml -│ └── src/... -├── tests/ ← node --test -│ ├── core/*.test.js -│ └── web/assets.test.js ← ตรวจว่า asset ทุกไฟล์มีจริง -├── docs/{SYSTEM-DESIGN.md,DATA-CONTRACT.md,DESIGN.md,AGENTS.md} -├── archive/ ← ของเดิมที่ไม่ได้ใช้ (template ซ้ำ, .download, tmp) -└── README.md +│ └── .env.example +├── tests/{core.test.mjs,golden.test.mjs,golden/vectors.json,api.contract.test.mjs} +├── tools/{build_eto_data.py,check_app.py,make_icons.py,seed_eto.py} +├── scripts/{bump-version.mjs} +├── deploy/{nginx.conf,Dockerfile.service,systemd/farm-api.service} +└── archive/ ``` -### Mapping ของเดิม → ที่ใหม่ +### ของเดิม → ที่ใหม่ | ของเดิม | ที่ใหม่ | หมายเหตุ | |---|---|---| -| `index.html` | `web/index.html` | ซ่อมแล้ว (path, markup, `#myBtn`) | -| `coding/scss/*.scss` | build → `web/assets/css/creative.css` | เก็บ scss ไว้เป็น source | -| `coding/css/custom.css` | `web/assets/css/custom.css` | ใช้ `size_card_2` อยู่ | -| `coding/vendor/*` | คงไว้ หรือย้าย `web/assets/vendor/` | ต้องอัปเกรด Bootstrap 4.2.1 → 5.3 ทีหลัง (ต้องแก้ `data-*` → `data-bs-*`) | -| `flat icon/*.svg` | `web/assets/img/icons/` | เปลี่ยนชื่อเป็น ASCII (`retention pond.svg` → `retention_pond.svg`) | -| `logo/**` | `web/assets/img/logos/` | `logo ใหม่/2566-09-08 11-51-40.png` → `logo_mark_2566.png` | -| `coding/js/water demand.js` ฯลฯ | `core/*.js` | เขียนใหม่ (ของเดิมเป็น stub ที่รันไม่ได้) | -| `open data/JSON/ปริมาณ…ภาค*.json` | `data/climate/eto_by_region.json` | รวม 5 ไฟล์เป็นชุดเดียว + เปลี่ยนคีย์ | -| `open data/JSON/Kc*.json` | `data/crops/crop_coefficient.json` | **ต้องสร้างใหม่** (ข้อมูลเสีย) | -| `coding/logic/farm-planning.postman_collection.json` | `service/openapi.yaml` | แปลง 16 endpoint เป็นสเปก | -| `PWA-fam-plans/` | `archive/` | เป็น docker ทดลอง ไม่ผูกกับโปรเจกต์ | -| `_readme.txt` | **ลบทิ้ง** | ⚠️ ไฟล์เรียกค่าไถ่ (ransomware) ไม่ใช่เอกสารโปรเจกต์ | - +| `index.html` + `app/router.js` + `partials/*.html` | `app/src/views/*.vue` + `router/index.js` | เนื้อหา/ข้อความย้ายตรง · เก็บ markup เดิมเป็น `archive/partials-*/` | +| `app/pwa.js` | `app/src/composables/usePwaInstall.js` + `sw.js` (Vite build) | auto-update logic เดิมพอร์ตมาทั้งดุ้น | +| `assets/css/app.css` | `app/src/assets/{_bootstrap-overrides,_app}.scss` | โทเคนจาก `DESIGN.md` | +| `coding/vendor/*`, `css/creative.css`, `coding/js/*` | **ไม่ย้าย** → `archive/legacy-static/` | Bootstrap 4 + jQuery เลิกใช้ | +| `farm-blog/src/**` | `app/src/{views/BlogView,components,TopicCard,data/topics.js}` | ย้ายทั้งชุด · `farm-blog/` เก็บเป็น bundle ใน `archive/` | +| `intro-irre/**` | `content/docs/**` | เปลี่ยน build path ใน `tools/build.py` | +| `service/src/server.jl` | `service/src/api.jl` | เปลี่ยนชื่อตาม `IDEA.md` (เนื้อหาเดิม) | +| `data/climate/eto_by_region.json` | คงที่ · เพิ่ม `data/schema/eto_by_region.schema.json` | | +| `_readme.txt` | **ลบทิ้ง** | ไฟล์เรียกค่าไถ่ ไม่ใช่เอกสารโปรเจกต์ | --- -## 7. โมดูลคำนวณ +## 7. สัญญาข้อมูล (Data Contract) -หน้าตาข้อมูลเข้า-ออกมาตรฐาน (ทุกโมดูลเหมือนกัน เพื่อให้ UI สร้างฟอร์มและแสดงผลแบบเดียวกันได้): +### 7.1 กติกา -```js -// core/reservoir.js -export function calculateReservoirVolume(input) { - // input: ReservoirInput (ดู DATA-CONTRACT.md) - return { - value: 4800, // ปริมาตรสุทธิ - unit: 'm3', - steps: [ - { label: 'พื้นที่ผิวน้ำ', value: 1200, unit: 'm2' }, - { label: 'ความลึกใช้การ', value: 4, unit: 'm' }, - { label: 'หักน้ำระเหย+รั่วซึม 30 วัน', value: 60, unit: 'm3' } - ], - warnings: ['ความลึกใช้การน้อยกว่า 2 ม. — ระบบจะแห้งเร็วในหน้าแล้ง'] - }; -} -``` +- คีย์เต็มคำ snake_case · หน่วยในชื่อคีย์: `_m`, `_m3`, `_mm_per_day`, `_rai`, `_percent`, `_baht_per_m3` +- ค่าตัวเลือกเป็นรหัสอังกฤษ · คำไทยอยู่ใน `label_th` +- ทุกไฟล์ข้อมูลมี `schema_version` + `source_reference` และมี schema คู่ใน `data/schema/` +- ห้ามใส่ control escape / ตัวอักษรเสีย (บทเรียนเดิม: Kc 3 ไฟล์ใช้ไม่ได้) -| โมดูล | หน้าที่ | แหล่งสูตร | -|---|---|---| -| `evapotranspiration.js` | ETo (Penman-Monteith) จากอุณหภูมิ/ความชื้น/ลม/รังสี | ข้อมูล ETo รายจังหวัดใน repo + FAO-56 | -| `water_balance.js` | ETc = Kc × ETo, ปริมาณน้ำรายวัน/รายสัปดาห์ | ตาราง Kc (ต้องสร้างใหม่) | -| `reservoir.js` | สระน้ำท่า / นอง / ฝน / ใต้ดิน | `Document/คำนวณขนาดสระน้ำ/` | -| `irrigation_drip.js` | เทปน้ำหยด / หัวน้ำหยด | `Document/การให้น้ำภายใต้แรงดัน/` | -| `irrigation_sprinkler.js` | มินิสปริงเกลอร์แรงดันต่ำ / สปริงเกลอร์แรงดันสูง (hydraulics: อัตราการไหล, head loss, จำนวนหัวต่อโซน) | `Document/การให้น้ำภายใต้แรงดัน/` | -| `channel.js` | คูส่งน้ำ / คูระบายน้ำ (Manning) | `Document/คูน้ำ`, `Document/คูระบายน้ำ` | -| `basin.js` | บ่อหน่วงน้ำ | `Document/บ่อหน่วงน้ำ` | -| `water_value.js` | มูลค่าน้ำ (บาท/ลบ.ม.) | `Document/มูลค่าน้ำ` | -| `scheduling.js` | จัดรอบเวรใช้น้ำในคูส่งน้ำ | งานใหม่ ( homepage การ์ดที่ 9 ) | -| `units.js` | แปลง ไร่/ตร.ม./ลิตร/บาร์ ฯลฯ | — | - -> **กติกาการเขียนสูตร**: ห้ามใช้ magic number ในฟังก์ชัน — ค่าคงที่ (ความหนาแน่นน้ำ, ค่า g, สัมประสิทธิ์การระเหยของถาดวัด) ต้องประกาศเป็น named export พร้อมหน่วยและแหล่งอ้างอิงใน comment เพราะผู้ใช้ต้องตรวจย้อนกลับได้ - ---- - -## 8. สัญญาข้อมูล (Data Contract) - -### 8.1 กติกาคีย์ - -- คีย์เป็นคำเต็ม ภาษาอังกฤษ snake_case ห้ามใช้ `field2`, `col3`, `a`, `b` -- หน่วยอยู่ในชื่อคีย์เสมอ: `_mm`, `_m3`, `_rai`, `_m`, `_percent`, `_baht_per_m3` -- ค่าที่เป็นตัวเลือกใช้รหัสภาษาอังกฤษ ไม่ใช่คำไทย (ไทยอยู่ใน `label_th`) - -### 8.2 ตัวอย่าง: `data/crops/crop_coefficient.json` (สร้างใหม่แทน Kc ที่เสีย) +### 7.2 รูปผลลัพธ์มาตรฐาน (ทั้ง JS และ Julia — ต้องเหมือนกัน) ```json { - "schema_version": "1.0", - "crop_groups": [ - { - "crop_group_id": "perennial", - "label_th": "พืชหลายปี", - "crops": [ - { - "crop_id": "durian", - "label_th": "ทุเรียน", - "stages": [ - { "stage_id": "establishment", "label_th": "เริ่มปลูก", "duration_day": 365, "kc": 0.60 }, - { "stage_id": "development", "label_th": "เจริญเติบโต", "duration_day": 730, "kc": 0.85 }, - { "stage_id": "maturity", "label_th": "ให้ผลเต็มที่", "duration_day": 1095, "kc": 1.00 } - ] - } - ] - } - ] + "calculation_kind": "pond_volume", + "value": 4800.0, + "unit": "m3", + "steps": [{ "label": "พื้นที่ผิวน้ำ", "value": 1200.0, "unit": "m2" }], + "warnings": ["ความลึกใช้การน้อยกว่า 2 ม. — ระบบจะแห้งเร็วหน้าแล้ง"], + "engine": "julia", + "formula_version": "1.0", + "run_id": "5c1f..." } ``` -### 8.3 ตัวอย่าง: `data/climate/eto_by_region.json` (แปลงจาก 5 ไฟล์เดิม) +### 7.3 API (v1) — มีแล้ว 4 + แผน -```json -{ - "schema_version": "1.0", - "unit": "mm_per_day", - "regions": [ - { - "region_id": "north", - "label_th": "ภาคเหนือ", - "provinces": [ - { - "province_id": "mae_hong_son", - "label_th": "แม่ฮ่องสอน", - "monthly_eto_mm_per_day": { - "january": 2.83, "february": 3.55, "march": 4.51, - "april": 5.31, "may": 5.20, "june": 4.68, - "july": 4.31, "august": 4.16, "september": 4.22, - "october": 4.05, "november": 3.45, "december": 2.92 - } - } - ] - } - ] -} +| Method | Path | สถานะ | ใช้ทำอะไร | +|---|---|---|---| +| GET | `/api/v1/health` | มี | สถานะ + DB + `formula_version` (ใช้ตัดสินเอนจิน) | +| GET | `/api/v1/meta` | มี | endpoint list + ชื่อเดือน | +| POST | `/api/v1/waters/calculate/plant` | มี | ETc = Kc × ETo → m³/วัน (net/gross) | +| POST | `/api/v1/capacities/reservoir` | มี | ปริมาตรสระ box/trapezoid + น้ำฝน | +| GET | `/api/v1/provinces?region=north` | แผน | dropdown จังหวัด + ETo รายเดือน (แทนโหลด JSON 2,011 บรรทัด) | +| GET | `/api/v1/crops` | แผน | กลุ่มพืช + ระยะ + ช่วง Kc ที่แนะนำ (ไม่ใช่ค่าฟันธง) | +| GET | `/api/v1/runs/{run_id}` | แผน | เปิดผลเก่าจาก `calculation_runs` | +| POST | `/api/v1/reports/pdf` | แผน (ช้า) | export ใบคำนวณ | + +ข้อกำหนดร่วม: error = `{"error": "ข้อความไทยอ่านรู้เรื่อง"}` · 400 input ผิด, 404 path ผิด, 500 อื่น · `Cache-Control: no-store` · CORS จาก `FARM_CORS_ORIGIN` (dev = `*`, prod = origin จริง) + +### 7.4 version 3 ชั้น + +| ชั้น | ที่เก็บ | เปลี่ยนเมื่อ | +|---|---|---| +| `build` (2026.11.16.N) | `package.json`, `app/src/version.js`, `sw.js` VERSION | ทุกครั้งที่ deploy (bump ด้วย `scripts/bump-version.mjs`) | +| `api_version` (1.0.0) | `service/src/api.jl` | เมื่อ path/สัญญาเปลี่ยนแบบไม่ถอยหลัง | +| `formula_version` (1.0) | `formulas.jl` + `core/*.js` + golden vectors | **ทุกครั้งที่ตัวเลขผลลัพธ์เปลี่ยน** | + +--- + +## 8. สูตรและ golden vectors + +- แก้สูตร = แก้ **3 ที่พร้อมกัน**: `core/` ครอบ `
` ครอบ `
` เกิน 2 ตัว | เบราว์เซอร์จัด DOM เอง ผลลัพธ์ไม่แน่นอน | +| P4 | JS อ้าง element ที่ไม่มี | `custom.js` เรียก `#myBtn` ทุก scroll | `TypeError` ทุกครั้งที่เลื่อนหน้า | +| P5 | ข้อมูล Kc เสีย | 3 ไฟล์ Thai chars = 0, control escape 200+ | คำนวณปริมาณน้ำของพืชไม่ได้ | +| P6 | โฟลเดอร์/ไฟล์ชื่อไทย + เว้นวรรค | `logo ใหม่/`, `flat icon/retention pond.svg` | URL ต้อง encode, deploy บน server/Linux เสี่ยงพัง | +| P7 | ไม่มี git history | commit = 0 | ย้อนกลับไม่ได้ ตรวจ diff ไม่ได้ | +| P8 | ขยะปนซอร์ส | `~WRL0005.tmp` 356 KB, `.download` 155 ไฟล์, template ซ้ำ 3 ชุด, `desktop.ini` 71 ไฟล์ | repo หนัก, หาไฟล์จริงยาก | + +--- + +## 4. หลักการออกแบบ + +1. **แยกชั้นชัด**: เนื้อหา (HTML) / รูปแบบ (CSS) / ตรรกะคำนวณ (JS module) / ข้อมูล (JSON) / บริการ (API) — ห้ามให้สูตรคณิตศาสตร์อยู่ใน HTML หรือ inline script +2. **สูตรต้องทดสอบได้**: ฟังก์ชัน pure รับ input object คืน `{ value, unit, steps, warnings }` — `steps` ไว้แสดงที่มาของผลลัพธ์ให้เกษตรกรเห็น (ตรวจสอบย้อนกลับได้) +3. **ไม่พึ่ง CDN ในส่วนวิกฤต**: ฟอนต์/ตัวนับผู้ชมอยู่นอก repo ได้ แต่ CSS/JS ที่ทำให้หน้าทำงานต้องอยู่ใน repo +4. **ข้อมูลเป็น JSON คีย์เต็มคำ** กลุ่ม → ชนิด → รายการ (แบบเดียวกับที่ใช้ในโปรเจกต์ transit) +5. **ชื่อไฟล์/โฟลเดอร์ ASCII** ทั้งหมด (ไฟล์ไทยเดิมเก็บใน `archive/`) + +--- + +## 5. สถาปัตยกรรมเป้าหมาย + +``` +┌──────────────────────────────────────────────────────────────┐ +│ ชั้นนำเสนอ web/ (static, ไม่มี build) │ +│ index.html · pages/*.html · assets/{css,js,img} │ +│ PWA: manifest.webmanifest + sw.js (precache เฉพาะที่ใช้) │ +└───────────────┬──────────────────────────────────────────────┘ + │ import (ES module, relative path) +┌───────────────▼──────────────────────────────────────────────┐ +│ ชั้นตรรกะ core/ (pure JS, ไม่แตะ DOM) │ +│ units · evapotranspiration · water_balance · reservoir │ +│ irrigation_drip · irrigation_sprinkler · channel · basin │ +│ water_value · scheduling │ +│ ทุกโมดูล: (input) → { value, unit, steps[], warnings[] } │ +└───────────────┬──────────────────────────────────────────────┘ + │ fetch (JSON, read-only) +┌───────────────▼──────────────────────────────────────────────┐ +│ ชั้นข้อมูล data/ (JSON มนุษย์อ่านได้ + JSON Schema) │ +│ crops/crop_coefficient.json · climate/eto_by_region.json │ +│ hydrology/province_runoff.json · prices/crop_price.json │ +└───────────────┬──────────────────────────────────────────────┘ + │ (เฟส 3, ถ้าต้องการเก็บโปรเจกต์/คำนวณหนัก) +┌───────────────▼──────────────────────────────────────────────┐ +│ ชั้นบริการ service/ (HTTP API) │ +│ POST /api/v1/waters/calculate/* · POST /api/v1/capacities │ +│ GET /api/v1/provinces · /api/v1/crops │ +│ เก็บผลคำนวณ + export PDF (แทน postman collection เดิม) │ +└──────────────────────────────────────────────────────────────┘ +``` + +เหตุผลที่ยัง **ไม่ต้องมี build step**: หน้าเว็บมี 10-13 หน้า, JS รวมไม่ถึง 100 KB — ใช้ ES module ตรง ๆ ได้ ลดความซับซ้อนของ toolchain (ถ้าภายหลังต้องการ bundle ค่อยเพิ่ม Vite โดยไม่ต้องรื้อโครง) + +--- + +## 6. โครงสร้างโฟลเดอร์เป้าหมาย + mapping + +``` +hydraucal/ +├── web/ +│ ├── index.html ← จาก index.html (ซ่อมแล้ว) +│ ├── pages/ +│ │ ├── pond_calculation.html ← ยังไม่มี (poolcal.html เดิมหาย) +│ │ ├── water_value.html +│ │ ├── crop_water.html +│ │ ├── irrigation_pressure.html +│ │ ├── glossary.html +│ │ └── ... +│ ├── assets/css/{creative.css,legacy.css,custom.css} +│ ├── assets/js/{app.js, pages/*.js} +│ ├── assets/img/{icons,logos,photos} +│ ├── manifest.webmanifest +│ └── sw.js +├── core/ ← ใหม่ทั้งหมด +│ ├── units.js +│ ├── evapotranspiration.js +│ ├── water_balance.js +│ ├── reservoir.js +│ ├── irrigation_drip.js +│ ├── irrigation_sprinkler.js +│ ├── channel.js +│ ├── basin.js +│ ├── water_value.js +│ └── scheduling.js +├── data/ +│ ├── schema/*.schema.json +│ ├── crops/{crop_coefficient.json,crop_list.json} +│ ├── climate/eto_by_region.json +│ ├── hydrology/province_runoff.json +│ └── prices/crop_price.json +├── service/ ← เฟส 3 +│ ├── openapi.yaml +│ └── src/... +├── tests/ ← node --test +│ ├── core/*.test.js +│ └── web/assets.test.js ← ตรวจว่า asset ทุกไฟล์มีจริง +├── docs/{SYSTEM-DESIGN.md,DATA-CONTRACT.md,DESIGN.md,AGENTS.md} +├── archive/ ← ของเดิมที่ไม่ได้ใช้ (template ซ้ำ, .download, tmp) +└── README.md +``` + +### Mapping ของเดิม → ที่ใหม่ + +| ของเดิม | ที่ใหม่ | หมายเหตุ | +|---|---|---| +| `index.html` | `web/index.html` | ซ่อมแล้ว (path, markup, `#myBtn`) | +| `coding/scss/*.scss` | build → `web/assets/css/creative.css` | เก็บ scss ไว้เป็น source | +| `coding/css/custom.css` | `web/assets/css/custom.css` | ใช้ `size_card_2` อยู่ | +| `coding/vendor/*` | คงไว้ หรือย้าย `web/assets/vendor/` | ต้องอัปเกรด Bootstrap 4.2.1 → 5.3 ทีหลัง (ต้องแก้ `data-*` → `data-bs-*`) | +| `flat icon/*.svg` | `web/assets/img/icons/` | เปลี่ยนชื่อเป็น ASCII (`retention pond.svg` → `retention_pond.svg`) | +| `logo/**` | `web/assets/img/logos/` | `logo ใหม่/2566-09-08 11-51-40.png` → `logo_mark_2566.png` | +| `coding/js/water demand.js` ฯลฯ | `core/*.js` | เขียนใหม่ (ของเดิมเป็น stub ที่รันไม่ได้) | +| `open data/JSON/ปริมาณ…ภาค*.json` | `data/climate/eto_by_region.json` | รวม 5 ไฟล์เป็นชุดเดียว + เปลี่ยนคีย์ | +| `open data/JSON/Kc*.json` | `data/crops/crop_coefficient.json` | **ต้องสร้างใหม่** (ข้อมูลเสีย) | +| `coding/logic/farm-planning.postman_collection.json` | `service/openapi.yaml` | แปลง 16 endpoint เป็นสเปก | +| `PWA-fam-plans/` | `archive/` | เป็น docker ทดลอง ไม่ผูกกับโปรเจกต์ | +| `_readme.txt` | **ลบทิ้ง** | ⚠️ ไฟล์เรียกค่าไถ่ (ransomware) ไม่ใช่เอกสารโปรเจกต์ | + + +--- + +## 7. โมดูลคำนวณ + +หน้าตาข้อมูลเข้า-ออกมาตรฐาน (ทุกโมดูลเหมือนกัน เพื่อให้ UI สร้างฟอร์มและแสดงผลแบบเดียวกันได้): + +```js +// core/reservoir.js +export function calculateReservoirVolume(input) { + // input: ReservoirInput (ดู DATA-CONTRACT.md) + return { + value: 4800, // ปริมาตรสุทธิ + unit: 'm3', + steps: [ + { label: 'พื้นที่ผิวน้ำ', value: 1200, unit: 'm2' }, + { label: 'ความลึกใช้การ', value: 4, unit: 'm' }, + { label: 'หักน้ำระเหย+รั่วซึม 30 วัน', value: 60, unit: 'm3' } + ], + warnings: ['ความลึกใช้การน้อยกว่า 2 ม. — ระบบจะแห้งเร็วในหน้าแล้ง'] + }; +} +``` + +| โมดูล | หน้าที่ | แหล่งสูตร | +|---|---|---| +| `evapotranspiration.js` | ETo (Penman-Monteith) จากอุณหภูมิ/ความชื้น/ลม/รังสี | ข้อมูล ETo รายจังหวัดใน repo + FAO-56 | +| `water_balance.js` | ETc = Kc × ETo, ปริมาณน้ำรายวัน/รายสัปดาห์ | ตาราง Kc (ต้องสร้างใหม่) | +| `reservoir.js` | สระน้ำท่า / นอง / ฝน / ใต้ดิน | `Document/คำนวณขนาดสระน้ำ/` | +| `irrigation_drip.js` | เทปน้ำหยด / หัวน้ำหยด | `Document/การให้น้ำภายใต้แรงดัน/` | +| `irrigation_sprinkler.js` | มินิสปริงเกลอร์แรงดันต่ำ / สปริงเกลอร์แรงดันสูง (hydraulics: อัตราการไหล, head loss, จำนวนหัวต่อโซน) | `Document/การให้น้ำภายใต้แรงดัน/` | +| `channel.js` | คูส่งน้ำ / คูระบายน้ำ (Manning) | `Document/คูน้ำ`, `Document/คูระบายน้ำ` | +| `basin.js` | บ่อหน่วงน้ำ | `Document/บ่อหน่วงน้ำ` | +| `water_value.js` | มูลค่าน้ำ (บาท/ลบ.ม.) | `Document/มูลค่าน้ำ` | +| `scheduling.js` | จัดรอบเวรใช้น้ำในคูส่งน้ำ | งานใหม่ ( homepage การ์ดที่ 9 ) | +| `units.js` | แปลง ไร่/ตร.ม./ลิตร/บาร์ ฯลฯ | — | + +> **กติกาการเขียนสูตร**: ห้ามใช้ magic number ในฟังก์ชัน — ค่าคงที่ (ความหนาแน่นน้ำ, ค่า g, สัมประสิทธิ์การระเหยของถาดวัด) ต้องประกาศเป็น named export พร้อมหน่วยและแหล่งอ้างอิงใน comment เพราะผู้ใช้ต้องตรวจย้อนกลับได้ + +--- + +## 8. สัญญาข้อมูล (Data Contract) + +### 8.1 กติกาคีย์ + +- คีย์เป็นคำเต็ม ภาษาอังกฤษ snake_case ห้ามใช้ `field2`, `col3`, `a`, `b` +- หน่วยอยู่ในชื่อคีย์เสมอ: `_mm`, `_m3`, `_rai`, `_m`, `_percent`, `_baht_per_m3` +- ค่าที่เป็นตัวเลือกใช้รหัสภาษาอังกฤษ ไม่ใช่คำไทย (ไทยอยู่ใน `label_th`) + +### 8.2 ตัวอย่าง: `data/crops/crop_coefficient.json` (สร้างใหม่แทน Kc ที่เสีย) + +```json +{ + "schema_version": "1.0", + "crop_groups": [ + { + "crop_group_id": "perennial", + "label_th": "พืชหลายปี", + "crops": [ + { + "crop_id": "durian", + "label_th": "ทุเรียน", + "stages": [ + { "stage_id": "establishment", "label_th": "เริ่มปลูก", "duration_day": 365, "kc": 0.60 }, + { "stage_id": "development", "label_th": "เจริญเติบโต", "duration_day": 730, "kc": 0.85 }, + { "stage_id": "maturity", "label_th": "ให้ผลเต็มที่", "duration_day": 1095, "kc": 1.00 } + ] + } + ] + } + ] +} +``` + +### 8.3 ตัวอย่าง: `data/climate/eto_by_region.json` (แปลงจาก 5 ไฟล์เดิม) + +```json +{ + "schema_version": "1.0", + "unit": "mm_per_day", + "regions": [ + { + "region_id": "north", + "label_th": "ภาคเหนือ", + "provinces": [ + { + "province_id": "mae_hong_son", + "label_th": "แม่ฮ่องสอน", + "monthly_eto_mm_per_day": { + "january": 2.83, "february": 3.55, "march": 4.51, + "april": 5.31, "may": 5.20, "june": 4.68, + "july": 4.31, "august": 4.16, "september": 4.22, + "october": 4.05, "november": 3.45, "december": 2.92 + } + } + ] + } + ] +} +``` + +งานแปลง: 144 แถว (139 จังหวัด + 5 แถวหัวตาราง) จาก `open data/JSON/ปริมาณ…ภาค*.json` → ต้องแมปคีย์ `field2…field13` → ชื่อเดือนเต็ม, แปลงชื่อจังหวัดไทย → `province_id` (อ้างรหัสจังหวัดมาตรฐาน 2 หลัก) + +### 8.4 Schema บังคับ + +ทุกไฟล์ข้อมูลต้องมี JSON Schema คู่กันใน `data/schema/` และมี test ตรวจ (`node --test tests/data/*.test.js`) — กันข้อมูลเพี้ยนแบบ P5 หลุดเข้ามาอีก + +--- + +## 9. บริการ (เฟส 3) + +แปลงจาก postman collection เดิม (16 endpoint) เป็น REST ที่มี version: + +| Method | Path | ใช้ทำอะไร | +|---|---|---| +| POST | `/api/v1/waters/calculate/daily` | ปริมาณน้ำอุปโภค-บริโภค ต่อวัน/คน/วัน | +| POST | `/api/v1/waters/calculate/plant` | ความต้องการน้ำของพืช (จาก ETo × Kc) | +| POST | `/api/v1/waters/calculate/animal` | น้ำสำหรับปศุสัตว์ | +| POST | `/api/v1/waters/calculate/industry` | น้ำสำหรับอุตสาหกรรมในฟาร์ม | +| POST | `/api/v1/capacities/reservoir` | ปริมาตรสระ (ท่า/นอง/ฝน/ใต้ดิน) | +| POST | `/api/v1/capacities/runoff` | น้ำท่ารายจังหวัด | +| POST | `/api/v1/capacities/rain_harvest` | พื้นที่รับน้ำฝน | +| POST | `/api/v1/capacities/loss` | น้ำระเหย + รั่วซึม | +| GET | `/api/v1/provinces` · `/api/v1/crops` | ข้อมูลอ้างอิงสำหรับ dropdown | +| POST | `/api/v1/reports/pdf` | export ผลคำนวณเป็น PDF (ใช้ฟอนต์ TH Sarabun New ตาม `Document/แม่แบบไฟล์ที่ส่งออก.txt`) | + +หลักการ: endpoint เรียก `core/` ตัวเดียวกับฝั่งเว็บ — **สูตรอยู่ที่เดียว** ไม่มีสำเนาใน backend + +--- + +## 10. ความเสี่ยง + +| ID | ความเสี่ยง | มาตรการ | +|---|---|---| +| R1 | ⚠️ `_readme.txt` ในราก repo คือข้อความเรียกค่าไถ่ (ransomware) ลงวันที่ 13 พ.ย. 2020 — แปลว่าเครื่อง/โฟลเดอร์นี้เคยถูกโจมตี ไฟล์ที่หาย (creative.min.css, poolcal.html, โลโก้, Kc JSON) อาจเป็นผลจากเหตุนั้น | อย่า commit ไฟล์นี้ · สแกนเครื่องด้วย Windows Defender/full scan · เปลี่ยนรหัสผ่านที่เคยเก็บใน `PWA-fam-plans/v.3.8.yaml` (มี `secret_password` ในไฟล์) · สำรอง repo ขึ้น remote ที่มี versioning | +| R2 | ข้อมูล Kc สร้างใหม่จากศูนย์ อาจคลาดเคลื่อน | อ้างตาราง Kc จากกรมชลประทาน/FAO-56 และเก็บ `source_reference` ในไฟล์ JSON ทุกไฟล์ | +| R3 | ชื่อไฟล์ไทย/เว้นวรรค ทำ URL พังบน server Linux | normalize เป็น ASCII ทั้งหมดในเฟส 1 | +| R4 | Bootstrap 4 → 5 ต้องแก้ `data-toggle`/`ml-auto`/`input-group-prepend` | ทำหลังปิด P1-P4 แล้ว และมี visual check ทุกหน้า | +| R5 | repo 296 MB ทำให้ clone/push ช้า | ย้าย `archive/`, `e-book/`, `แรงบันดาลใจ/`, ไฟล์ `.download` ออก หรือใช้ Git LFS เฉพาะ pdf/docx | + +--- + +## 11. แผนงาน + +| เฟส | งาน | เกณฑ์ตรวจรับ | +|---|---|---| +| **0 — กู้สภาพ (ทำแล้วบางส่วน)** | ซ่อม `index.html`, compile `creative.css` จาก scss, เพิ่ม `legacy.css`, เพิ่ม `#myBtn`, backup ไฟล์เดิม, commit แรก | asset ในเครื่อง 200 ทุกไฟล์ · ไม่มี JS error · tag balance = 0 · `id` ไม่ซ้ำ | +| **1 — จัดบ้าน** | ย้ายเข้าโครง `web/ core/ data/ docs/`, เปลี่ยนชื่อไฟล์เป็น ASCII, ย้ายขยะไป `archive/`, ลบ `_readme.txt`, เพิ่ม `.gitignore` | `find` ไม่พบชื่อไทยใน path ที่ deploy · repo < 50 MB | +| **2 — ข้อมูล + สูตร** | สร้าง `eto_by_region.json` (144 แถว), สร้าง `crop_coefficient.json`, เขียน `core/` 9 โมดูล + unit test | test ผ่านทั้งหมด · ค่าที่คำนวณตรงกับตัวอย่างใน `Document/` อย่างน้อย 3 เคส | +| **3 — หน้าเว็บจริง + PWA** | ทำหน้า `pond_calculation`, `crop_water`, `water_value`, `irrigation_*` ต่อจาก `core/` · เพิ่ม manifest + sw.js | ใช้งาน offline ได้หลังโหลดครั้งแรก · Lighthouse PWA ผ่าน | +| **4 — API** | `service/` ตาม openapi.yaml, ต่อ PDF export | ยิง endpoint ตาม postman เดิมได้ผลเท่ากับฝั่งเว็บ | + +--- + +## 12. Checklist ตรวจรับ (ใช้ซ้ำได้ทุกครั้งที่แก้) + +```bash +# 1) asset ในเครื่องต้องมีจริงทุกไฟล์ (รันบน localhost:8090) +# tests/web/assets.test.js — สร้างในเฟส 1 +node tests/web/assets.test.js + +# 2) markup ต้องสมดุล (ไม่มี tag ค้าง/เกิน) — มีแล้ว +python tools/check_html_balance.py index.html + +# 3) ข้อมูลต้องผ่าน schema และห้ามมี control escape — เฟส 2 +node --test tests/data/ + +# 4) สูตรต้องผ่านเคสอ้างอิง — เฟส 2 +node --test tests/core/ +``` + +ผลตรวจล่าสุด (เฟส 0): ข้อ 2 ผ่าน · ข้อ 1 ตรวจด้วยเบราว์เซอร์จริง — รูป 16/16 โหลดได้, CSS 10/10 ไฟล์เข้า, `dupId` = 0, JS error = 0 + +--- + +## ภาคผนวก A — สิ่งที่ซ่อมใน `index.html` (เฟส 0) + +| เดิม | ใหม่ | +|---|---| +| `../vendor/...`, `/flat_icon/...`, `..dist/clipboard.min.js` | path จริงในโปรเจกต์ (`coding/vendor/...`, `flat%20icon/...`) | +| Bootstrap CDN 4.0.0 + vendor 4.2.1 (โหลดซ้ำ) | ใช้ vendor 4.2.1 ตัวเดียว | +| `../css/creative.min.css` (ไม่มีไฟล์) | `css/creative.css` (compile จาก `coding/scss/creative.scss`) | +| `` (ไม่มี `rel`) | `` + `logo/logo-farm-planning.ico` | +| `` ครอบ `