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 ไม่ถูกต้อง | `

` ครอบ `

`, `` ครอบ `

`, `id` ซ้ำ 4 จุด, `

` เกิน 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/.js` + `service/src/formulas.jl` + `tests/golden/vectors.json` แล้วรันทั้ง `node --test tests/*.test.mjs` และ `julia --project=service service/test/runtests.jl` +- `formula_version` ต้อง bump เมื่อตัวเลขเปลี่ยน — แถวเก่าใน `calculation_runs` ไม่ถูกแก้ (append-only) +- ค่าคงที่ทุกตัวเป็น named export พร้อมหน่วย + แหล่งอ้างอิง (`RAI_IN_SQUARE_METRE = 1600`, `CUBIC_METRE_PER_MM_PER_RAI = 1.6`) +- เปิดใช้สูตรใหม่ (irrigation / คูส่ง-ระบาย / รอบเวร) ได้ต่อเมื่อยืนยันกับ `Document/` ต้นฉบับแล้วเท่านั้น — ห้ามเดา + +| โมดูล | สถานะ | แหล่งสูตร | +|---|---|---| +| `crop_water` | ใช้งาน | FAO-56 (ETc = Kc × ETo) | +| `pond` | ใช้งาน | `Document/คำนวณขนาดสระน้ำ/` | +| `drip` / `sprinkler` | ยังไม่เปิด | `Document/การให้น้ำภายใต้แรงดัน/` | +| `channel` / `drain` | ยังไม่เปิด | `Document/คูน้ำ`, `Document/คูระบายน้ำ` | +| `water_value` | ยังไม่เปิด | `Document/มูลค่าน้ำ` | +| `scheduling` | ยังไม่เปิด | งานใหม่ | + +--- + +## 9. PWA / ออฟไลน์ + +| เรื่อง | ข้อกำหนด | +|---|---| +| precache | สร้างจาก manifest ที่ Vite ปล่อย (`dist/assets/*`) + `data/*.json` ที่หน้าต้องใช้ · ห้ามพิมพ์มือ | +| กลยุทธ์ | text/HTML = network-first + fallback cache · รูป/ฟอนต์/ไอคอน = cache-first · JSON ข้อมูล = stale-while-revalidate | +| อัปเดต | `updatefound` → `SKIP_WAITING` → `controllerchange` reload หนเดียว (guard 8 วิ) | +| หน้า offline | `offline` view บอกว่าหน้าไหนเคยเปิดได้ | +| ป้ายสถานะ | footer: ออนไลน์/ออฟไลน์ + build + formula_version | +| ข้อจำกัด | SW ทำงานเฉพาะ `localhost` หรือ `https` · `http://` ติดตั้งไม่ได้ | + +--- + +## 10. Deploy + +``` +[nginx :443] + / → dist/ (Vue build · hash router จึงไม่ต้อง rewrite) + /docs/ → dist/docs/ (ตำรา 10 บท) + /api/ → proxy_pass http://127.0.0.1:8000 +[julia service] systemd unit farm-api.service · FARM_API_HOST=127.0.0.1 +[postgresql] psql -f service/db/001_init.sql · seed ETo ด้วย tools/seed_eto.py ``` -งานแปลง: 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 หลุดเข้ามาอีก +- prod ตั้ง `FARM_CORS_ORIGIN=https://<โดเมน>` (ไม่ใช่ `*`) +- ถ้า API ตาย เว็บยังคำนวณได้ด้วย `js-offline` — deploy จึงไม่ใช่ single point of failure +- `service/.env` อยู่นอก git เสมอ · `.env.example` มีชื่อคีย์เท่านั้น --- -## 9. บริการ (เฟส 3) +## 11. ความปลอดภัย -แปลงจาก 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 +| S1 | `_readme.txt` = ข้อความเรียกค่าไถ่ (13 พ.ย. 2020) ในรีโป public | ลบไฟล์ · สแกนเครื่อง · ตัดสินใจเรื่อง history (`filter-repo`/BFG **ต้องขออนุญาตก่อน force-push**) | +| S2 | `PWA-fam-plans/v.3.8.yaml` มี `DB_PASSWORD` plaintext ใน history | หมุนรหัสทันที (ถือว่ารั่วแล้ว) · ลบไฟล์ออกจาก tree | +| S3 | API ไม่มี auth | v1 เปิด anonymous โดยตั้งใจ · ใส่ rate limit ต่อ IP ที่ nginx · ไม่เก็บ PII · `input_payload` เก็บเฉพาะค่าคำนวณ | +| S4 | input ไม่ถูกตรวจฝั่ง JS | ตรวจทั้งสองฝั่งด้วยกติกาเดียวกับ `formulas.jl` + `core/*.js` · 400 ภาษาไทย | +| S5 | ผลคำนวณถูกแก้ทีหลัง | `calculation_runs` append-only (ห้าม UPDATE/DELETE) | +| S6 | ไฟล์ส่วนตัวยังค้างใน tree | `.gitignore` ครอบแล้ว (`หลักฐาน*/`, `สัญญาจ้าง*`, `แรงบันดาลใจ/`) — ห้าม `git add -A` | --- -## 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. แผนงาน +## 12. แผนงาน | เฟส | งาน | เกณฑ์ตรวจรับ | |---|---|---| -| **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 เดิมได้ผลเท่ากับฝั่งเว็บ | +| **0 — ยุบสแตก** | สร้าง `app/` (Vite) · ย้าย farm-blog เป็น view · พอร์ต 4 หน้าเดิม (home, crop-water, pond, irrigation) · ย้ายของเก่าเข้า `archive/` · ลบ `_readme.txt` | เปิดทุก route ได้ · ไม่มี Bootstrap 4/jQuery ใน `app/` · `npm run build` ผ่าน | +| **1 — ต่อ API** | `composables/useCalculation.js` + `api/client.js` · เพิ่ม `/provinces` ใน `api.jl` · ป้ายเอนจิน | ออนไลน์ → engine `julia` + `run_id` · ปิด API → ยังคำนวณได้และป้ายเปลี่ยน · ตัวเลขตรง golden | +| **2 — PWA ใหม่** | SW สร้างจาก build manifest · auto-update · offline view | reload ขณะ offline แล้วเปิดหน้าเดิมได้ · bump แล้วได้ของใหม่ใน reload เดียว | +| **3 — ข้อมูล + schema** | `data/schema/*.schema.json` + test ตรวจ · `tools/seed_eto.py` เข้า DB · `crop_coefficient.json` (รอค่าจากผู้ใช้) | `node --test tests/data/` ผ่าน · จำนวนแถว `eto_monthly` = 116×12 | +| **4 — สูตรเพิ่ม** | irrigation/canal/scheduling ตาม `Document/` | golden vectors ใหม่ + เปิดหน้าได้จริง ไม่ใช่ "ยังไม่เปิดใช้" | +| **5 — deploy** | `deploy/` nginx + systemd + Dockerfile | เข้าเว็บผ่านโดเมนจริงได้ · API ผ่าน `/api/` · SW ทำงานบน https | --- -## 12. Checklist ตรวจรับ (ใช้ซ้ำได้ทุกครั้งที่แก้) +## 13. ความเสี่ยง + +| ID | ความเสี่ยง | มาตรการ | +|---|---|---| +| R1 | พอร์ต Vue แล้วพฤติกรรมเพี้ยน (ค่าที่เคยคำนวณได้ไม่ตรง) | พอร์ตด้วย golden vectors ก่อน/หลัง · เก็บ partial เดิมใน `archive/` ไว้เทียบ | +| R2 | สูตรสองภาษาต่างกันเงียบ ๆ | golden test ถูกบังคับก่อน commit (§8) | +| R3 | Kc ไม่มีแหล่งที่มา | ให้ผู้ใช้กรอก + แสดง `source_reference` · **ห้ามแต่งค่า** | +| R4 | repo หนัก (30 MB coding + 32 MB รูป + template ซ้ำ) | ย้ายเข้า `archive/` แล้วตัดออกจาก HEAD · ถ้าต้องลด clone ใช้ Git LFS เฉพาะ pdf/docx | +| R5 | ประวัติ git มีความลับ | S1/S2 | +| R6 | Vite build พังบน path ย่อย | ตั้ง `base` ให้ตรง และทดสอบ `vite preview` ก่อนขึ้น nginx | + +--- + +## 14. 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/ +npm --prefix app run build # build ผ่าน +node --test tests/*.test.mjs # สูตร JS + golden +julia --project=service service/test/runtests.jl # สูตร Julia + golden +python tools/check_app.py # ลิงก์, PRECACHE, version ตรงกัน, ไม่มีอีโมจิ +node scripts/bump-version.mjs --check # version ตรงทุกที่ +python -m http.server 8090 # ตรวจด้วยตา 1 รอบ (desktop + 360px) ``` -ผลตรวจล่าสุด (เฟส 0): ข้อ 2 ผ่าน · ข้อ 1 ตรวจด้วยเบราว์เซอร์จริง — รูป 16/16 โหลดได้, CSS 10/10 ไฟล์เข้า, `dupId` = 0, JS error = 0 - --- -## ภาคผนวก A — สิ่งที่ซ่อมใน `index.html` (เฟส 0) +## 15. คำถามที่ยังต้องตัดสิน -| เดิม | ใหม่ | -|---|---| -| `../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` | -| `

` ครอบ `

`, `` ครอบ `

`, `

…

` | โครงสร้างถูกต้องตาม HTML5 | -| `id="inputGroup-sizing-default"` ซ้ำ 4 ครั้ง | `label-name`, `label-email`, `label-subject`, `label-message` | -| `text-indent: 2.5emv`, `width=100px` | `2.5em`, `width="100"` | -| ไม่มี `#myBtn` (แต่ `custom.js` เรียก) | เพิ่มปุ่ม + `coding/css/gototop.css` | -| `clipboard.min.js` หาย | inline script ใช้ `navigator.clipboard` + fallback | -| `
` คั่นกลาง `.row > .col-*` | เอา wrapper ออก ให้ grid ถูกต้อง | -| โลโก้ 7 ไฟล์ที่ไม่มีใน repo (5 กรม + Builk + Fastwork) | เปลี่ยนเป็นลิงก์ข้อความ (ไม่เกิด broken image) | -| คำผิด: ดาว์นโหลด, ดูส่งน้ำ, ดูระบายน้ำ, Lat's Go, ความคุ้มค้า, หนึ่งใจช่องทาง | แก้เป็น ดาวน์โหลด, คูส่งน้ำ, คูระบายน้ำ, ไปดู, ความคุ้มค่า, อีกหนึ่งช่องทาง | - -ซอร์สเดิมสำรองไว้ที่ `index.html.bak-20261116` +| # | คำถาม | ตัวเลือก | +|---|---|---| +| Q1 | ย้าย `/docs` (ตำรา) ไป build ใน Vite ไหม | คง static (แนะนำ) / แปลงเป็น view | +| Q2 | เก็บประวัติ `farm-blog` ไว้ไหม | `git bundle` ไว้ `archive/` (แนะนำ) / ทิ้ง | +| Q3 | โดเมน/เซิร์ฟเวอร์เป้าหมาย | ใช้ host เดิม `103.107.52.82` / ตั้งใหม่ | +| Q4 | history rewrite ของ S1/S2 | ทำเลย (ต้อง force-push) / เปลี่ยน repo เป็น private ก่อน | diff --git a/archive/SYSTEM-DESIGN.v0.1-20261116.md b/archive/SYSTEM-DESIGN.v0.1-20261116.md new file mode 100644 index 0000000..44ecda3 --- /dev/null +++ b/archive/SYSTEM-DESIGN.v0.1-20261116.md @@ -0,0 +1,369 @@ +# SYSTEM DESIGN — hydraucal / sprinkler-calculation + +> เวอร์ชัน 0.1 (16 พ.ย. 2026) · สถานะ: ออกแบบหลังสำรวจ repo จริง · เอกสารนี้เป็น "แบบก่อสร้าง" ไม่ใช่รายงานสถานะ + +--- + +## 1. บริบทและเป้าหมาย + +เว็บ `farm-planning` เป็นเครื่องมือช่วยตัดสินใจเรื่องน้ำในแปลงเกษตร (คำนวณขนาดสระ, ปริมาณน้ำของพืช, ระบบน้ำหยด/สปริงเกลอร์, คูส่ง-คูระบาย, บ่อหน่วงน้ำ) ปัจจุบันเป็น static site ยุค 2019 ที่พึ่ง Start Bootstrap "Creative" + Bootstrap 4 และตัวคำนวณยังเป็นไฟล์ JS ที่ไม่ทำงาน + +เป้าหมายของ repo `hydraucal`: + +| เป้าหมาย | คำอธิบาย | +|---|---| +| G1 ใช้งานได้จริง | หน้าเว็บทุกหน้าต้องเปิดได้ ไม่มี asset 404 ไม่มี JS error | +| G2 คำนวณถูกและตรวจสอบได้ | สูตรแยกเป็นโมดูลบริสุทธิ์ (pure) มี unit test เทียบค่าอ้างอิง | +| G3 ข้อมูลอ่านได้โดยมนุษย์ | JSON คีย์เต็มคำ ไม่มี `field2`/`field3` แบบ export จาก Excel | +| G4 ต่อยอดเป็น PWA + API | ใช้ offline ได้ และมี backend รับงานคำนวณหนัก/เก็บโปรเจกต์ | + +--- + +## 2. สถานะปัจจุบัน (วัดจริงจาก repo) + +| รายการ | ค่า | +|---|---| +| ไฟล์ทั้งหมด (ไม่รวม `.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`) | + +### โครงสร้างระดับบนสุดที่ปะปนกันอยู่ + +``` +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. ปัญหาที่ต้องแก้ (เรียงตามผลกระทบ) + +| # | ปัญหา | หลักฐาน | ผลกระทบ | +|---|---|---|---| +| P1 | path ของ asset พังทั้งหน้า | `../vendor/...`, `/flat_icon/...`, `..dist/clipboard.min.js` ไม่มีอยู่จริง | หน้าเว็บไม่มีสไตล์ ไม่มีไอคอน | +| P2 | ไฟล์ CSS หลักหาย | `creative.min.css` ไม่มีใน repo (เหลือแต่ `coding/scss/*.scss`) | hero/nav/การ์ดเสียรูปแบบ | +| P3 | markup ไม่ถูกต้อง | `

` ครอบ `

`, `` ครอบ `

`, `id` ซ้ำ 4 จุด, `

` เกิน 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` | +| `

` ครอบ `

`, `` ครอบ `

`, `

…

` | โครงสร้างถูกต้องตาม HTML5 | +| `id="inputGroup-sizing-default"` ซ้ำ 4 ครั้ง | `label-name`, `label-email`, `label-subject`, `label-message` | +| `text-indent: 2.5emv`, `width=100px` | `2.5em`, `width="100"` | +| ไม่มี `#myBtn` (แต่ `custom.js` เรียก) | เพิ่มปุ่ม + `coding/css/gototop.css` | +| `clipboard.min.js` หาย | inline script ใช้ `navigator.clipboard` + fallback | +| `
` คั่นกลาง `.row > .col-*` | เอา wrapper ออก ให้ grid ถูกต้อง | +| โลโก้ 7 ไฟล์ที่ไม่มีใน repo (5 กรม + Builk + Fastwork) | เปลี่ยนเป็นลิงก์ข้อความ (ไม่เกิด broken image) | +| คำผิด: ดาว์นโหลด, ดูส่งน้ำ, ดูระบายน้ำ, Lat's Go, ความคุ้มค้า, หนึ่งใจช่องทาง | แก้เป็น ดาวน์โหลด, คูส่งน้ำ, คูระบายน้ำ, ไปดู, ความคุ้มค่า, อีกหนึ่งช่องทาง | + +ซอร์สเดิมสำรองไว้ที่ `index.html.bak-20261116`