Files
sprinkler-calculation/SYSTEM-DESIGN.md
T

337 lines
30 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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. หลักการออกแบบ
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. สถาปัตยกรรมเป้าหมาย
```
┌────────────────────────────────────────────────────────────────────┐
│ ชั้นนำเสนอ 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
```
### 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
```
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
│ └── .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/
```
### ของเดิม → ที่ใหม่
| ของเดิม | ที่ใหม่ | หมายเหตุ |
|---|---|---|
| `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 — ต้องเหมือนกัน)
```json
{
"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..."
}
```
### 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
```
[docker compose] (ตอนนี้)
web nginx:alpine listen ${WEB_CONTAINER_PORT} · root /app · /api/ → api
api julia:1.13-bookworm FARM_API_HOST=0.0.0.0 · FARM_API_PORT=${API_CONTAINER_PORT}
db postgres:17-alpine volume pgdata · service/db/001_init.sql (ครั้งแรก)
[แบบเดิม ไม่ใช้แล้ว] nginx บน host + systemd unit + postgres ในเครื่อง
```
- พอร์ตทุกตัวมาจาก `.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 ตรวจรับ (ทุกครั้งที่แก้)
```bash
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)
```
---
## 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 ก่อน |