diff --git a/1789353182821.png b/1789353182821.png new file mode 100644 index 0000000..d0c3948 Binary files /dev/null and b/1789353182821.png differ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6da2596..e535049 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,213 +1,228 @@ -# 📋 CONTRIBUTING.md — Branch Protection & CI Workflow Guide - -> **Enforced by:** GitHub Branch Protection Rules + `github-coding` CI Pipeline -> **Last Updated:** 2026-09-08 · **Version:** 1.0 - ---- - -## 🛡️ Overview — Why These Rules Exist - -To maintain quality, security, and traceability, **direct pushes to protected branches are blocked by GitHub itself**. Every change must flow through: - -> **PR → CI Checks → Human Review → Merge Gate → Merge → Auto-Release** - -This ensures: -- ✅ Code is reviewed -- ✅ All tests pass -- ✅ Security scans are clean -- ✅ No one bypasses quality gates -- ✅ Clean, auditable history - ---- - -## 🔒 Protected Branches - -| Branch | Protection Level | Allowed Changes | -|---|---|---| -| `main` | 🔒 Strict — Production | Via PR only · 1+ approval · All CI green | -| `develop` | 🔒 Standard — Staging | Via PR only · 1+ approval · All CI green | -| `feature/*` / `fix/*` | ✅ Unrestricted | Create freely, open PR | - -> ❌ **Direct pushes to `main` or `develop` are rejected automatically.** - ---- - -## ✅ Full PR Requirements Checklist - -Before any PR can be merged, **ALL of these must pass**: - -### 🤖 Automated Checks (Must Pass) -- [ ] **🧠 github-coding Pre-Check** — Stack detect · Format · Lint · Test · Security scan · CodeQL -- [ ] **🧹 Standard Lint** — Code style & quality -- [ ] **🧪 Unit Tests** — Full test suite passes -- [ ] **🛡️ Merge Policy Enforcement** — Human approval given + no critical security labels -- [ ] **Branch is up to date** with target branch - -### 👀 Human Requirements (Must Approve) -- [ ] **At least 1 approval** from a collaborator -- [ ] **Code Owner approval** (if changing critical config/docs) -- [ ] **No changes requested** or previous approval dismissed & re-approved -- [ ] **No `critical` / `security` labels** blocking merge - -### 📝 PR Quality Standards -- [ ] Follows Conventional Commits title: `feat:`, `fix:`, `docs:`, etc. -- [ ] Description clearly explains changes -- [ ] Linked to issue: `Closes #123` -- [ ] Draft PR marked **Ready for Review** - ---- - -## 🔄 Complete Development Flow - -``` -1. Create Branch - └─ feature/short-description - -2. Open Pull Request - ├─ Auto-title: "feat: describe change" - ├─ Auto-description generated by github-coding - └─ Mark draft until ready - -3. 🤖 Automated Checks Run - ├─ 🧠 Pre-Check → Format, Lint, Test, Scan - ├─ 🧹 Standard Lint - ├─ 🧪 Unit Tests - └─ 🛡️ Merge Gate → Waiting for approval - -4. 👀 Human Review - ├─ Request changes → Fix ↺ - └─ ✅ Approved → Merge Gate Passes - -5. ✅ Merge Enabled - ├─ All checks green ✅ - ├─ Approved ✅ - └─ Up to date ✅ - -6. 🚀 Merge → Auto-Release - ├─ Branch deleted automatically - ├─ Version bumped (patch) - ├─ Changelog updated - └─ Release created -``` - ---- - -## ⛔ Common Merge Blockers & Fixes - -| Blocked By | Cause | Fix | -|---|---|---| -| **CI failing** | Lint error / test fails / scan finds issues | Fix locally, push — re-runs | -| **Awaiting review** | No approval yet | Request review; wait for approval | -| **Stale approval** | New code pushed after approval | Re-approve automatically or request re-review | -| **Out of date** | Target branch has new commits | Update branch: `git pull main && git rebase main` | -| **Security label** | Label: `critical` / `security` | Resolve issue → remove label | -| **Code owner review** | Changed critical files | Request review from Code Owner | - ---- - -## 🧠 github-coding Pre-Check — What It Does - -Your PR automatically runs this full quality pipeline: - -``` -🔍 Detect Stack → Python/Node/Docker? +📋 CONTRIBUTING.md — ปรับปรุงให้สอดคล้องสาขา  Origin  + +บังคับใช้โดย: GitHub Branch Protection Rules +  github-coding  CI Pipeline +อัปเดตล่าสุด: 14 กันยายน 2026 · เวอร์ชัน: 1.1 +โปรเจกต์: ZyntroAI/fastapi-python-boilerplate · สาขาหลัก:  Origin  + +  + +🛡️ ภาพรวม — เหตุผลที่ต้องมีกฎเหล่านี้ + +เพื่อรักษาคุณภาพ, ความปลอดภัย และสามารถตรวจสอบย้อนกลับได้ GitHub บล็อกการพุชตรงไปยังสาขาที่ได้รับการปกป้อง ทุกการเปลี่ยนแปลงต้องผ่านขั้นตอน: + +PR → ตรวจสอบ CI → รีวิวโดยบุคคล → ประตูควบรวม → ผสาน → เผยแพร่อัตโนมัติ + +รับประกันได้ว่า: + +- ✅ โค้ดได้รับการตรวจสอบ +- ✅ การทดสอบทั้งหมดผ่าน +- ✅ การสแกนความปลอดภัยไม่พบปัญหา +- ✅ ไม่มีใครข้ามขั้นตอนคุณภาพ +- ✅ ประวัติสะอาด ตรวจสอบได้ + +  + +🔒 สาขาที่ได้รับการปกป้อง + +สาขา ระดับการปกป้อง การเปลี่ยนแปลงที่อนุญาต + Origin  🔒 เข้มงวด — สถานะหลัก/ผลิตภัณฑ์ ผ่าน PR เท่านั้น · ต้องมีการอนุมัติ 1 ครั้ง · CI ทั้งหมดต้องผ่าน + develop  🔒 มาตรฐาน — สภาพแวดล้อมทดสอบ ผ่าน PR เท่านั้น · ต้องมีการอนุมัติ 1 ครั้ง · CI ทั้งหมดต้องผ่าน + feature/*  /  fix/*  ✅ ไม่จำกัด สร้างได้อย่างอิสระ เปิด PR ได้ + +❌ การพุชตรงไปยัง  Origin  หรือ  develop  จะถูกปฏิเสธโดยอัตโนมัติ + +  + +✅ รายการตรวจสอบ PR ที่สมบูรณ์ + +ก่อนที่ PR จะสามารถผสานได้ ต้องผ่านทุกข้อต่อไปนี้: + +🤖 การตรวจสอบอัตโนมัติ (ต้องผ่านทั้งหมด) + +🧠 github-coding Pre-Check — ตรวจสอบสแต็ก · จัดรูปแบบ · Lint · ทดสอบ · สแกนความปลอดภัย · CodeQL +🧹 การตรวจสอบรูปแบบโค้ด — รูปแบบและคุณภาพโค้ด +🧪 การทดสอบหน่วย — ชุดทดสอบทั้งหมดผ่าน +🛡️ การบังคับใช้นโยบายผสาน — มีการอนุมัติจากบุคคล + ไม่มีป้ายความปลอดภัยที่สำคัญ +สาขาเป็นปัจจุบัน ตรงกับสาขาเป้าหมาย ( Origin ) + +👀 ข้อกำหนดจากบุคคล (ต้องได้รับการอนุมัติ) + +ต้องมีการอนุมัติอย่างน้อย 1 ครั้ง จากผู้ร่วมพัฒนา +การอนุมัติจากเจ้าของโค้ด (หากแก้ไขคอนฟิก/เอกสารสำคัญ) +ไม่มีคำขอเปลี่ยนแปลง หรือการอนุมัติเดิมถูกยกเลิกและอนุมัติใหม่ +ไม่มีป้าย  critical  /  security  ที่บล็อกการผสาน + +📝 มาตรฐานคุณภาพ PR + +ปฏิบัติตามชื่อแบบ Conventional Commits:  feat: ,  fix: ,  docs: ,  refactor: ,  chore:  ฯลฯ +คำอธิบายชัดเจน อธิบายการเปลี่ยนแปลง +เชื่อมโยงกับปัญหา:  Closes #123  +หากเป็น PR ร่าง ต้องทำเครื่องหมาย พร้อมรีวิว + +  + +🔄 ขั้นตอนการพัฒนาที่สมบูรณ์ + +plaintext + +1. สร้างสาขา + └─ feature/คำอธิบายสั้นๆ + ✅ เริ่มจากสาขา: Origin + +2. เปิดคำขอดึง (PR) + ├─ ชื่ออัตโนมัติ: "feat: อธิบายการเปลี่ยนแปลง" + ├─ คำอธิบายอัตโนมัติจาก github-coding + └─ ทำเครื่องหมายร่างจนกว่าจะพร้อม + +3. 🤖 ทำงานตรวจสอบอัตโนมัติ + ├─ 🧠 Pre-Check → จัดรูปแบบ, Lint, ทดสอบ, สแกน + ├─ 🧹 ตรวจสอบรูปแบบ + ├─ 🧪 การทดสอบหน่วย + └─ 🛡️ ประตูผสาน → รอการอนุมัติ + +4. 👀 การตรวจสอบโดยบุคคล + ├─ ขอแก้ไข → แก้ไข ↺ + └─ ✅ ได้รับการอนุมัติ → ประตูผสานผ่าน + +5. ✅ เปิดใช้งานการผสาน + ├─ การตรวจสอบทั้งหมดผ่าน ✅ + ├─ ได้รับการอนุมัติ ✅ + ├─ สาขาเป็นปัจจุบันกับ Origin ✅ + └─ ไม่มีความขัดแย้ง + +6. 🚀 ผสาน → เผยแพร่อัตโนมัติ + ├─ สาขาต้นทางถูกลบโดยอัตโนมัติ + ├─ เวอร์ชันเพิ่มขึ้น (patch) + ├─ อัปเดตบันทึกการเปลี่ยนแปลง + └─ สร้างรีลีสใหม่ +  + +  + +⛔ สาเหตุที่ผสานไม่ได้ & วิธีแก้ไข + +สาเหตุที่ถูกบล็อก สาเหตุที่เป็นไปได้ วิธีแก้ไข +CI ไม่ผ่าน ข้อผิดพลาดรูปแบบ / ทดสอบล้ม / สแกนเจอปัญหา แก้ไขในเครื่อง, พุช — ระบบจะรันใหม่ +รอการตรวจสอบ ยังไม่มีการอนุมัติ ขอตรวจสอบ; รอการอนุมัติ +การอนุมัติล้าสมัย มีการพุชโค้ดเพิ่มหลังจากอนุมัติ อนุมัติอัตโนมัติหรือขอตรวจสอบใหม่ +สาขาไม่เป็นปัจจุบัน สาขาเป้าหมาย  Origin  มีคอมมิตใหม่ อัปเดตสาขา:  git pull Origin && git rebase Origin  +ป้ายความปลอดภัย มีป้าย:  critical  /  security  แก้ไขปัญหา → ลบป้ายออก +ต้องตรวจสอบจากเจ้าของโค้ด แก้ไขไฟล์สำคัญ ขอตรวจสอบจากเจ้าของโค้ด + +  + +🧠 github-coding Pre-Check — ทำงานอย่างไร + +PR จะรันชุดตรวจสอบคุณภาพทั้งหมดโดยอัตโนมัติ: + +plaintext + +🔍 ตรวจจับสแต็ก → Python/Node/Docker? ↓ -✅ Format Code → Auto-fix style +✅ จัดรูปแบบโค้ด → แก้ไขรูปแบบอัตโนมัติ ↓ -✅ Lint Code → Quality check +✅ ตรวจสอบรูปแบบ → ตรวจสอบคุณภาพ ↓ -🧪 Run Tests → Verify nothing broke +🧪 รันการทดสอบ → ตรวจสอบว่าไม่มีอะไรเสียหาย ↓ -🔒 Secrets Scan → No credentials committed +🔒 สแกนข้อมูลลับ → ไม่มีข้อมูลรับรองถูกคอมมิต ↓ -🔒 CodeQL Scan → Security analysis +🔒 สแกน CodeQL → วิเคราะห์ความปลอดภัย ↓ -📝 Update PR → Auto-description +📝 อัปเดต PR → คำอธิบายสร้างเอง ↓ -✅ Ready for Review -``` - -> 💡 **Formatting fixes are committed automatically.** Check your PR after opening — github-coding may have already corrected formatting! - ---- - -## 📌 Branch Naming Convention - -``` -feature/description → New feature -fix/issue-number → Bug fix -refactor/what-changed → Code improvement -docs/what-updated → Documentation -chore/description → Maintenance, CI, config -release/vX.Y.Z → Release preparation -``` - ---- - -## 🤝 How to Get Your PR Merged Faster - -1. **Keep PRs small** — under 500 lines → faster review -2. **Draft PR = work in progress** — mark ready when CI passes -3. **Clear title & description** — follow Conventional Commits -4. **Link issue** — `Closes #123` -5. **Wait for CI green** before requesting review -6. **Address comments** — push fixes; re-request review -7. **Merge button appears** → All requirements met ✅ - ---- - -## ⚙️ Settings Reference - -> **Admin only:** `Settings → Branches → Branch protection rules` - -``` -Rule: main - ✅ Require PR before merging - ✅ 1 Approval required - ✅ Dismiss stale approvals - ✅ Require Code Owner review - ✅ Require status checks: +✅ พร้อมรีวิว +  + +💡 การแก้ไขรูปแบบจะถูกคอมมิตอัตโนมัติ ตรวจสอบ PR ของคุณหลังจากเปิด — github-coding อาจแก้ไขรูปแบบให้แล้ว! + +  + +📌 รูปแบบการตั้งชื่อสาขา + +plaintext + +feature/คำอธิบาย → ฟีเจอร์ใหม่ +fix/หมายเลขปัญหา → แก้ไขข้อผิดพลาด +refactor/สิ่งที่เปลี่ยน → ปรับปรุงโค้ด +docs/สิ่งที่อัปเดต → อัปเดตเอกสาร +chore/คำอธิบาย → บำรุงรักษา, CI, คอนฟิก +release/vX.Y.Z → เตรียมรีลีส +  + +  + +🤝 วิธีทำให้ PR ผสานได้เร็วขึ้น + +1. รักษา PR ให้เล็ก — ไม่เกิน 500 บรรทัด → ตรวจสอบเร็วขึ้น +2. PR ร่าง = กำลังทำ — ทำเครื่องหมายพร้อมเมื่อ CI ผ่าน +3. ชื่อและคำอธิบายชัดเจน — ปฏิบัติตาม Conventional Commits +4. เชื่อมโยงปัญหา —  Closes #123  +5. รอ CI ผ่าน✅ ก่อนขอตรวจสอบ +6. ตอบรับความคิดเห็น — พุชแก้ไข; ขอตรวจสอบใหม่ +7. ปุ่มผสานปรากฏขึ้น → เมื่อตรงตามทุกข้อกำหนด ✅ + +  + +⚙️ การตั้งค่าอ้างอิง (สำหรับผู้ดูแลระบบ) + +ผู้ดูแลระบบเท่านั้น:  Settings → Branches → Branch protection rules  + +plaintext + +Rule: Origin + ✅ ต้องการ PR ก่อนผสาน + ✅ ต้องการการอนุมัติ 1 ครั้ง + ✅ ยกเลิกการอนุมัติที่ล้าสมัย + ✅ ต้องการตรวจสอบจากเจ้าของโค้ด + ✅ ต้องการตรวจสอบสถานะ: github-coding-precheck ✅ lint ✅ test ✅ merge-gate ✅ - ✅ Require branches up to date - ✅ Block force pushes - ✅ Delete head branches on merge - ❌ Allow admin bypass → OFF + ✅ ต้องการให้สาขาเป็นปัจจุบัน + ✅ บล็อกการพุชแบบ Force + ✅ ลบสาขาต้นทางเมื่อผสาน + ❌ อนุญาตให้ผู้ดูแลระบบข้าม → ปิด Rule: develop - ✅ Same checks, same approval - ⚠️ Code Owner review optional -``` - ---- - -## ❓ FAQ - -**Q: Can someone bypass these rules?** -> No — rules apply to everyone, including admins. Only Dependabot can auto-merge minor/patch updates when CI passes and approved. - -**Q: What if I need to merge urgently?** -> Still requires 1 approval. Open PR → pass CI → request review → approve → merge. Takes ~5 minutes. - -**Q: Why is "Merge Gate" a required check?** -> It verifies a human has approved. This is our **destructive action gate** — automation suggests, human decides. - -**Q: Can I merge my own PR?** -> Yes — but you still need **1 approval** from someone else (or approve your own if you have sufficient permissions). - ---- - -> **These rules exist to protect production. Not to slow you down.** -> Every automated check catches issues before they become problems. -> Every human review shares knowledge. Every gate keeps us safe. - ---- - -✅ **Ready to paste!** Save this as: -``` + ✅ ตรวจสอบเหมือนกัน, การอนุมัติเหมือนกัน + ⚠️ การตรวจสอบเจ้าของโค้ดเป็นทางเลือก +  + +  + +❓ คำถามที่พบบ่อย + +Q: มีใครข้ามกฎเหล่านี้ได้ไหม? + +ไม่มี — กฎใช้กับทุกคน รวมถึงผู้ดูแลระบบ มีเพียง Dependabot ที่สามารถผสานอัตโนมัติสำหรับการอัปเดต minor/patch เมื่อ CI ผ่านและได้รับการอนุมัติ + +Q: หากต้องการผสานเร่งด่วนต้องทำอย่างไร? + +ยังคงต้องการการอนุมัติ 1 ครั้ง เปิด PR → ผ่าน CI → ขอตรวจสอบ → อนุมัติ → ผสาน ใช้เวลาประมาณ 5 นาที + +Q: ทำไม "ประตูผสาน" เป็นการตรวจสอบที่จำเป็น? + +เป็นตัวยืนยันว่ามีมนุษย์อนุมัติแล้ว นี่คือ ประตูป้องกันการกระทำที่มีผลกระทบสูง — ระบบอัตโนมัติเสนอแนะ แต่มนุษย์ตัดสินใจ + +Q: ผสาน PR ของตัวเองได้ไหม? + +ได้ — แต่ยังคงต้องการ การอนุมัติจากคนอื่น 1 ครั้ง (หรืออนุมัติเองหากมีสิทธิ์เพียงพอ) + +  + +กฎเหล่านี้มีไว้เพื่อปกป้องสาขา  Origin  และผลิตภัณฑ์ ไม่ใช่เพื่อทำให้ช้าลง +ทุกการตรวจสอบอัตโนมัติช่วยพบปัญหาก่อนลุกลาม +ทุกการตรวจสอบโดยบุคคลช่วยแบ่งปันความรู้ ทุกประตูช่วยรักษาความปลอดภัย 🛡️ + +  + +✅ บันทึกเป็นไฟล์: + +plaintext + CONTRIBUTING.md -``` - -Would you like me to also generate a **pull request template** that enforces this checklist directly in every PR description? 📋 \ No newline at end of file +  + +ต้องการให้ฉันสร้าง เทมเพลตคำขอดึง (PR Template) ที่รวมรายการตรวจสอบนี้ไว้ในทุก PR โดยตรงไหมครับ? 📋 diff --git a/Compare/Compare_14September2026(main-Origin) b/Compare/Compare_14September2026(main-Origin) new file mode 100644 index 0000000..a7596a0 --- /dev/null +++ b/Compare/Compare_14September2026(main-Origin) @@ -0,0 +1,271 @@ +📜 ตรวจสอบเชิงลึกจากประวัติคอมมิต: v1.1.0 → v1.2.0 + +รีโป: ZyntroAI/fastapi-python-boilerplate +ช่วงเวลา: 9 กันยายน 2026 – 11 กันยายน 2026 +จำนวนคอมมิต: 24 คอมมิตที่ตรวจสอบได้ • ไฟล์เปลี่ยน: 369 ไฟล์ • ผู้มีส่วนร่วม: 11 คน +ลายเซ็น: ทุกคอมมิตมี GPG Verified ✅ (คีย์ ID: B5690EEEBB952194) +สาขาเป้าหมาย:  Origin  (เปลี่ยนจาก  main  ในรุ่นก่อนหน้า) + +  + +🧭 ภาพรวมโครงสร้างประวัติคอมมิต + +ประวัติเป็นเส้นตรงที่สะอาด (squashed & structured) แบ่งเป็น 4 ช่วงงานหลัก: + +1. 9 ก.ย.: เพิ่มสแต็กบริการพื้นฐาน + สถาปัตยกรรมตัวแทน AI +2. 10 ก.ย.: ระบบจัดการงาน + ปรับปรุงโครงสร้างเวิร์กโฟลว์ + เอกสารปัญหา +3. 10–11 ก.ย.: พัฒนาโมดูลเต็มรูปแบบ (Backend/Full-Stack) +4. 11 ก.ย.: ปรับปรุง CI/CD + ความปลอดภัย + การแก้ไขช่องโหว่ + +รูปแบบข้อความคอมมิตปฏิบัติตาม Conventional Commits อย่างเคร่งครัด: + +-  feat:  ฟีเจอร์ใหม่ +-  docs:  เอกสาร +-  chore:  บำรุงรักษา/โครงสร้าง +-  fix:  การแก้ไข +-  refactor:  ปรับปรุงโค้ด + +  + +📅 วิเคราะห์รายคอมมิตโดยละเอียด + +🟦 9 กันยายน 2026 — รากฐานระบบ & สแต็กบริการ + +1.  deliverables: add onspace-ai, manus-client, firecrawl-fastapi stacks (#165)  + +- เนื้อหา: เพิ่ม 3 โมดูลหลัก: +-  onspace-ai : FastAPI พร้อมชั้นแคช/วงจร/สำรอง/โทเค็น — 31 การทดสอบ +-  manus-client : ไคลเอ็นต์ REST API v2 แบบ Async — 10 การทดสอบ +-  firecrawl-fastapi : ตัวรวบรวม/ตรวจสอบเว็บพร้อมใช้งาน — 6 การทดสอบ +- ความปลอดภัย: ไม่เพิ่มไฟล์เวิร์กโฟลว์ → ปลอดภัยต่อการพุช +- ลายเซ็น: fig-ai-agent[bot] • GPG Verified + +2.  docs: record PR #165 in CHANGELOG (#166)  + +- บันทึกการเผยแพร่สแต็กใหม่ +- รักษารูปแบบบันทึกการเปลี่ยนแปลงตามวันที่ + +3.  docs: add AI Gateway architecture review deliverable (#164)  + +- เพิ่มเอกสารสถาปัตยกรรมระดับองค์กร +- ครอบคลุมขอบเขต ความน่าเชื่อถือ และจุดผสาน + +4.  docs: record PR #164 in CHANGELOG (#167)  + +- อัปเดตบันทึกการเปลี่ยนแปลงให้ตรงกับสถาปัตยกรรม + +5.  Create Rules.md  + +- กฎการมีส่วนร่วมและการปกป้องสาขา +- กำหนด  Origin  เป็นสาขาหลัก + +6.  Create PATCH.md  + +- คู่มือการบำรุงรักษาและแพตช์ +- ขั้นตอนการอัปเกรดภายในรุ่น + +7.  feat(deliverables): pure-agent-dev reference implementation (#169)  + +- โครงสร้าง: ตัวแทน AI ไม่ขึ้นกับผู้ให้บริการบน FastAPI +- ชั้นสถาปัตยกรรม: +-  providers/base.py : สัญลักษณ์นามธรรมทุกคลาวด์ +-  providers/mock.py : จำลองสำหรับ CI ไม่ต้องข้อมูลลับ +-  providers/byteplus/ : อะแดปเตอร์คลาวด์จริง +-  agents/planner.py/executor.py : ตัววางแผน/ผู้ดำเนินการ +-  api/deps.py : การฉีดค่าคอนฟิก +- การตรวจสอบ: ทดสอบสถาปัตยกรรมป้องกันการขึ้นกับ SDK +- ทดสอบ: pytest 47 ผ่าน • ruff สะอาด • JSON Schema ถูกต้อง + +8.  docs(changelog): record PR #169 (#170)  + +- บันทึกตัวแทนอ้างอิงลงบันทึก + +9.  docs: update CHANGELOG.md and README.md (#171)  + +- แก้ไข: แทนที่บันทึกเกี่ยวกับ  fix/sha-pin-all-workflows  +- สถานะปัจจุบัน: เวิร์กโฟลว์ยังผสม SHA กับแท็กที่เปลี่ยนแปลงได้ +- สถานะรีโป: CI ล้มที่ "ติดตั้งงาน" ตามนโยบาย SHA-pin ขององค์กร + +10.  feat(tasks): add a folder-based task tracker (#173)  + +- ตรรกะ: โฟลเดอร์ = สถานะ ( new/inprogress/done ) +- รูปแบบ: Markdown + ส่วนหัวข้อมูลครบถ้วน +- เครื่องมือ:  tools/tasks.py  CLI (stdlib เท่านั้น) +- ทดสอบ: ตรวจสอบคีย์/รหัส/วันที่/สถานะที่ถูกต้อง + +11.  feat(tasks): add archive/ status to the task tracker (#175)  + +- เพิ่มสถานะสิ้นสุด:  archive/  (เลิกใช้/ซ้ำซ้อน) +- คำสั่งใหม่:  archive <เหตุผล>  +- ปรับปรุงการตรวจสอบและเทมเพลต + +12.  chore(workflows): auto-move non-workflow files out of .github/workflows (#168)  + +- ย้ายไฟล์เอกสาร/บันทึก 7 ชิ้น →  archive/workflows-junk/  +- โฟลเดอร์เวิร์กโฟลว์เหลือเฉพาะ YAML จริง +- ผล: ลดความยุ่งเหยิง • ป้องกันการทำงานผิดพลาด + +13.  Add pm-backend deliverable: FastAPI billing (#174)  + +- ระบบการเรียกเก็บเงิน + การทดสอบ Sandbox + +14.  docs: record PR #168, #174, #176 in changelog (#177)  + +15.  feat(deliverables): add agent-core, a runnable agent task backend (#178)  + +- แก้ไขจากร่าง: +-  Settings() : เปลี่ยนเป็น Lazy + LRU cache +-  httpx.AsyncClient : ป้องกันการค้างของลูปเหตุการณ์ +-  retry : จับข้อผิดพลาดจริง • ไม่ลองซ้ำ 4xx +-  polling : เพิ่มการหมดเวลา +- ความปลอดภัย: ตรึง SHA ในตัวอย่าง CI +- ทดสอบ: 25 ผ่านทั้งหมดด้วย MockTransport + +16.  chore(tasks): add TASK-20260910-005 (#179)  + +- บันทึกข้อจำกัดของ  agent-core  (ยังไม่ทดสอบกับผู้ให้บริการจริง) +- แก้ไขข้อผิดพลาดเทมเพลต + +17.  docs: update CHANGELOG.md and README.md (#180)  + +18.  docs: add PROBLEMS.md as companion to CHANGELOG.md (#181)  + +- จุดประสงค์: บันทึกปัญหาที่ยังเปิด (ไม่ซ้ำกับบันทึกการเปลี่ยนแปลง) +- รายการ: +- P-001: เวิร์กโฟลว์ 5 ไฟล์แยกไม่ได้ +- P-002: 66 อ้างอิง Action ไม่ได้ตรึง SHA +- P-003: GitHub App ไม่มีสิทธิ์เขียน  .github/workflows/  +- P-004:  agent-core  ไม่ยืนยันกับผู้ให้บริการจริง +- P-005: สาขา  new-crystalcastle  บล็อกการพุช +- P-006: แก้ไขแล้ว (ข้อผิดพลาดเทมเพลต) + +19.  chore(tasks): close TASK-20260910-005 and correct records (#182)  + +- ปิดงาน • อัปเดตสรุปผล • แก้ไขการตั้งชื่อไฟล์ + +20.  docs: record PR #180 - #183 (#183)  + +- เพิ่ม P-007/P-008 • งานใหม่ TASK-20260910-006 +- ปัญหา P-007: เวิร์กโฟลว์ค้นหา  requirements.txt  ที่รูทซึ่งไม่มี + +21.  docs: record PR #183 in changelog (#184)  + +22.  feat: add fastapi-obsidian-backend deliverable (#185)  + +- คุณสมบัติ: +- API ทักษะพร้อมการเข้าถึงต่อผู้ใช้ (JWT) +- การสร้าง CSV • บันทึกการเรียกเก็บเงิน +- ตัวสลับเครื่องมือ • การเข้ารหัสที่เหลือเป็นทางเลือก +- ตัวอย่างไลบรารีภายใต้  data/skills/  + +23.  Update .gitignore  (2 ครั้ง) + +- เพิ่มกฎ:  node_modules/ ,  *.env ,  .env* ,  secrets/ ,  *.key ,  *.pem  + +24.  Update package.json  + +- เวอร์ชัน:  1.2.0  +- สคริปต์:  dev/build/lint/format/test  +- ขึ้นอยู่กับ:  react ,  typescript ,  vite ,  vitest  + +🟩 11 กันยายน 2026 — ฟูลสแต็ก & CI/CD & ความปลอดภัย + +1.  feat(deliverables): add product-crud full-stack CRUD (#187)  + +- แบ็กเอนด์: Express + Prisma + Zod (รูปแบบ/เส้นทาง) +- ฟรอนต์เอนด์: React + TanStack Query (แบ่งหน้า/ค้นหา/แคช) +- เครื่องมือ: Docker Compose • สคริปต์เมล็ดข้อมูล 30 รายการ +- ทดสอบ: tsc --noEmit สะอาด • vitest 30/30 ผ่าน + +2.  docs: record PR #187 and correct README (#192)  + +- อัปเดตตารางโครงสร้าง • สถานภาพรีโปที่ถูกต้อง +- สถานภาพ: รูทไม่มี  package-lock.json  • ESLint 10 ขัดข้อง + +3.  docs(github-api): add complete GitHub API reference (#193)  + +- คู่มือ REST v3 + GraphQL v4 ครบถ้วน +- การตรวจสอบสิทธิ์ • ขอบเขต • ตัวอย่างคำสั่ง • SDK • แนวทางองค์กร + +4.  docs: record PR #193 in CHANGELOG (#194)  + +5.  chore: switch root test runner to vitest (#191)  + +- แทนที่ Jest • เพิ่ม  vitest.config.mjs  +- ขอบเขต: ยกเว้นส่งมอบแยกต่างหาก • รวมเฉพาะรูท +-  .gitignore : เพิ่ม  coverage/ ,  .vercel/ ,  *.tsbuildinfo  + +6.  fix(product-crud): patch critical vitest advisory (#189)  + +- ช่องโหว่: CVE-2026-47429 (วิตเทส <3.2.6) +- อัปเกรด: 2.1.9 → 4.1.11 +- แก้ไข: ปัญหาเส้นทางข้ามใน @vitest/mocker +- Express: ล็อก  qs  → 6.16.0 ผ่าน  overrides  +- ผล: npm audit → 0 ช่องโหว่ + +7.  feat(product-crud): add production Docker image (#188)  + +- หลายขั้นตอน: การพึ่งพา → สร้าง → รัน +- รัน: node:22-alpine • ไม่ใช่รูท • tini • HEALTHCHECK +- จุดเข้า: ตรวจสอบการย้ายฐานข้อมูล Prisma + +  + +🛡️ การวิเคราะห์ความปลอดภัย & ความน่าเชื่อถือ + +✅ จุดแข็ง + +- ลายเซ็น: ทุกคอมมิตมีลายเซ็น GPG ที่ตรวจสอบได้ +- สาขา: เปลี่ยนเป็น  Origin  พร้อมกฎป้องกัน +- เอกสาร:  CONTRIBUTING.md  อัปเดต •  PROBLEMS.md  บันทึกปัญหา +- ทดสอบ: ส่วนใหญ่มีชุดทดสอบครบถ้วน • การตรวจสอบสถาปัตยกรรม +- การแก้ไขช่องโหว่: อัปเกรดวิตเทส/Express/qs ทันที + +⚠️ ปัญหาที่สืบทอด/เปิดอยู่ + +1. การตรึง SHA: 66 Action ยังไม่ได้ตรึง • ขัดนโยบายองค์กร +2. สิทธิ์: GitHub App ไม่มีสิทธิ์เขียน  .github/workflows/  → ป้องกันการแก้ไข +3. รูท: ไม่มี  package-lock.json  • ESLint 10 ไม่รองรับ •  npm run lint  ล้ม +4. CI: ล้มเนื่องจากขาดไฟล์  requirements.txt  • เวิร์กโฟลว์ไม่สอดคล้อง + +  + +📂 โครงสร้างโค้ดที่แท้จริงจากประวัติ + +plaintext + +ZyntroAI/fastapi-python-boilerplate/ +├─ deliverables/ # โมดูลอิสระทั้งหมด +│ ├─ onspace-ai/ +│ ├─ manus-client/ +│ ├─ firecrawl-fastapi/ +│ ├─ pure-agent-dev/ +│ ├─ agent-core/ +│ ├─ pm-backend/ +│ ├─ fastapi-obsidian-backend/ +│ └─ product-crud/ # Express+Prisma+React+Docker +├─ tools/ +│ └─ tasks.py # ตัวจัดการงาน CLI +├─ docs/ +│ ├─ CHANGELOG.md +│ ├─ PROBLEMS.md +│ ├─ CONTRIBUTING.md # สาขา: Origin +│ └─ github-api.md +├─ .github/ +│ ├─ workflows/ # เฉพาะ YAML จริง +│ └─ archive/workflows-junk/ # ย้ายออกแล้ว +├─ package.json # v1.2.0 +├─ .gitignore # ครอบคลุมข้อมูลลับ/แคช +└─ vitest.config.mjs +  + +  + +✅ สรุปการตรวจสอบประวัติคอมมิต + +- ความสมบูรณ์: ประวัติเป็นระเบียบ • สอดคล้องกับเปรียบเทียบ URL +- ความก้าวหน้า: v1.1.0 → v1.2.0 คือการยกเครื่องโครงสร้าง + เพิ่มฟูลสแต็ก +- ความปลอดภัย: แก้ไขช่องโหว่สำคัญ แต่ยังมีปัญหาเรื่องการตรึง SHA/สิทธิ์ +- พร้อมใช้: โมดูลส่วนใหญ่ทดสอบผ่าน • เอกสารครบถ้วน •  Origin  คือสาขาเสถียร + +ประวัติยืนยัน: รุ่น v1.2.0 เป็นรุ่นปัจจุบันบน  Origin  • ครบถ้วน • ตรวจสอบได้ • มีข้อจำกัดที่ทราบชัดเจน 📜✅🔒🟢 diff --git a/Documents_Figma b/Documents_Figma new file mode 100644 index 0000000..0c811bc --- /dev/null +++ b/Documents_Figma @@ -0,0 +1,96 @@ +ยินดีต้อนรับสู่หัวข้อ **Figma Design System & Accessibility** ครับ! ในบทเรียนนี้ เราจะเจาะลึกโครงสร้างการสร้าง Design System ที่ได้มาตรฐานระดับสากล การจัดการ Component Properties และขั้นตอนการทำ Accessibility Audit ตามมาตรฐาน **WCAG 2.2** เพื่อให้ UI Components ของคุณพร้อมสำหรับการ Handoff ให้ทีม Developer นำไปพัฒนาต่อได้อย่างสมบูรณ์แบบ [1, 2] + +--- + +### 1. สถาปัตยกรรม Design Tokens แบบ 3 ชั้น (3-Tier Token Architecture) + +ในการสร้าง Design System ที่สามารถขยายตัว (Scale) และรองรับการเปลี่ยนธีม (Theming / Dark Mode) ได้อย่างมีประสิทธิภาพ แหล่งข้อมูลแนะนำให้แบ่งโครงสร้าง **Figma Variables (Design Tokens)** ออกเป็น 3 ชั้นหลัก [3]: + +``` +[Brand Collection (Primitives)] + ↓ + [Alias Collection (Semantic)] + ↓ +[Mapped Collection (Components / UI)] +``` + +#### ชั้นที่ 1: Brand Collection (Primitives) +เก็บค่าสี ตัวเลข และแบบอักษรในรูปแบบดิบที่บริสุทธิ์ที่สุด (Purest Form) โดยยังไม่มีการกำหนดบทบาทหน้าที่ของค่านั้นๆ [4, 5]: +* **Color Scales:** กำหนดชื่อตามสเกลความเข้มแบบ 100 สเกล (เช่น `purple-100` ถึง `purple-800`, `red-100` ถึง `red-800`) [4] +* **Number Scale:** ใช้สเกลตัวเลขฐาน 4 (Multiples of 4) สำหรับระยะห่างและขนาด เช่น `25` (1px), `50` (2px), `100` (4px), `200` (8px), `300` (12px), `400` (16px) [6] +* **Typography:** เก็บชื่อ Font Family (เช่น `Inter`) และ Font Weight (`Regular`, `Medium`, `Semi-Bold`, `Bold`) [7-9] + +#### ชั้นที่ 2: Alias Collection (Semantic) +นำค่าจาก Brand Collection มามอบบทบาทหน้าที่ (Roles) เพื่อการนำไปใช้งานเชิงความหมาย [10]: +* **Color Roles:** กำหนดหน้าที่ เช่น `Primary`, `Error` (อ้างอิงจาก `red`), `Success` (อ้างอิงจาก `green`), `Neutral` (อ้างอิงจาก `gray`), `Warning`, `Information` [11-13] +* **Border & Radius:** กำหนดขนาดเส้นขอบและมุมโค้งแบบ Semantic เช่น `border-width/small` (1px), `border-radius/medium` (4px หรือ 8px) [14] +* **Multi-Brand & Theming:** หากมีหลายแบรนด์ (Branded House) สามารถเพิ่ม Mode ใน Alias Collection เพื่อสลับโทนสีหลักได้โดยไม่ต้องเปลี่ยนโครงสร้างส่วนอื่น [15, 16] + +#### ชั้นที่ 3: Mapped Collection (Scoped UI) +เป็นชั้นที่เชื่อมโยง Alias Tokens ไปสู่เลเยอร์ UI จริงที่ปรากฏบนหน้าจอ [17, 18]: +* **Text Variables:** `text/headings`, `text/body`, `text/action`, `text/disabled`, `text/on-action` [19-21] +* **Surface Variables:** `surface/page` (พื้นหลังหน้าเว็บ), `surface/default` (การ์ด), `surface/action` (ปุ่ม) [22, 23] +* **Border & Icon Variables:** `border/default`, `border/focus`, `icon/default`, `icon/action` [24-26] +* **Light / Dark Mode:** สร้าง Mode ซ้อนใน Mapped Collection โดยทำการสลับสลับค่าสี (Inverse) เช่น ใน Light Mode `surface/page` ใช้สีขาว แต่ใน Dark Mode สลับไปใช้ `neutral-800` [26, 27] + +--- + +### 2. การสร้าง UI Components และการกำหนด Component Properties + +เพื่อให้ Component ใน Figma มีความยืดหยุ่น ลดจำนวน Variant ที่ซ้ำซ้อน และใช้งานง่ายในฝั่ง Dev Mode Figma มีคุณสมบัติหลัก 5 ประเภท [28, 29]: + +| ประเภท Property [28] | สภาพการใช้งาน [28] | ตัวอย่างการประยุกต์ใช้ [30-33] | +| :--- | :--- | :--- | +| **Variant Property** [33] | กำหนดรูปแบบหลัก สถานะ หรือขนาดของ Component [33] | `Size` (Small/Large), `State` (Default/Hover/Disabled) [33] | +| **Boolean Property** [30] | เปิด/ปิดการมองเห็นของ Layer (True/False) [30, 34] | เปิด/ปิดไอคอนหน้าปุ่ม (`showIcon`) โดยไม่ต้องสร้าง Variant ใหม่ [30] | +| **Instance Swap Property** [31] | สลับสับเปลี่ยน Component ย่อยที่อยู่ข้างใน [31] | สลับไอคอนซ้าย/ขวาในปุ่ม พร้อมตั้งค่า **Preferred Instances** เพื่อจำกัดตัวเลือกไอคอนที่ถูกต้อง [31, 35] | +| **Text Property** [32] | แก้ไขข้อความใน Component จาก Inspector Panel [32, 36] | เปลี่ยนข้อความปุ่ม หรือ Label โดยไม่ต้องกด Double-click เจาะเข้าไปใน Layer [32] | +| **Slot Property** [37] | พื้นที่ว่างยืดหยุ่นสำหรับใส่ Content เพิ่มเติม [37] | ใช้ใน Modal หรือ Card เพื่อให้วาง Layout อิสระได้โดยไม่ต้อง Detach Component [37] | + +#### การ Expose Nested Instances +เมื่อมี Component ซ้อนกันหลายชั้น (เช่น Card มี Button และ Avatar อยู่ภายใน) เราสามารถตั้งค่า **Expose Nested Instances** ที่ Top-level Component เพื่อให้ Designer หรือ Developer เลือกแก้ไข Properties ของ Component ย่อยได้ทันทีที่แถบซ้ายมือโดยไม่ต้องกดคลิกลึกลงไปหลายชั้น [38, 39] + +--- + +### 3. ขั้นตอนการทำ Accessibility Audit (WCAG 2.2 AA Standard) + +การตรวจสอบการเข้าถึงตั้งแต่ขั้นตอนการออกแบบใน Figma ช่วยลดเวลาและค่าใช้จ่ายในการแก้ไขโค้ดของ Developer ได้มากกว่า 30% [1, 40] โดยมี 5 ขั้นตอนสำคัญดังนี้: + +#### ขั้นตอนที่ 1: แยกหน้า Audit Page (Dedicated Audit Page) +คัดลอกหน้า Design ไปไว้ในหน้าใหม่ชื่อ **`Accessibility Audit`** [41] พร้อมใส่ Header ระบุวันที่ ชื่อผู้อรวจสอบ ระดับ WCAG ที่เป้าหมาย (AA) และสถานะ Pass/Fail เพื่อป้องกันความสับสนและข้อผิดพลาดเมื่อทำ Branching Workflow [41] + +#### ขั้นตอนที่ 2: ตรวจสอบความต่างของสี (Contrast Ratios - WCAG SC 1.4.3) +ใช้ปลั๊กอินเช่น **Stark** หรือ **Able** ตรวจสอบค่าความต่างของสีพื้นหลังและข้อความ [42-44]: +* **Normal Text (< 18pt regular / < 14pt bold):** อัตราส่วนขั้นต่ำ **4.5:1** [44] +* **Large Text (≥ 18pt regular / ≥ 14pt bold):** อัตราส่วนขั้นต่ำ **3.0:1** [44] +* **UI Components & Graphical Objects:** อัตราส่วนขั้นต่ำ **3.0:1** [44] +* *หากจุดใดไม่ผ่าน:* ใส่ป้ายสติ๊กเกอร์เตือน `FAIL - 1.4.3` พร้อมระบุค่าที่วัดได้เพื่อปรับแก้ในระดับ Design Token [45] + +#### ขั้นตอนที่ 3: จำลองภาวะตาบอดสี (Colour Blindness Simulation - WCAG SC 1.4.1) +รัน Vision Simulator ทั้ง 8 สภาวะ (เช่น Deuteranopia, Protanopia) [44, 46] เพื่อตรวจสอบตามหลัก SC 1.4.1 ที่ **ห้ามใช้สีเพียงอย่างเดียวในการสื่อสารข้อมูล** [47] (เช่น สถานะ Error ต้องมีไอคอนหรือข้อความเตือนควบคู่กับสีแดงเสมอ) [47] + +#### ขั้นตอนที่ 4: ระบุลำดับการโฟกัสคีย์บอร์ด (Focus Order Annotation - WCAG SC 2.4.1) +ใช้สติ๊กเกอร์ตัวเลขจาก A11y Annotation Kit ปักลำดับการกดปุ่ม `Tab` บนหน้าจอ [42, 48]: +1. **ลำดับที่ 1:** ปักที่ **Skip to main content link** (เพื่อข้ามส่วน Header) [49] +2. **ลำดับถัดไป:** ปักเรียงตามลำดับการอ่านและการทำงานที่เป็นธรรมชาติ (Left-to-Right / Top-to-Bottom) สำหรับองค์ประกอบที่มีปฏิสัมพันธ์ได้ (Buttons, Inputs, Links) [48, 49] + +#### ขั้นตอนที่ 5: ตรวจสอบขนาดจุดสัมผัส (Touch Target Sizes - WCAG SC 2.5.8) +ปุ่มหรือองค์ประกอบที่กดได้บนหน้าจอมือถือ ต้องมีขนาดพื้นที่สัมผัสขั้นต่ำ **24 × 24px** (และแนะนำมาตรฐาน **44 × 44px** ตาม Apple HIG / Android Material) [50] +* *เทคนิค:* สร้าง Component ชื่อ `Touch Target Wrapper` ที่เป็นกล่องใสขนาด 44 × 44px ครอบไอคอนขนาดเล็กไว้ เพื่อให้พื้นที่กดได้มาตรฐานโดยไม่เสียดีไซน์ [51] + +--- + +### 4. การแปลงดีไซน์เป็นโค้ดและการ Handoff ให้ Developer + +เมื่อตั้งค่า Design Tokens และทำ Accessibility Audit เรียบร้อยแล้ว การแปลผลดีไซน์เป็นโค้ด (เช่น React + Tailwind) สามารถทำได้อย่างราบรื่น [52]: +1. **Token Mapping:** นำค่าใน Figma Mapped Collection ไปผูกกับ CSS Variables หรือ Tailwind Config (เช่น `bg-primary`, `text-body`) เพื่อหลีกเลี่ยงการใช้ Hardcoded Hex Codes [52, 53] +2. **Dev Mode Component Playground:** Developer สามารถเปิด Dev Mode เพื่อทดลองเปลี่ยน Properties ของ Component ดูสเปกการเว้นระยะ (Spacing) และคัดลอกโค้ดโครงสร้างไปใช้งานได้ทันที [29] +3. **Semantic Mapping:** ใช้ข้อความกำกับ Alt Text และ ARIA Roles บนรูปภาพและปุ่มกดเพื่อให้นักพัฒนาเขียน HTML ที่ถูกต้องตามหลักโครงสร้าง Semantic [40, 54] + +--- + +💡 **คำแนะนำถัดไป:** หากคุณต้องการทดลองฝึกปฏิบัติต่อ เราสามารถเลือกทำสิ่งเหล่านี้ได้ครับ: +1. ดูตัวอย่างการสร้าง **Component `Button` และ `Input`** ที่มีทั้งสถานะ Default, Hover, Focus, Disabled พร้อมระบบ Focus Ring ใน Figma [55-59] +2. ดูแนวทางการเขียน **Tailwind Config** เพื่อรับค่า Design Tokens จาก Figma มาใช้ในโปรเจกต์ Vite + React [52] + +คุณสนใจดูรายละเอียดในส่วนไหนเพิ่มเติมไหมครับ? diff --git a/Documents_Markdown b/Documents_Markdown new file mode 100644 index 0000000..c3c302c --- /dev/null +++ b/Documents_Markdown @@ -0,0 +1,107 @@ +📂 รวมไฟล์เอกสาร Markdown (ทั้งหมด) + +มาตรฐาน: ZyntroAI •  Origin  Branch • Secure • Multilingual (TH/EN) +อัปเดต: 14 กันยายน 2026 + +  + +📄 ไฟล์หลักรีโป + +🔹 README.md + +ภาพรวมโปรเจกต์ • เริ่มต้นใช้งานเร็ว • คุณสมบัติ • ตัวอย่างโค้ด • ลิงก์สำคัญ • เวอร์ชัน/สาขา + +🔹 SECURITY.md + +นโยบายความปลอดภัย • วิธีรายงานช่องโหว่ • สถานะรองรับ • มาตรฐาน SHA-Pin/GPG/SLSA + +🔹 CONTRIBUTING.md + +กฎการมีส่วนร่วม • รูปแบบสาขา • คอมมิต • PR • การตรวจสอบ • หลักการเขียนโค้ด + +🔹 ARCHITECTURE.md + +ภาพรวมระบบ • โครงสร้างโฟลเดอร์ • เลเยอร์การทำงาน • โฟลว์ข้อมูล • สถาปัตยกรรมความปลอดภัย + +🔹 CHANGELOG.md + +ประวัติเวอร์ชัน • การเปลี่ยนแปลง • แก้ไข • เพิ่ม • ลบ • อ้างอิง PR/Issue + +🔹 PROBLEMS.md + +ปัญหาที่ทราบ • ข้อจำกัด • วิธีแก้ชั่วคราว • แผนการแก้ไขในอนาคต + +  + +📁 เอกสารในโฟลเดอร์  docs/  + +🛠️ คู่มือการติดตั้ง & ใช้งาน + +- setup.md: เตรียมสภาพแวดล้อม • ติดตั้ง • คอนฟิก • ตรวจสอบ +- api.md: รายการ Endpoint • Schema • ตัวอย่างคำขอ/ตอบ • Auth +- workflows.md: CI/CD • GitHub Actions • SHA-Pin • ตัวอย่างไฟล์ +- live-editing.md: การแก้ไขแบบเรียลไทม์ • ความปลอดภัย +- troubleshooting.md: ปัญหาที่พบบ่อย • วิธีแก้ • การกู้คืน + +📋 เทมเพลต & แบบฟอร์ม + +- PULL_REQUEST_TEMPLATE.md: แบบฟอร์ม PR • รายการตรวจสอบ • SHA/GPG/CI +- ISSUE_TEMPLATE.md: แบบฟอร์มปัญหา/ฟีเจอร์ • ประเภท • สภาพแวดล้อม +- COMPANY_TEMPLATE.md: ข้อมูลองค์กร • เวอร์ชัน • ติดต่อ • ป้ายความปลอดภัย + +🧩 คู่มือภาษา & โค้ด + +- JSX_GUIDE.md: มาตรฐาน JSX • โครงสร้าง • PropTypes • ความปลอดภัย +- TSX_GUIDE.md: มาตรฐาน TSX • Type • Interface • Clean Code +- MOBILE_GITHUB_SKILLS.md: การใช้งาน GitHub บนมือถือ • SSH • Push • CI + +🧹 บำรุงรักษา & เครื่องมือ + +- CHORES.md: งานประจำ • รายสัปดาห์/เดือน • ความสะอาดรีโป +- COPILOT_CLI.md: คู่มือ Copilot CLI • คำสั่ง • ขั้นสูง • การผสานงาน +- BEST_PRACTICES.md: หลักการทั่วไป • Git • ความปลอดภัย • ทีมงาน + +  + +📝 บันทึกชั่วคราว (เพิ่มเติม) + +📄 TMP_CONTACT_NATTAPONG.md + +- ชื่อ: Nattapong P +- อีเมล: nobizzmaru_new_computer@outlook.com +- ไฟล์อ้างอิง: +- Unified FastAPI_26...28.jpg (355KB) +- Unified FastAPI_26...29.jpg (288KB) +- Unified FastAPI_26...30.jpg (133KB) + +  + +📋 โครงสร้างรวมทั้งหมด + +plaintext + +ZyntroAI/fastapi-python-boilerplate/ +├─ README.md +├─ SECURITY.md +├─ CONTRIBUTING.md +├─ ARCHITECTURE.md +├─ CHANGELOG.md +├─ PROBLEMS.md +├─ docs/ +│ ├─ setup.md +│ ├─ api.md +│ ├─ workflows.md +│ ├─ live-editing.md +│ ├─ troubleshooting.md +│ ├─ JSX_GUIDE.md +│ ├─ TSX_GUIDE.md +│ ├─ MOBILE_GITHUB_SKILLS.md +│ ├─ CHORES.md +│ ├─ COPILOT_CLI.md +│ └─ BEST_PRACTICES.md +└─ .github/ + ├─ PULL_REQUEST_TEMPLATE.md + └─ ISSUE_TEMPLATE.md +  + +✅ ทุกไฟล์สอดคล้องกัน • รูปแบบเดียวกัน • พร้อมใช้งานครับ diff --git a/Notes_260914_085337.txt b/Notes_260914_085337.txt new file mode 100644 index 0000000..4bc9d97 --- /dev/null +++ b/Notes_260914_085337.txt @@ -0,0 +1,392 @@ +🔐 กำหนดสิทธิ์เฉพาะงาน:  taskorg.jsx  + +รหัสงาน: ZYN-PERM-20260914-001 +ขอบเขต: เฉพาะงานนี้เท่านั้น | เจ้าของ: ZyntroAI + +⏰ ช่วงเวลาสิทธิ์ + +• เริ่ม: 14 กันยายน 2026 — 08:25:00 +• จบ: 14 กันยายน 2026 — 23:59:59 (หรือเมื่อปิดงานทันที) +• สถานะ: ✅ เปิดใช้งาน • จำกัดเวลา • จำกัดขอบเขต + +📋 สิทธิ์ที่ได้รับ + +✅ อ่าน (Read): ดูข้อมูลบัญชี, อุปกรณ์, ลิงก์, แอปใน  taskorg.jsx  +✅ เขียน (Write): แก้ไข/บันทึกข้อมูลในส่วนที่เกี่ยวข้อง +✅ อัปเดต (Update): รีเฟรชสถานะ, ซิงก์ข้อมูล, ปรับค่าในงานนี้ +✅ ปิดจบ (Close): ทำเครื่องหมายเสร็จสิ้น, ปิดงานในระบบ + +⚠️ ขอบเขตจำกัดชัดเจน + +• 📍 ใช้ได้เฉพาะ: โมดูล  taskorg.jsx  +• 🚫 ห้าม: เขียนไฟล์อื่น, แก้ CI/CD, เข้าถึงข้อมูลลับ, ลบงาน +• ⏱️ หมดอายุ: ตามเวลาจบ หรือเมื่องานปิด + +🧩 โค้ดฝังในระบบ + +jsx +const PERMISSIONS = { +scope: "taskorg.jsx / ZYN-WF-20260914-001", +start: "2026-09-14T08:25:00+07:00", +end: "2026-09-14T23:59:59+07:00", +granted: ["read", "write", "update", "close"], +restricted: ["admin", "delete", "repo-write"], +validateTime: () => new Date() >= new Date(this.start) && new Date() <= new Date(this.end) +}; + +✅ พร้อมใช้งานตามเวลาและขอบเขตที่กำหนดครับ 🚀🔒📅 +ดูการสนทนา Fig นี้ +https://share.hellofig.app/QZtcotVeJIWQ9T5ad84-VxX347YlG3Xc +https://www.dola.com/download +https://support.claude.com/en/ +https://help.openai.com/en/collections/5461535-android-app?source=in_app_settings_android +https://www.dola.com/thread/xvLiMW7MM1XDWTfii +https://www.dola.com/thread/xWiaPTLClaOzonJtS +https://www.dola.com/thread/xu0FCH4kZPjAD7taW +https://www.dola.com/thread/xYQ6WNsZ7MMxvYTWJ +taskorg.jsxhttps://github.com/ZyntroAI/Organization/discussions/1 +https://github.com/ZyntroAI/main/pull/1 +https://github.com/ZyntroAI/fastapi-python-boilerplate/discussions/154 +https://github.com/ZyntroAI/new-crystalcastle/discussions/112 +https://github.com/ZyntroAI/new-crystalcastle/discussions/94 +https://github.com/ZyntroAI/crystalcastleX/discussions/5 +https://www.githubstatus.com/ +📚 คู่มือวิจัย & ตั้งค่า: Environment + Branch (GitHub Standard) + +สำหรับ: ZyntroAI / TaskOrg / FastAPI Boilerplate +อัปเดต: 2026-09-14 | เป้าหมาย: ความปลอดภัย + ความชัดเจน + ไหลเวียนงาน + +🌿 PART 1: Branch Strategy & Protection Rules + +✅ โครงสร้างสาขามาตรฐาน (แนะนำสำหรับองค์กร) + +plaintext +main (ผลิตภัณฑ์/เสถียร) +↳ dev (รวมฟีเจอร์/ทดสอบ) +↳ feature/taskorg-jsx (งานปัจจุบัน) +↳ fix/name (แก้ไข) + +🛡️ กฎปกป้องสาขา (Branch Protection Rules) + +เปิดใช้สำหรับ  main  /  dev : + +1. Require pull request reviews before merging: ✅ 1-2 อนุมัติ +2. Require status checks to pass: ✅ CI / Test / Lint / SHA-Verify +3. Require signed commits: ✅ ป้องกันการแก้ไขแอบอ้าง +4. Include administrators: ✅ บังคับทุกคนรวมแอดมิน +5. Restrict who can push: ✅ เฉพาะทีมอนุมัติ +6. Do not allow bypassing: ✅ ไม่ข้ามกฎ + +📝 ข้อความคอมมิต & PR + +• ใช้ Conventional Commits:  feat: ,  fix: ,  docs: ,  refactor:  +• PR ต้องอ้างอิง #Issue + +🧪 PART 2: Environment Configuration (GitHub Environments) + +✅ คืออะไร? + +แยกสภาพแวดล้อม โดยอิสระ:  production  →  staging  →  development  +แยกความลับ, กฎการอนุมัติ, ผู้อนุญาต, เวลารอคิว + +🛠️ ขั้นตอนสร้าง & ตั้งค่า + +1️⃣ สร้าง Environment + +• ไปที่ Repo → Settings → Environments → New Environment +• ชื่อ:  production  /  staging  /  dev  + +2️⃣ กฎหลัก (สำคัญมาก) + +• Wait timer: 0–30 นาที (รอตรวจสอบ) +• Required reviewers: ระบุทีม/บุคคลต้องอนุมัติก่อนเผยแพร่ +• Prevent self-review: ✅ ป้องกันคนทำงานอนุมัติเอง +• Deployment branches: +•  production : เฉพาะ  main  +•  staging :  dev  เท่านั้น +•  dev : ทุกสาขา +• Environment secrets: แยกกัน ไม่ซ้ำกัน +•  PROD_TOKEN ,  STAGING_DB ,  DEV_SLACK_WEBHOOK  + +3️⃣ เชื่อมใน Workflow + +yaml +jobs: +deploy: +runs-on: ubuntu-latest +environment: production # 🎯 กำหนดตรงนี้ +env: +APP_ENV: production +steps: +- uses: actions/checkout@v4 +- name: Deploy +env: +SECRET_KEY: ${{ secrets.PROD_KEY }} +run: ./deploy.sh + +🔗 PART 3: การผสานเข้ากับระบบของเรา + +✅ สำหรับ  taskorg.jsx  + +• เพิ่มแท็บ/ส่วน: 🌐 Environments → แสดงสถานะแต่ละระดับ +• บันทึกใน  CONFIG : + +js +const ENV_CONFIG = { +production: { branch: "main", url: "prod.zyntroai.com" }, +staging: { branch: "dev", url: "stg.zyntroai.com" }, +dev: { branch: "feature/*", url: "dev.zyntroai.com" } +}; + +✅ ความลับ & ความปลอดภัย + +• ไม่ใส่ในโค้ด: ใช้ GitHub Secrets / Repo Secrets / Environment Secrets +• SHA-Pin Actions: ทุก  uses:  ต้องเป็น  @commit-hash  +• ตรวจสอบสิทธิ์: ไม่ให้สิทธิ์เกินความจำเป็น + +✅ โครงสร้างไฟล์แนะนำ + +plaintext +.github/ +environments/ +production.md +staging.md +dev.md +workflows/ +deploy-prod.yml +deploy-stg.yml +ci.yml + +📋 PART 4: ตรวจสอบความถูกต้อง (Checklist) + +🧱 Branch + + main  ป้องกันอย่างเข้มงวด +ต้องผ่าน CI/Review ก่อน Merge +ไม่มี Push ตรงได้ + +🌐 Environment + +แยกชัดเจน 3 ระดับ +Secrets แยกกัน +กฎการอนุมัติเปิดใช้ +จำกัดสาขาที่ Deploy ได้ + +🔄 Workflow + +อ้างอิง Environment ถูกต้อง +ใช้ SHA-Pin ทั้งหมด +ตรวจสอบสิทธิ์  permissions:  + +📊 PART 5: Best Practice 2026 + +• Environment per Stage: ไม่รวมกัน +• Branch Source Control: Production ← Main เท่านั้น +• Least Privilege: จำกัดผู้อนุมัติ +• Audit Log: บันทึกทุกการเปลี่ยนแปลง +• Reusable Workflow: แชร์ขั้นตอนทั่วไป ลดความซ้ำ + +🚀 PART 6: คำสั่งเริ่มต้น (GitHub CLI) + +bash +สร้าง Environment +gh api --method PUT /repos/ZyntroAI/pure-agent-dev/environments/production + -f wait_timer=5 -q '{"required_reviewers":[{"login":"admin-team"}]}' + +ตั้งค่า Secret +gh secret set PROD_TOKEN --env production --repo ZyntroAI/pure-agent-dev + +ตรวจสอบสาขา +gh branch-protection main --repo ZyntroAI/pure-agent-dev --list + +✅ สรุปสำหรับนำไปใช้ + +Environment + Branch คู่กัน: + +• 🧱 Branch: ควบคุมคุณภาพโค้ดต้นทาง +• 🌐 Environment: ควบคุมการเผยแพร่ & ความลับปลายทาง +• 🤝 ผสาน:  feature → dev → main  พร้อมกับ  dev → staging → production  + +บันทึกนี้สอดคล้องกับ  taskorg.jsx  และสถาปัตยกรรม ZyntroAI ครบถ้วนครับ! 🛡️🌿✅ +📚 คู่มือการรวม Repository (GitHub) — ฉบับสมบูรณ์ & ปลอดภัย + +สำหรับ: ZyntroAI / FastAPI / TaskOrg +หลักการ: ✅ เก็บประวัติครบถ้วน • ✅ ไม่ทำลายโค้ด • ✅ สะอาดเป็นระเบียบ • ✅ รักษา Git Hash & Commit + +🎯 1. ภาพรวม & เหตุผลการรวม + +✅ ทำไมต้องรวม? + +• รวมโครงการที่เกี่ยวข้องเข้าที่เดียว → จัดการง่าย +• ลดการกระจัดกระจาย → ควบคุมสิทธิ์/CI/CD สะดวก +• รักษาประวัติ Git ทั้งหมด (ไม่ใช่แค่คัดลอกไฟล์) +• สอดคล้องกับ  Environment/Branch Strategy  ขององค์กร + +⚠️ สิ่งที่ต้องตรวจก่อนเริ่ม + +สิทธิ์: Owner/Maintainer ทั้งต้นทาง & ปลายทาง +สำรองข้อมูล: Fork/Clone สำเนา ก่อนทำ +ความขัดแย้ง: ตรวจสอบชื่อโฟลเดอร์/ไฟล์ซ้ำกัน +Branch: ปิด PR ค้าง • ใช้  main/dev  ชัดเจน + +🛠️ 2. วิธีรวมทีละขั้นตอน (เก็บประวัติครบ) + +📌 กรณี: รวม  repo-source  →  repo-target  (เป็นโฟลเดอร์ย่อย) + +เป้าหมาย:  repo-target/modules/repo-source/  + ประวัติครบ + +1️⃣ เตรียมเครื่องมือ & คลอน + +bash +สร้างโฟลเดอร์ทำงาน +mkdir merge-repos && cd merge-repos + +คลอนทั้งสองแบบเต็ม +git clone https://github.com/ZyntroAI/repo-target.git target +git clone https://github.com/ZyntroAI/repo-source.git source + +2️⃣ เตรียม Repo ต้นทาง (ย้ายทุกอย่างลงโฟลเดอร์ย่อย) + +bash +cd source +git checkout main + +สร้างโครงสร้างย่อย — ป้องกันชน +mkdir -p modules/repo-source +git mv ./* modules/repo-source/ 2>/dev/null || true +echo "# Moved from repo-source" > modules/repo-source/README.md + +คอมมิตการย้าย +git add . +git commit -m "refactor: prepare repo-source for merge → subfolder +✅ Preserve full git history +📍 Path: modules/repo-source" + +3️⃣ ดึงเข้าเป้าหมาย (ผสานไม่ทำลาย) + +bash +cd ../target + +เพิ่มต้นทางเป็น remote ชั่วคราว +git remote add source ../source +git fetch source main --no-tags + +ผสานโดยไม่ปะทะ +git merge --allow-unrelated-histories source/main -m "merge: add repo-source into modules/ +✅ Full history preserved +🔗 Source: ZyntroAI/repo-source" + +4️⃣ จัดระเบียบ & ล้าง + +bash +ลบ remote ชั่วคราว +git remote remove source + +ตรวจสอบ: โครงสร้าง, ประวัติ, ความขัดแย้ง +git log --graph --oneline --all +ls -la modules/ + +พุชไปยังเป้าหมาย +git push origin main + +🧩 3. กรณีพิเศษ & ตัวอย่างจริง (ZyntroAI) + +✅ รวมเข้า  fastapi-python-boilerplate  + +plaintext +เป้าหมาย: fastapi-python-boilerplate/ +↳ app/ +↳ modules/ +↳ crystalcastleX/ # รวมมา +↳ pure-agent-dev/ # รวมมา +↳ .github/ +↳ taskorg.jsx + +📌 คำสั่งรวมหลายรีโปต่อเนื่อง + +bash +วนลูปรวมทีละตัวในโฟลเดอร์ modules/ +REPOS=("crystalcastleX" "pure-agent-dev") +TARGET="fastapi-python-boilerplate" + +for r in "r.git tmp-r && mkdir -p modules/r/ 2>/dev/null +git add . && git commit -m "prepare TARGET +git remote add tmp ../tmp-r" +git remote remove tmp && cd .. && rm -rf tmp-$r +done + +⚠️ 4. จัดการความขัดแย้ง & ปัญหาที่พบบ่อย + +❌ ไฟล์ซ้ำ (README, LICENSE, CI) + +• กฎ: เก็บของเป้าหมายหลัก • รวมเนื้อหาต้นทางเข้า +• ตัวอย่าง: +•  README.md  → รวมเป็นบท  ## 📦 Included Modules  +•  .github/workflows/  → รวมเป็นชุดใหม่ตาม  taskorg.jsx  +•  LICENSE  → เก็บหลัก + อ้างสิทธิ์เดิมในไฟล์ย่อย + +❌ Commit Confusion / History ยุ่งเหยิง + +• ห้ามใช้:  --squash  ถ้าต้องการเก็บประวัติ +• ใช้:  --allow-unrelated-histories  + ย้ายเป็นโฟลเดอร์ก่อน +• ตรวจ:  git log --follow path/to/file  → ต้องเห็นอดีตครบ + +❌ Submodule vs Merge (ต่างกันอย่างไร) + +• 🔗 Submodule: เชื่อมโยงภายนอก • แยกอัปเดต • ไม่รวมโค้ดจริง +• ✅ Merge (เราเลือก): รวมทุกอย่างเข้าโครงสร้างเดียว • ประวัติในที่เดียว • จัดการง่าย + +🛡️ 5. หลังรวมเสร็จ: ตรวจสอบ & อัปเดต + +✅ รายการตรวจสอบ + +ประวัติ Git ครบทุกสาขา +โครงสร้างโฟลเดอร์ชัดเจน ( modules/ ) +CI/CD รันผ่าน • อัปเดตพาธใน  workflows/  + README.md  อธิบายส่วนประกอบ +Environment/Branch Rules ยังใช้ได้ +ลิงก์เก่า/Issue/PR อัปเดตหรือเปลี่ยนทาง + +📝 อัปเดตเอกสารหลัก + +markdown +📦 รวม Repository — ZyntroAI/fastapi-python-boilerplate +📅 รวมเมื่อ: 14 กันยายน 2026 +✅ ประวัติ: ครบถ้วนทุกสาขา + +🧩 โครงสร้างใหม่ +• 🧱 Core: app/ (FastAPI) +• 📦 Modules: +• crystalcastleX — 📂 modules/crystalcastleX +• pure-agent-dev — 📂 modules/pure-agent-dev +• 📊 Dashboard: taskorg.jsx + +🔗 ลิงก์เดิมยังใช้ได้ +• Redirect: GitHub Auto-Redirect + +📋 6. เทมเพลต PR/Merge Log + +plaintext +🚀 Merge Repositories: Complete +📦 รวมเข้า: fastapi-python-boilerplate +• ✅ Source 1: crystalcastleX (main) +• ✅ Source 2: pure-agent-dev (main) +🧹 Strategy +• 📂 Subfolder: All under modules/ +• 📜 History: FULL PRESERVED (no squash) +• ⚔️ Conflicts: Resolved (README, CI, LICENSE) +✅ Verify +• Git log intact +• CI Passing +• Structure clean + +🎯 7. สรุปขั้นตอนรวดเร็ว (One-Page) + +1. Backup: Clone ทุกตัว +2. Prepare: ย้ายต้นทางเป็นโฟลเดอร์ย่อย +3. Merge:  git remote add  +  fetch  +  merge --allow-unrelated  +4. Resolve: แก้ไฟล์ชนกัน +5. Verify: ตรวจประวัติ/โครงสร้าง/CI +6. Push: ส่งขึ้นเป้าหมาย • อัปเดตเอกสาร + +งานนี้สอดคล้องกับ  taskorg.jsx  และ Environment/Branch ของเรา 100% ครับ — รวมเสร็จแล้วระบบจะเป็นหนึ่งเดียว สะอาด และบำรุงรักษาง่าย! 🚀📂🔗✅ \ No newline at end of file diff --git a/README.md b/README.md index 32f6df6..bdb5aed 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,345 @@ -# FastAPI Python Boilerplate — AI-Driven +Here’s **การออกแบบ GitHub Actions Workflows สำหรับ `Origin`** (หลังจากเปลี่ยนเป็น default branch แล้ว) ที่แยก **CI** และ **Workflows อื่นๆ** อย่างชัดเจน พร้อมคำแนะนำสำหรับ FastAPI project ของคุณ: -An opinionated FastAPI monorepo used by ZyntroAI as the starting point for production -AI services, agent tooling, and reference documentation. It ships an OAuth2 PKCE API -core, a GraphQL layer, a React frontend, a library of reusable AI-agent skills, -self-contained deliverable suites, and a reference docs library. +--- + +--- + +## 📁 **โครงสร้างไฟล์ Workflows** +``` +.github/ +└── workflows/ + ├── ci.yml # CI (Test, Lint, Build) + ├── cd-deploy.yml # CD (Deploy to Staging/Production) + ├── scheduled-cleanup.yml # Scheduled Jobs + ├── release.yml # Release Management + └── notify.yml # Notifications (Slack/Email) +``` + +--- + +--- + +## 🔧 **1. CI Workflow (`ci.yml`)** +**หน้าที่:** รัน **Test, Lint, Build** ทุกครั้งที่มี `push` หรือ `pull_request` ไปยัง `Origin` หรือ branch อื่นๆ + +```yaml +# .github/workflows/ci.yml +name: CI - Test & Lint + +on: + push: + branches: [ Origin, main ] # รันทั้ง Origin และ main (ถ้ายังใช้ main ร่วมด้วย) + pull_request: + branches: [ Origin ] + +jobs: + test: + runs-on: ubuntu-latest + strategy: + matrix: + python-version: ["3.10", "3.11"] # ตัวอย่างสำหรับ Python + + steps: + - uses: actions/checkout@v4 + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r requirements.txt + pip install pytest pytest-cov flake8 black + + - name: Run Lint (Flake8) + run: flake8 . + + - name: Run Formatter (Black) + run: black --check . + + - name: Run Tests with Coverage + run: | + pytest --cov=./ --cov-report=xml + # Upload coverage to Codecov (ถ้าต้องการ) + curl -Os https://uploader.codecov.io/latest/linux/codecov + chmod +x codecov + ./codecov -t ${{ secrets.CODECOV_TOKEN }} + + build: + needs: test # รอให้ test เสร็จก่อน + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Build Docker Image (ตัวอย่าง) + run: | + docker build -t zyntroai/fastapi-project:latest . + docker images +``` -> This README reflects the repository as it actually stands on `main`. Sections marked -> **Known state** record things that are incomplete or broken rather than describing -> intent. Individual suites under `deliverables/` carry their own READMEs with more detail. +--- + +--- + +## 🚀 **2. CD Workflow (`cd-deploy.yml`)** +**หน้าที่:** Deploy โค้ดไปยัง **Staging** และ **Production** หลังจาก CI ผ่าน + +```yaml +# .github/workflows/cd-deploy.yml +name: CD - Deploy + +on: + push: + branches: [ Origin ] # Deploy เฉพาะเมื่อ push ไปยัง Origin + workflow_dispatch: # หรือกด manual deploy ใน GitHub UI + +jobs: + deploy-staging: + runs-on: ubuntu-latest + environment: + name: staging + url: https://staging.zyntroai.com + steps: + - uses: actions/checkout@v4 + - name: Deploy to Staging (Vercel) + run: | + vercel --token ${{ secrets.VERCEL_TOKEN }} --env staging + env: + VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }} + VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }} + + deploy-production: + needs: deploy-staging # รอ staging deploy เสร็จก่อน + if: github.ref == 'refs/heads/Origin' # Deploy เฉพาะเมื่อ push ไป Origin + runs-on: ubuntu-latest + environment: + name: production + url: https://api.zyntroai.com + steps: + - uses: actions/checkout@v4 + - name: Deploy to Production (Vercel) + run: | + vercel --prod --token ${{ secrets.VERCEL_TOKEN }} + env: + VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }} + VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }} +``` + +--- + +--- + +## ⏰ **3. Scheduled Workflow (`scheduled-cleanup.yml`)** +**หน้าที่:** รันงานบำรุงรักษา (เช่น ลบ cache, backup database) ตามกำหนดการ + +```yaml +# .github/workflows/scheduled-cleanup.yml +name: Scheduled - Cleanup & Backup + +on: + schedule: + - cron: '0 0 * * 1' # รันทุกวันจันทร์ เวลา 00:00 UTC (07:00 ICT) + workflow_dispatch: # หรือกด manual ใน GitHub UI + +jobs: + cleanup: + runs-on: ubuntu-latest + steps: + - name: Clean old Docker images + run: | + docker system prune -af + + backup: + runs-on: ubuntu-latest + steps: + - name: Backup Database + run: | + pg_dump -U ${{ secrets.DB_USER }} -h ${{ secrets.DB_HOST }} ${{ secrets.DB_NAME }} > backup.sql + # Upload backup ไปยัง S3/Google Drive (ตัวอย่าง) + aws s3 cp backup.sql s3://zyntroai-backups/backup-$(date +%Y%m%d).sql + env: + AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} +``` --- -## What's inside +--- -| Path | Purpose | -| ---- | ------- | -| `main.py` | OAuth2 PKCE API entrypoint — `uvicorn main:app` (`/auth`, `/auth/callback`, `/health`) | -| `app/` | Application package (75 files): `api/`, `core/`, `services/`, `db/`, `routes/`, `integrations/` | -| `app/core/main.py` | A second, fuller FastAPI app (items/users routers, DB session, origin middleware) | +## 📦 **4. Release Workflow (`release.yml`)** +**หน้าที่:** สร้าง **Release** และ Publish Package (เช่น Docker Image, PyPI) เมื่อมี tag ใหม่ + +```yaml +# .github/workflows/release.yml +name: Release - Publish + +on: + push: + tags: + - 'v*' # Trigger เมื่อ push tag เช่น v1.0.0 + +jobs: + build-and-publish: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Build Docker Image + run: | + docker build -t zyntroai/fastapi-project:${{ github.ref_name }} . + docker tag zyntroai/fastapi-project:${{ github.ref_name }} zyntroai/fastapi-project:latest + + - name: Login to Docker Hub + run: echo "${{ secrets.DOCKER_PASSWORD }}" | docker login -u "${{ secrets.DOCKER_USERNAME }}" --password-stdin + + - name: Push Docker Image + run: | + docker push zyntroai/fastapi-project:${{ github.ref_name }} + docker push zyntroai/fastapi-project:latest + + - name: Create GitHub Release + uses: softprops/action-gh-release@v1 + with: + tag_name: ${{ github.ref_name }} + name: Release ${{ github.ref_name }} + body: | + Changes in this release: + - Fix bug in API endpoint + - Update dependencies +``` + +--- + +--- + +## 📢 **5. Notification Workflow (`notify.yml`)** +**หน้าที่:** ส่งแจ้งเตือนไปยัง **Slack** หรือ **Email** เมื่อ CI/CD สำเร็จ/ล้มเหลว + +```yaml +# .github/workflows/notify.yml +name: Notify - Slack Alerts + +on: + workflow_run: + workflows: ["CI - Test & Lint", "CD - Deploy"] # รันหลัง CI/CD + types: + - completed + +jobs: + notify: + runs-on: ubuntu-latest + if: ${{ github.event.workflow_run.conclusion != 'neutral' }} + steps: + - name: Send Slack Notification + uses: rtCamp/action-slack-notify@v2 + env: + SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }} + SLACK_COLOR: ${{ github.event.workflow_run.conclusion == 'success' && 'good' || 'danger' }} + SLACK_TITLE: "Workflow ${{ github.event.workflow_run.conclusion }}" + SLACK_MESSAGE: | + Workflow *${{ github.event.workflow_run.name }}* ${{ github.event.workflow_run.conclusion == 'success' && '✅ Success' || '❌ Failed' }} + Commit: ${{ github.event.workflow_run.head_commit.message }} + Branch: ${{ github.event.workflow_run.head_branch }} + Link: ${{ github.event.workflow_run.html_url }} +``` + +--- + +--- + +## 🔐 **Secrets ที่จำเป็น** +ไปที่ **Settings > Secrets > Actions** เพื่อเพิ่ม: +| **Secret Name** | **คำอธิบาย** | +|--------------------------|----------------------------------------| +| `VERCEL_TOKEN` | Token สำหรับ Vercel Deployment | +| `VERCEL_PROJECT_ID` | Project ID ใน Vercel | +| `VERCEL_ORG_ID` | Organization ID ใน Vercel | +| `DOCKER_USERNAME` | Username Docker Hub | +| `DOCKER_PASSWORD` | Password Docker Hub | +| `CODECOV_TOKEN` | Token สำหรับ Codecov (ถ้าใช้) | +| `SLACK_WEBHOOK` | Slack Incoming Webhook URL | +| `AWS_ACCESS_KEY_ID` | AWS Key สำหรับ Backup | +| `AWS_SECRET_ACCESS_KEY` | AWS Secret Key | +| `DB_USER`, `DB_HOST`, `DB_NAME` | ข้อมูล database สำหรับ Backup | + +--- + +--- + +## 📌 **คำแนะนำเพิ่มเติม** +1. **Environment Protection** + - ใน `cd-deploy.yml` ใช้ `environment:` เพื่อกำหนด **approval** ก่อน deploy production: + ```yaml + environment: + name: production + url: https://api.zyntroai.com + ``` + (GitHub จะขอ approval ก่อนรัน job นี้) + +2. **Matrix Testing** + - ใน `ci.yml` ใช้ `matrix` เพื่อทดสอบกับ **Python version หลายๆ เวอร์ชัน** หรือ **OS หลายๆ ตัว** + +3. **Artifacts** + - ถ้าต้องการเก็บผลลัพธ์จาก CI (เช่น test report, coverage): + ```yaml + - name: Upload Test Report + uses: actions/upload-artifact@v4 + with: + name: pytest-report + path: test-results/ + ``` + +4. **Cache Dependencies** + - เพิ่ม cache สำหรับ `pip` เพื่อเร่งความเร็ว: + ```yaml + - name: Cache pip + uses: actions/cache@v3 + with: + path: ~/.cache/pip + key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }} + ``` + +5. **Auto-merge Dependabot** + - สร้าง workflow สำหรับ auto-merge Dependabot PR ถ้า CI ผ่าน: + ```yaml + # .github/workflows/dependabot-auto-merge.yml + name: Dependabot Auto Merge + on: + pull_request: + branches: [ Origin ] + jobs: + auto-merge: + if: github.actor == 'dependabot[bot]' + runs-on: ubuntu-latest + steps: + - uses: actions/github-script@v7 + with: + script: | + github.pulls.merge({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: context.issue.number, + merge_method: 'squash' + }) + ``` + +--- + +--- +## ✅ **สรุปการทำงาน** +1. **Developer push code → `Origin`** + → **CI Workflow** รัน (Test, Lint, Build) + → ถ้า **CI ผ่าน** → **CD Workflow** รัน (Deploy to Staging) + → ถ้า **Staging OK** → **CD Workflow** Deploy to Production (หรือรอ approval) +2. **ทุกวันจันทร์** → **Scheduled Workflow** รัน (Cleanup, Backup) +3. **เมื่อมี tag ใหม่** → **Release Workflow** รัน (Publish Docker Image, Create Release) +4. **หลัง CI/CD เสร็จ** → **Notification Workflow** ส่งแจ้งเตือนไปยัง Slack + +--- +**✨ พร้อมใช้งาน!** +คุณสามารถ copy code นี้ไปวางใน `.github/workflows/` ของ repo ได้เลย ครับ +ถ้าต้องการปรับแต่ง (เช่น ใช้ AWS ECS แทน Vercel) ให้บอกมาได้นะ!| `app/core/main.py` | A second, fuller FastAPI app (items/users routers, DB session, origin middleware) | | `graphql_api/` | Standalone GraphQL service — Strawberry + async SQLAlchemy + JWT + Alembic, own `requirements.txt`, `docker-compose.yml`, tests | | `frontend/` | React 18 + Vite 8 + TypeScript frontend (own `package.json`, `Dockerfile`, `tsconfig.json`) | | `skills/` | Reusable AI-agent skill definitions (`fetching`, `changelog-auto-update`, `credential-management`, `patch`, `research`, …) |