# 📚 Coding Standards — GOFLOW Enterprise AI OS Portal

**Coding Standards Document**
เวอร์ชัน 1.0 · Confidential – GOFLOW Enterprise · อัปเดตล่าสุด: 2026-08-07
บังคับใช้กับทุกทีมและทุกภาษาใน Monorepo

---

## 1. หลักการพื้นฐาน

1. **Readability > Cleverness** — เขียนให้คนอ่านเข้าใจก่อน อย่าเขียนให้ฉลาดเกินจำเป็น
2. **Consistency** — ทำแบบเดียวกันทั้งโปรเจกต์ (รูปแบบเดิมที่ตั้งไว้ ชนะความคิดเห็นส่วนตัว)
3. **Simplicity** — ใช้วิธีที่ง่ายที่สุดที่ยังคงคุณภาพ — YAGNI, KISS
4. **Security by Default** — คิดเรื่องความปลอดภัยตั้งแต่แรก ไม่ใช่ทีหลัง
5. **Documented** — โค้ดที่ไม่มีเอกสาร = งานยังไม่เสร็จ

---

## 2. ภาษาและเครื่องมือ

| ด้าน | มาตรฐาน |
|---|---|
| ภาษาหลัก | TypeScript (strict mode) — ทั้ง web และ api |
| Linter | ESLint (config ร่วมใน `packages/config`) |
| Formatter | Prettier (ไม่ใช้ tab กับ space ปนกัน — 2 spaces) |
| Package manager | pnpm (Monorepo) |
| ตรวจชนิด | `tsc --noEmit` ผ่านก่อน commit ทุกครั้ง |
| Python (AI) | Ruff + mypy สำหรับ AI services |

**คำสั่งที่ต้องผ่านก่อน push:**
```bash
pnpm lint
pnpm typecheck
pnpm test
pnpm build
```

---

## 3. โครงสร้างโค้ด (Code Structure)

- **Monorepo:** โค้ดแชร์อยู่ใน `packages/` — ห้าม copy-paste ข้ามแอป
- **Components:** ฟังก์ชันเดียวทำงานเดียว (single responsibility)
- **ไฟล์:** 1 ไฟล์ ≤ ~200 บรรทัด (เกิน → แยก) · ฟังก์ชัน ≤ ~40 บรรทัด
- **Naming:**
  - Component: `PascalCase` (`DashboardCard.tsx`)
  - ฟังก์ชัน/ตัวแปร: `camelCase` (`getUserById`)
  - ค่าคงที่: `UPPER_SNAKE_CASE` (`MAX_RETRY`)
  - ประเภท/Interface: `PascalCase` + คำนำหน้า `I`? → **ไม่ใช้** (ตาม TS convention)
  - ไฟล์ API route: kebab-case path ตาม endpoint

---

## 4. TypeScript Guidelines

```ts
// ✅ ดี: explicit + ไม่ใช้ any
interface User {
  id: string;
  email: string;
  role: "admin" | "developer" | "customer";
}

function formatName(user: Pick<User, "email">): string { … }

// ❌ ไม่ดี: any, non-null assertion เกินจำเป็น
// function foo(data: any) { return data.name!; }
```

- ห้าม `any` (ยกเว้นมีเหตุผล + comment + ได้รับอนุมัติใน review)
- เปิด `strict: true` เสมอ
- ใช้ `satisfies` สำหรับ object ที่ต้องตรงกับ type
- Zod (หรือ ajv) สำหรับ runtime validation — type อย่าไว้ใจ input จากภายนอก
- การจัดการ error: ใช้ Result/error class ที่ทีมกำหนด ไม่ใช่ throw กระจาย

---

## 5. Git Workflow

### Branch Model (Git Flow แบบเบา)

| Branch | ใช้กับ |
|---|---|
| `main` | พร้อม release เสมอ — ห้าม push ตรง |
| `develop` | รวมงานระหว่าง sprint (optional ถ้าทีมเล็ก) |
| `feature/<id>-<slug>` | งานใหม่ เช่น `feature/S2-04-ai-chat-widget` |
| `fix/<id>-<slug>` | แก้บั๊ก |
| `release/vX.Y.Z` | เตรียม release |

### Conventional Commits

```
feat(web): add AI chat widget        ← ฟีเจอร์ใหม่
fix(api): return 400 on invalid id   ← แก้บั๊ก
docs(readme): update setup steps     ← เอกสาร
refactor(api): extract auth plugin   ← ปรับโครงสร้าง (ไม่เปลี่ยนพฤติกรรม)
test(qa): add booking e2e            ← เพิ่ม test
chore(deps): bump next to 16.2       ← งานสนับสนุน
```

