Files
Bkk1234 dd65e9061f Add Julia+Postgres calculation service with shared golden vectors
- 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
2026-11-16 01:59:22 +07:00

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` หนึ่งครั้ง (รอบเดียว)