Grounded in the actual repo state (3 overlapping frontend stacks, two copies of each formula, no API wiring, no schema, no deploy path). Documents target layout app/ (Vue 3 + Vite) + service/ (HTTP.jl) + core/ offline fallback, engine-selection rule, API contract, data contract, PWA strategy, security items and a 6-phase plan. v0.1 kept in archive/.
336 lines
30 KiB
Markdown
336 lines
30 KiB
Markdown
# 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
|
||
|
||
```
|
||
[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
|
||
```
|
||
|
||
- prod ตั้ง `FARM_CORS_ORIGIN=https://<โดเมน>` (ไม่ใช่ `*`)
|
||
- ถ้า API ตาย เว็บยังคำนวณได้ด้วย `js-offline` — deploy จึงไม่ใช่ single point of failure
|
||
- `service/.env` อยู่นอก git เสมอ · `.env.example` มีชื่อคีย์เท่านั้น
|
||
|
||
---
|
||
|
||
## 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 | โดเมน/เซิร์ฟเวอร์เป้าหมาย | ใช้ host เดิม `103.107.52.82` / ตั้งใหม่ |
|
||
| Q4 | history rewrite ของ S1/S2 | ทำเลย (ต้อง force-push) / เปลี่ยน repo เป็น private ก่อน |
|