SYSTEM-DESIGN — irrcal / farm-planning
เวอร์ชัน 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. ผลิตภัณฑ์
ระบบเดียว 3 งาน ที่วันนี้กระจายอยู่ 3 สแตก:
| งาน |
ของวันนี้ |
ผู้ใช้ |
ที่อยู่ในเป้าหมาย |
| 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 |
คำนวณถูกและตรวจย้อนได้ |
ทุกฟังก์ชันคืน 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. สภาพปัจจุบัน (วัดจริง 23 พ.ย. 2026, commit 4f74a50 + ของที่ยังไม่ commit)
| ชั้น |
ของจริงในรีโป |
สถานะ |
| เชลล์เว็บ |
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/ |
สรุป: สแตกซ้อน 3 ชุด (vanilla BS4 / Vue BS5 / static docs) · ตรรกะคำนวณซ้ำ 2 ภาษา · หน้าเว็บยังไม่เรียก API เลย
3. ปัญหาสถาปัตยกรรมที่ต้องแก้
| # |
ปัญหา |
หลักฐาน |
ผลกระทบ |
| 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. หลักการออกแบบ
- หนึ่ง frontend หนึ่งภาษา — Vue 3 + Vite + Bootstrap 5.3 (SCSS overrides) เท่านั้น · ไม่มี jQuery ไม่มี Bootstrap 4 ในแอปใหม่
- สูตรอยู่ที่เดิม ไม่ย้ายเข้า component —
core/*.js (pure ES module) และ service/src/formulas.jl · view ทำหน้าที่แค่เก็บ input → เรียก → วาดผล
- ผลลัพธ์มีโครงเดียวทุกเอนจิน —
{ value, unit, steps[], warnings[], engine, formula_version, run_id? } สลับแหล่งคำนวณได้โดย UI ไม่ต้องแก้
- ออฟไลน์เป็นสภาพปกติ ไม่ใช่ของแถม — ทุกสูตรที่เปิดใช้ต้องรันในเบราว์เซอร์ได้ และให้ผลตรงกับเซิร์ฟเวอร์ (golden)
- ข้อมูลผู้ใช้ห้ามแต่ง — Kc, ราคาพืช, ค่าระบายน้ำ ที่ระบบไม่มีแหล่งอ้างอิง ให้ผู้ใช้กรอกและแสดงที่มา (กฎเดียวกับ
AGENTS.md)
- ค่าออกแบบอยู่ที่
DESIGN.md ที่เดียว — สี ฟอนต์ รัศมี ระยะ · component ห้าม hardcode hex
5. สถาปัตยกรรมเป้าหมาย
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
ของเดิม → ที่ใหม่
| ของเดิม |
ที่ใหม่ |
หมายเหตุ |
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. สัญญาข้อมูล (Data Contract)
7.1 กติกา
- คีย์เต็มคำ 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 ไฟล์ใช้ไม่ได้)
7.2 รูปผลลัพธ์มาตรฐาน (ทั้ง JS และ Julia — ต้องเหมือนกัน)
7.3 API (v1) — มีแล้ว 4 + แผน
| 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/<module>.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://<lan-ip> ติดตั้งไม่ได้ |
10. Deploy
- พอร์ตทุกตัวมาจาก
.env ที่ราก repo (.env.example ขึ้น git, .env ไม่ขึ้น)
- prod:
FARM_CORS_ORIGIN ใส่ origin จริง และไม่ต้อง publish DB_HOST_PORT/API_HOST_PORT ออกนอก
- ถ้า API ตาย เว็บยังคำนวณได้ด้วย
js-offline — deploy จึงไม่ใช่ single point of failure
service/.env (แบบรันบน host) และ .env (แบบ compose) อยู่นอก git เสมอ
11. ความปลอดภัย
| # |
เรื่อง |
มาตรการ |
| 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 |
12. แผนงาน
| เฟส |
งาน |
เกณฑ์ตรวจรับ |
| 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 |
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 ตรวจรับ (ทุกครั้งที่แก้)
15. คำถามที่ยังต้องตัดสิน
| # |
คำถาม |
ตัวเลือก |
| Q1 |
ย้าย /docs (ตำรา) ไป build ใน Vite ไหม |
คง static (แนะนำ) / แปลงเป็น view |
| Q2 |
เก็บประวัติ farm-blog ไว้ไหม |
git bundle ไว้ archive/ (แนะนำ) / ทิ้ง |
| Q3 |
โดเมน/เซิร์ฟเวอร์เป้าหมาย |
git.hobbypj.com (repo ใหม่) / ตั้งโดเมนแยกสำหรับเว็บ |
| Q4 |
history rewrite ของ S1/S2 |
ทำเลย (ต้อง force-push) / เปลี่ยน repo เป็น private ก่อน |