---

name: coding-standards description: บังคับใช้มาตรฐานการเขียนโค้ดของโปรเจกต์นี้ ทุกฟังก์ชัน (PHP และ JavaScript) ต้องมี Docstring ครบถ้วน (Description / Args / Returns) และห้ามเขียน inline script ใน HTML ทุกกรณี Trigger เมื่อผู้ใช้ขอเขียนฟังก์ชัน, เพิ่มโค้ด, review โค้ด หรือถามเรื่อง coding style ของโปรเจกต์นี้

Coding Standards

กฎบังคับ 3 ข้อ

1. ทุกฟังก์ชันต้องมี Docstring ครบ 3 ส่วน: Description · Args · Returns
2. ห้ามเขียน inline script ใน HTML โดยเด็ดขาด
3. หากมีการอัปเดตฐานข้อมูล ที่เกี่ยวข้อง ต้องอัปเดตไฟล์ sql/update.sql ด้วย

---

1. Docstring Standard

PHP — PHPDoc

ทุก function และ method ต้องมี PHPDoc block เหนือ declaration เสมอ

/**
 * [Description] อธิบายหน้าที่ของฟังก์ชันนี้ในหนึ่งบรรทัดหรือมากกว่า
 * ถ้ามีพฤติกรรมพิเศษหรือ side effect ให้อธิบายต่อในบรรทัดถัดไป
 *
 * @param  type  $paramName  คำอธิบาย parameter นี้
 * @param  type  $paramName2 คำอธิบาย parameter นี้
 *
 * @return type  คำอธิบายค่าที่คืนกลับ; ถ้าไม่คืนค่าให้ระบุ void
 */
function myFunction(type $paramName, type $paramName2): type
{
    // ...
}

ตัวอย่างที่ถูกต้อง:

/**
 * ดึงรายการชิ้นส่วนอะไหล่ที่เหลืออยู่ทั้งหมดสำหรับเครื่องจักรที่กำหนด
 * เรียงตามจำนวนคงเหลือจากน้อยไปมาก
 *
 * @param  int     $machineId  รหัสเครื่องจักรที่ต้องการ
 * @param  int     $limit      จำนวนแถวสูงสุดที่ต้องการ (default 50)
 *
 * @return array   array ของ associative array แต่ละแถวมีคีย์ part_id, part_name, qty
 */
function getSparePartsByMachine(int $machineId, int $limit = 50): array
{
    // ...
}

ตัวอย่างที่ผิด (ห้ามทำ):

// ❌ ไม่มี docstring เลย
function getSparePartsByMachine(int $machineId): array
{
    // ...
}

// ❌ มีแค่ชื่อ ไม่มี @param / @return
/**
 * get spare parts
 */
function getSparePartsByMachine(int $machineId): array
{
    // ...
}

---

JavaScript — JSDoc

ทุก function declaration, function expression, และ arrow function ที่ export หรือใช้งานข้ามไฟล์ต้องมี JSDoc block

/**
 * [Description] อธิบายหน้าที่ของฟังก์ชันนี้
 *
 * @param  {type}  paramName   คำอธิบาย parameter
 * @param  {type}  paramName2  คำอธิบาย parameter
 *
 * @returns {type}  คำอธิบายค่าที่คืนกลับ; ถ้าไม่คืนค่าให้ระบุ {void}
 */
function myFunction(paramName, paramName2) {
    // ...
}

ตัวอย่างที่ถูกต้อง:

/**
 * คำนวณ OEE (Overall Equipment Effectiveness) จากข้อมูล KPI ที่รับเข้ามา
 * ผลลัพธ์จะอยู่ในช่วง 0–100 (หน่วยเป็น %)
 *
 * @param  {number}  availability   อัตราความพร้อมใช้งาน (0–1)
 * @param  {number}  performance    อัตราประสิทธิภาพการผลิต (0–1)
 * @param  {number}  quality        อัตราคุณภาพ (0–1)
 *
 * @returns {number}  ค่า OEE เป็น % ปัดทศนิยม 2 ตำแหน่ง
 */
function calculateOEE(availability, performance, quality) {
    return parseFloat((availability * performance * quality * 100).toFixed(2));
}

---

2. No Inline Script

กฎ

