Files
sprinkler-calculation/AGENTS.md
T
Bkk1234 1b6c56b47c fix(compose): default DB_PASSWORD so interpolation never fails
':?' made docker compose config/up fail whenever .env was absent (fresh
clone, different working dir, Docker Desktop UI). Falls back to a
documented dev password; prod must still set a real one.
2026-11-23 02:16:16 +07:00

93 lines
6.8 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)
### Docker (web + API + PostgreSQL) — พอร์ตมาจาก `.env`
```bash
cp .env.example .env # ไม่บังคับถ้าอยากใช้ค่า dev (DB_PASSWORD ว่าง = farm_planning_dev)
docker compose build # ครั้งแรก ~5 นาที (Julia Pkg.instantiate)
docker compose up -d
docker compose ps # รอ Up (healthy) ทั้ง 3 บริการ
curl -s http://127.0.0.1:8097/healthz # ok
curl -s http://127.0.0.1:8000/api/v1/health # database.connected = true
docker compose down # หยุด · เพิ่ม -v ถ้าต้องล้างฐานข้อมูล
```
- `WEB_CONTAINER_PORT`/`WEB_HOST_PORT` · `API_CONTAINER_PORT`/`API_HOST_PORT` · `DB_HOST_PORT` = ตัวแปรเดียวที่ต้องแก้
- `deploy/nginx.conf.template` ใช้ `${WEB_CONTAINER_PORT}` (nginx image envsubst ให้เอง) และ proxy `/api/` → `api:${API_CONTAINER_PORT}`
- แก้ไฟล์ static = ต้อง `docker compose up -d --build` (COPY เข้า image ไม่ใช่ mount)
- รายละเอียดทุกตัวแปร: `service/README.md` §6
## อัปเดตเวอร์ชัน — ห้ามแก้มือทีละไฟล์
```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` หนึ่งครั้ง (รอบเดียว)