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

5.6 KiB

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 ข้อ)

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)

# ติดตั้ง 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)

อัปเดตเวอร์ชัน — ห้ามแก้มือทีละไฟล์

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