• ห้าม <script> tag ภายใน .php / .html file ที่มีเนื้อหา JavaScript โดยตรง
• JavaScript ทั้งหมดต้องอยู่ใน ไฟล์ .js แยกต่างหาก ใต้ assets/js/
• ยกเว้นกรณีที่จำเป็นต้อง inject ตัวแปร config จาก PHP ลง JS (เช่น const BASE_URL = "<?= $url ?>";) — แต่ต้องจำกัดไว้แค่ const declarations เท่านั้น ห้ามมีตรรกะหรือฟังก์ชันใดๆ ใน inline script
• โหลดด้วย <script src="..."> เท่านั้น

ผิด — ห้ามทำ

<!-- ❌ inline script ใน PHP file -->
<button id="btnSave">Save</button>
<script>
    document.getElementById('btnSave').addEventListener('click', function () {
        fetch('/api/save_repair.php', { method: 'POST' });
    });
</script>

ถูก — วิธีที่ถูกต้อง

<!-- ✅ โหลด JS จากไฟล์แยก -->
<button id="btnSave">Save</button>
<script src="../assets/js/repair_form.js"></script>

// assets/js/repair_form.js

/**
 * ผูก event listener ให้ปุ่ม Save บนฟอร์มซ่อมบำรุง
 * เรียกใช้ครั้งเดียวเมื่อ DOM พร้อม
 *
 * @param  {string}  apiUrl  URL ของ endpoint ที่จะ POST ข้อมูลไป
 *
 * @returns {void}
 */
function initSaveButton(apiUrl) {
    document.getElementById('btnSave').addEventListener('click', function () {
        fetch(apiUrl, { method: 'POST' });
    });
}

ข้อยกเว้นที่อนุญาต

| สิ่งที่อนุญาต | เหตุผล | |---|---| | <script src="..."> | โหลดไฟล์ภายนอก ไม่ใช่ inline | | ตัวแปร config ที่ PHP inject ลงไป เช่น <script>const BASE_URL = "<?= $url ?>";</script> | ข้อมูล server-side ที่จำเป็นต้อง inject ณ runtime — ต้องจำกัดไว้แค่ const declarations เท่านั้น ห้ามมีตรรกะ |

---

3. UI Conventions — ช่องกรอกตัวเลข (number input)

กฎ

• <input type="number"> ทุกช่อง ให้ตั้ง step="1" (จำนวนเต็ม) เป็นค่าเริ่มต้น ทั้งจำนวนอะไหล่, ชั่วโมงงาน, ดาวน์ไทม์, เลขมิเตอร์ ฯลฯ ห้ามใช้ step="any" / step="0.001" / step="0.25" เว้นแต่มีเหตุผลชัดเจนและระบุกำกับไว้
• การ แสดงผล จำนวน ให้ตัด trailing zero ทิ้ง (เช่น 2.000 → 2, 2.50 → 2.5)
  • JS: ใช้ helper fmt() (toLocaleString แบบ maximumFractionDigits:3 ไม่มี min)
  • SQL: TRIM(TRAILING '.' FROM TRIM(TRAILING '0' FROM <col>))

ผิด — ห้ามทำ

<input type="number" id="qty" step="0.001">
<input type="number" id="hours" step="0.25">

ถูก

<input type="number" id="qty" min="1" step="1">
<input type="number" id="hours" min="0" step="1">

---

Checklist ก่อน commit

ตรวจข้อต่อไปนี้ทุกครั้งก่อนส่งโค้ด:

• [ ] ทุก function/method มี docstring ครบ 3 ส่วน (Description, Args, Returns)
• [ ] ไม่มี <script> block ที่มี JS logic อยู่ใน HTML/PHP file
• [ ] JS ใหม่ทุกชิ้นอยู่ใน assets/js/*.js
• [ ] ชื่อ parameter ใน docstring ตรงกับชื่อจริงใน signature
• [ ] <input type="number"> ใช้ step="1" (จำนวนเต็ม) และการแสดงผลตัด .000 ทิ้ง

---

ทำเมื่อ review โค้ดที่ไม่ผ่านมาตรฐาน

1. ระบุทุก function ที่ขาด docstring พร้อม file:line
2. ระบุทุก inline script พร้อม file:line
3. เขียน docstring และ/หรือแยก JS ออกมาให้ครบ ก่อน proceed งานอื่น