- service/: Julia HTTP API (HTTP.jl + LibPQ), formulas.jl as source of truth - service/db/001_init.sql: calculation_runs (append-only), provinces, eto_monthly - tests/golden/vectors.json: single fixture set enforced on both JS and Julia - .gitignore: keep secrets (DB env, contracts, financial records, ransomware note) out - AGENTS.md: document service commands and formula-change rule
76 lines
5.6 KiB
Markdown
76 lines
5.6 KiB
Markdown
# AGENTS.md — กติกาการทำงานใน repo นี้
|
|
|
|
เว็บ static (SPA + PWA) **ไม่มี build step** — แก้ไฟล์แล้วเสิร์ฟได้เลย
|
|
เอกสารออกแบบ: `SYSTEM-DESIGN.md` (สถาปัตยกรรม/แผน) · `DESIGN.md` (สี ฟอนต์ คอมโพเนนต์)
|
|
|
|
## โครงสร้างที่ต้องยึด
|
|
|
|
```
|
|
index.html shell เดียวของแอป (nav + <main id="view"> + footer)
|
|
partials/*.html หนึ่งไฟล์ต่อหนึ่งหน้า (มี <style>/<script> ของตัวเองได้)
|
|
app/router.js hash router (#/route) · ห้ามลิงก์ ./x.html ภายใน partial
|
|
app/pwa.js register SW + auto-update + ปุ่มติดตั้ง + ป้ายออนไลน์
|
|
app/version.js ค่า build ที่หน้าเว็บฝังไว้
|
|
sw.js service worker (VERSION = ชื่อ cache)
|
|
core/*.js สูตรคำนวณ pure module (ไม่แตะ DOM, มี unit test)
|
|
data/**/*.json ข้อมูลที่แอปอ่าน (คีย์เต็มคำ + หน่วยในชื่อคีย์)
|
|
tools/*.py สคริปต์สร้างข้อมูล/ไอคอน/ตรวจสอบ
|
|
tests/*.test.mjs node --test
|
|
archive/ ของเดิมที่เลิกใช้ (ไฟล์ static รุ่นก่อน, backup)
|
|
```
|
|
|
|
## ก่อนส่งงานทุกครั้ง (ต้องผ่านทั้ง 4 ข้อ)
|
|
|
|
```bash
|
|
python tools/check_app.py # ลิงก์ hash, PRECACHE มีจริง, version ตรงกัน, ไม่มีอีโมจิ
|
|
python tools/check_html_balance.py index.html
|
|
node --test tests/*.test.mjs
|
|
python -m http.server 8090 # แล้วเปิด http://localhost:8090 ตรวจด้วยตา 1 รอบ
|
|
```
|
|
|
|
## บริการ API (Julia + PostgreSQL)
|
|
|
|
```bash
|
|
# ติดตั้ง dependency ครั้งแรก
|
|
julia --project=service -e 'using Pkg; Pkg.add(["HTTP","JSON3","LibPQ"])'
|
|
|
|
# รัน API (ค่า env อยู่ใน service/.env — คัดลอกจาก .env.example แล้วใส่รหัสเอง)
|
|
julia --project=service service/src/server.jl # http://127.0.0.1:8000
|
|
|
|
# ทดสอบสูตรทั้งสองฝั่ง (ต้องได้เลขตรงกันตาม golden vectors)
|
|
julia --project=service service/test/runtests.jl
|
|
node --test tests/*.test.mjs
|
|
```
|
|
|
|
- สูตรอยู่ที่ `service/src/formulas.jl` (แหล่งความจริง) — `core/*.js` เป็นตัวสำรองตอนออฟไลน์
|
|
- แก้สูตร = แก้ 3 ที่พร้อมกัน: `core/*.js`, `service/src/formulas.jl`, `tests/golden/vectors.json`
|
|
- สคีมา DB: `service/db/001_init.sql` · สัญญา API: `service/openapi.yaml`
|
|
- ห้าม commit `service/.env` (มีรหัส DB)
|
|
|
|
## อัปเดตเวอร์ชัน — ห้ามแก้มือทีละไฟล์
|
|
|
|
```bash
|
|
node scripts/bump-version.mjs 2026.11.16.5 # bump ทุกที่พร้อมกัน
|
|
node scripts/bump-version.mjs --check # ตรวจว่าตรงกัน
|
|
```
|
|
|
|
เวอร์ชันต้องตรงกัน 5 ที่: `sw.js` (VERSION = ชื่อ cache), `app/version.js`,
|
|
`app/version.json`, `index.html` (`?v=` ของ `app/*.js` และ `app.css`), `package.json`
|
|
ถ้าไม่ตรง → ผู้ใช้จะเห็น "แก้แล้วแต่เว็บยังโชว์ของเก่า"
|
|
|
|
## กฎที่ห้ามละเมิด
|
|
|
|
- **ห้าม commit ไฟล์ส่วนตัว/ความลับ**: `หลักฐาน*/`, `สัญญาจ้าง*`, `_readme.txt` (ข้อความเรียกค่าไถ่),
|
|
`PWA-fam-plans/v.3.8.yaml` (มีรหัสผ่าน), `~WRL*.tmp`, `*.download`
|
|
- ข้อมูลที่ผู้ใช้กรอกเอง (เช่น Kc ของพืช) **ห้ามแต่งค่าขึ้นเอง** — ให้เว็บรับค่าจากผู้ใช้และบอกที่มาให้ชัด
|
|
- สูตรคำนวณต้องอยู่ใน `core/` เท่านั้น ห้ามเขียนสูตรใน partial
|
|
- อีโมจิไม่ใช้ในหน้าเว็บ (ลูกศร/ขีดคั่นใช้ได้)
|
|
- ภาษาไทยบนหน้าเว็บ ใช้ "ต้นทาง/กลางทาง/ปลายทาง" ไม่ใช้ "จุดเปลี่ยน" และเลี่ยงคำอังกฤษลอย
|
|
- ลบ/ย้ายไฟล์เดิม → ย้ายเข้า `archive/` ก่อน ไม่ลบทิ้ง
|
|
|
|
## หมายเหตุ PWA
|
|
|
|
- localhost หรือ https เท่านั้นที่ service worker ทำงาน (`http://<lan-ip>` จะติดตั้งไม่ได้)
|
|
- ครั้งแรกต้องออนไลน์ก่อน หลังจากนั้นเปิดออฟไลน์ได้ทุกหน้า
|
|
- หลัง bump แล้ว ถ้าเบราว์เซอร์ยังโชว์ของเก่า ให้ `Ctrl+Shift+R` หนึ่งครั้ง (รอบเดียว)
|