- PR title ใช้ format เดียวกับ commit
- ทุก PR อ้าง Issue (`Closes #42`)
- **Tag ทุก release:** `web-v1.0.0`, `api-v1.0.0`, `aios-v1.0.0` (ตามรูปแบบ GOFLOW เดิม `module-vX.Y`)

---

## 6. Code Review Rules

### ผู้ Review ตรวจ:
- ถูกต้องตาม Acceptance Criteria
- มี test ครอบคลุมกรณีหลัก + edge case
- ไม่มี security issue (injection, secrets, auth bypass)
- Performance สมเหตุสมผล (N+1 query, bundle size)
- ตาม Design System และมาตรฐานนี้

### กติกา:
- Merge ได้เมื่อ: **AI Review ผ่าน + Human Review ≥ 1 + CI เขียว**
- ระบบสำคัญ (payment, auth, AI core): ต้องการ Human Review ≥ 2 หรือ Lead
- Review ต้องเสร็จภายใน 24 ชม. ทำการ
- Comment ควรเป็นคำถาม/ข้อเสนอ ไม่ใช่คำสั่งกดดัน

---

## 7. Testing Standards

- ฟีเจอร์ใหม่ต้องมี test กำกับ — ไม่มี test = ยังไม่ Done
- Unit: ทดสอบ logic ล้วน (mock ภายนอก)
- Integration: ทดสอบกับ DB จริง (Testcontainers)
- E2E: เส้นทางผู้ใช้หลักเท่านั้น (จอง Demo, สมัครงาน, AI chat)
- Coverage เป้า: ≥ 80% โมดูลสำคัญ ≥ 90%
- ห้าม `test.skip` หรือ `it.only` หลงเหลือใน main

---

## 8. Security Coding Rules

| ข้อ | กฎ |
|---|---|
| Secrets | ห้าม hardcode — ใช้ env + Secret Manager เสมอ |
| SQL | ใช้ Prisma/parameterized query เท่านั้น (ห้าม string concat) |
| XSS | React ปลอดภัยโดยค่าเริ่มต้น — ห้าม `dangerouslySetInnerHTML` โดยไม่จำเป็น |
| Auth | ตรวจ token + RBAC ทุก endpoint ที่มีข้อมูลส่วนบุคคล |
| Input | validate ทุก input (zod) — ฝั่ง server เป็นหลัก |
| Upload | ตรวจ type, size, scan ไวรัส; เก็บใน MinIO ไม่ใช่ public dir |
| Rate limit | ใช้กับทุก endpoint (AI chat เข้มสุด) |
| Logs | ห้าม log password/token/ข้อมูลส่วนตัว |

---

## 9. Performance Budget

| รายการ | งบ |
|---|---|
| JS bundle เริ่มต้น (gzip) | ≤ 250 KB |
| ภาพ LCP | ≤ 200 KB (webp/avif) |
| API response (ไม่รวม AI) | p95 < 500ms |
| Lighthouse | ≥ 95 |
| CLS | < 0.1 |

**กฎ:** อย่าเพิ่ม dependency โดยไม่จำเป็น (ขออนุมัติใน review) · lazy-load ส่วนที่ไม่ได้ใช้ตอนแรก

---

## 10. Documentation Rules

- ทุกฟีเจอร์ใหม่: อัปเดตเอกสารที่เกี่ยวข้อง (API spec, README, docs/)
- โค้ดซับซ้อน: comment อธิบาย **why** (ไม่ใช่ what — โค้ดบอก what เอง)
- ทุก endpoint: อยู่ใน OpenAPI spec
- ทุกตารางใหม่: อัปเดต `05-database-schema.md`
- การตัดสินใจใหญ่: เขียน ADR (Architecture Decision Record) สั้น ๆ 1 หน้า

---

## 11. Definition of Done (ระดับงาน)

งานถือว่าเสร็จเมื่อ:

- [ ] โค้ดตามมาตรฐานนี้ (lint + typecheck ผ่าน)
- [ ] มี test ผ่านครบ (unit + integration/E2E ตามความเหมาะสม)
- [ ] ผ่าน AI Review + Human Review
- [ ] ไม่มี secrets ในโค้ด
- [ ] เอกสารอัปเดต
- [ ] Deploy staging + QA ยืนยัน
- [ ] อัปเดตสถานะใน Sprint Board

---

*เอกสารนี้เป็นส่วนหนึ่งของ GOFLOW Developer Kit — สอดคล้องกับ GOFLOW-AI-Code-Review-System.md และ GOFLOW-AI-Release-Process.md*