# Contributing to 485Tech.com

ขอบคุณที่ช่วยพัฒนา 485Tech.com. โปรเจกต์นี้เน้นเครื่องมือที่ใช้งานได้จริงใน browser, ลดการส่งข้อมูลออกจากเครื่อง, มี accessibility พื้นฐาน และมีหลักฐาน validation ก่อน release. เอกสารนี้ใช้กับ pull request, direct commit และงานที่ AI ช่วยดำเนินการ.

## ก่อนเริ่มงาน

ตรวจ branch และ working tree ก่อนเสมอ:

```bash
git status --short --branch
```

อ่าน `AGENTS.md`, `docs/project-architecture.md`, `docs/code-commenting-standard.md`, `docs/tool-authoring-standard.md` และ `docs/release-checklist.md`. ระบุ issue/intent ที่จะแก้, acceptance criteria, data boundary, files ที่คาดว่าจะเปลี่ยน และ test plan. ห้าม reset หรือ revert งานของผู้อื่นเพียงเพื่อทำให้ working tree สะอาด.

## โครงสร้างและจุดแก้ไข

Business logic ของ public pages อยู่ใน `src/` และ `public/scripts/`; generated standalone HTML อยู่ใน `public/tools/`. Build script `scripts/build.mjs` เป็น source ของ catalog/page generation. หาก tool เป็น adapter ให้ trace ไปยัง shared runtime ก่อนเพิ่ม code ซ้ำ.

| ต้องการแก้ | แก้ที่ | ห้ามทำ |
|---|---|---|
| Tool behavior เดียว | `public/scripts/tools/apps/<id>/index.js` | แก้ generated HTML เท่านั้น |
| Shared behavior | `tools-core.js`, `mega-tools.js`, `pro-tools*.js` ตามกลุ่ม | copy logic ไป 159 adapters โดยไม่จำเป็น |
| Standalone shell | `src/app-layout.html`, `tools-app.js`, shared CSS | patch หน้า generated เดียว |
| Catalog capability | `src/tool-capabilities.json`, i18n และ validator | ใส่ claim ใน UI โดยไม่มี metadata |
| Public page/SEO | source page, `src/pages.json`, build | เพิ่ม thin page จำนวนมากเพื่อ SEO |
| Worker/security/API | `src/worker/`, `wrangler.toml`, SECURITY docs | เปิด binding/secret/deploy โดยไม่ตรวจ authorization |

## Comment and documentation standard

ใช้ comment เพื่ออธิบาย **เหตุผล, invariant, contract, lifecycle, side effect, privacy boundary และ failure mode**. อย่าอธิบาย syntax ที่อ่านออกอยู่แล้ว. Module สำคัญควรมี JSDoc header ตามมาตรฐานใน `docs/code-commenting-standard.md`; public-like function ควรระบุ input, output, async/throw behavior และ cleanup.

Comment privacy ต้องตรงกับ runtime. ถ้า tool ประมวลผลใน browser แต่ดาวน์โหลด model/library จาก CDN ให้เขียนว่า browser inference/local input พร้อม first-use network dependency; ห้ามใช้ “fully offline”. ถ้าเพิ่ม fetch/upload ต้องเพิ่ม threat model, consent, capability metadata, i18n copy และ tests ใน change เดียวกัน.

## Tool development contract

Tool ใหม่ต้องมี stable id, manifest/catalog entry, translated name/description, keyboard-reachable primary controls, visible status/error state, empty state, valid/invalid input behavior, cleanup และ download/copy behaviorตามที่ทำได้จริง. File tool ต้อง validate extension/MIME/size, ไม่แทนที่ input เมื่อ reject, แสดงข้อจำกัด และ revoke object URLs.

ทุก tool live ต้องมี capability metadata อย่างน้อย `client`, `download`, `clientSide`, `offline`, `needsNetwork`, `privacyKey` และ `limitationsKey` ผ่าน `npm run validate:tools`. ใส่ `fileTypes`/`maxFileBytes` เฉพาะเมื่ออ่านได้จาก implementation และให้ตรงกับ UI.

## Accessibility and UX

ใช้ semantic elements, label ที่เชื่อมกับ controls, `aria-*` เฉพาะที่จำเป็น, focus state ที่มองเห็นได้, keyboard path และข้อความ status ที่อ่านได้โดย screen reader. อย่าซ่อน error ด้วยสีอย่างเดียว. ตรวจที่ความกว้างอย่างน้อย 320–390px เมื่อแก้ layout และตรวจ reduced-motion rule หากเพิ่ม animation.

Shared runtime มี blast radius สูง: เปลี่ยน core/shell/shared CSS ต้องรัน unit, smoke, functional matrix, deep sweep และ UI regression. หากเพิ่ม UI-specific behavior ให้เพิ่ม focused QA และตรวจไทย/อังกฤษอย่างน้อยหนึ่ง viewport ต่อ locale.

## Test and release workflow

รันจาก root repository:

```bash
npm run build
npm run validate:tools
node scripts/validate_syntax.mjs
node scripts/unit-app-test.mjs
node scripts/bg-remover-test.mjs
node scripts/worker-smoke.mjs
node scripts/smoke_all_tools.mjs
node scripts/functional_extra.mjs
node scripts/functional-matrix.mjs
node scripts/deep-tool-sweep.mjs
node scripts/ui-regression.mjs
node scripts/qa-json-snapshots.mjs
node scripts/qa-capability-details.mjs
git diff --check
CI=1 npx --yes wrangler@4.127.0 deploy --dry-run --env production
```

ไม่จำเป็นต้องรันทุกชุดสำหรับ typo ที่ไม่กระทบ runtime แต่ต้องบอกเหตุผลและรัน full gate ก่อน production release. รายงานผลด้วยตัวเลขและ log/evidence ที่ชี้กลับไปยัง `docs/`.

## Commit and pull request standard

หนึ่ง commit ควรมี intent เดียวและชื่อแบบ imperative conventional style เช่น `feat: add local snapshot workspace`, `fix: preserve file queue on rejection`, `docs: document deployment source of truth`. Generated output ต้อง rebuild ใน commit เดียวกับ source change; ห้าม commit secret หรือ local path.

PR/commit summary ต้องมีตารางต่อไปนี้:

| หัวข้อ | เนื้อหา |
|---|---|
| Intent | ปัญหาและ outcome |
| Changed scope | source/runtime/generated/docs |
| Data contract | local storage/network/file limits/privacy |
| Validation | exact commands และผลตัวเลข |
| Known limitations | สิ่งที่ยังไม่จบและ impact |
| Deployment | local/dry-run/Cloudflare evidence; ห้าม claim เกินหลักฐาน |
| Follow-up | acceptance criteria และลำดับถัดไป |

## Production deployment rule

`git push` ไม่เท่ากับ production deploy. ต้องมี evidence จาก Cloudflare build/deployment record และ read-only live route smoke. ตอนนี้ Worker name คือ `home`; หาก Workers Builds configuration ไม่พบ ให้ตรวจ source of truth ก่อนเลือก Workers Builds หรือ GitHub Actions เพียงทางเดียว. อย่าสร้าง trigger, เปลี่ยน binding, เพิ่ม secret หรือ deploy production จากการคาดเดา.

## Review checklist

Reviewer ต้องตรวจ diff source และ generated output, comment freshness, i18n completeness, capability/privacy claims, file limits, keyboard/focus behavior, cleanup, tests และ deployment status. ถ้า test ผ่านแต่ production route ยัง 1101 ให้ระบุเป็น deployment blocker ไม่ใช่ปิดบังด้วยการแก้ข้อความใน UI.