แนวทางสถาปัตยกรรมวิศวกรรมและการไหลของข้อมูล
แผนก
สารบัญ
วัตถุประสงค์
แนวทางนี้กำหนดมาตรฐานสถาปัตยกรรมวิศวกรรมและการไหลของข้อมูลที่ จำเป็น สำหรับแผนกเทคโนโลยีที่ Kiluth
| ผลลัพธ์ |
|---|
| ระบบมีขอบเขตความรับผิดชอบที่ชัดเจน การไหลของข้อมูลที่คาดการณ์ได้ และโค้ดที่ดูแลรักษาได้ซึ่งสามารถพัฒนาได้โดยไม่ทำลายการเชื่อมต่อ |
ขอบเขต
ใช้กับเว็บแอปพลิเคชัน เครื่องมือ CLI ไมโครเซอร์วิส งานพื้นหลัง และการเชื่อมต่อที่สร้างโดยแผนกเทคโนโลยี
เอกสารนี้เน้นที่ การจัดระเบียบโค้ด รูปแบบการไหลของข้อมูล และขอบเขตความรับผิดชอบ ไม่ได้กำหนดภาษา framework หรือตัวเลือกการปรับใช้
คำจำกัดความ
| คำศัพท์ | คำจำกัดความ |
|---|---|
| Contract / DTO | โครงสร้างข้อมูลที่กำหนดขอบเขตภายนอก (request/response/event payload) เป็น “ข้อตกลง” ระหว่างระบบหรือเลเยอร์ |
| Business entity | แนวคิดโดเมนที่ใช้ภายใน application logic (เช่น User, Order) |
| Storage model | การแสดงผลแบบถาวร (DB schema/record/file format) ที่ใช้ภายใน data access |
| Entry point | ขอบเขตกลไกการส่งมอบ (HTTP handler/controller, CLI command, job handler, event handler) |
| Application logic | กฎทางธุรกิจและการประสานงาน (services/use cases) |
| Data access | Repositories/adapters ที่อ่าน/เขียน storage หรือเรียกใช้ระบบภายนอก |
Operating Model
| # | Operating Model |
|---|---|
| 1 | Asana คือระบบหลัก (system of record) สำหรับการติดตามงาน การอนุมัติ และการส่งต่องาน |
| 2 | ใช้จุดตรวจสอบและจุดตัดสินใจ: ไม่ไปขั้นถัดไปจนกว่าขั้นก่อนจะ “เสร็จ”, และกรณีแตกแขนงต้องระบุให้ชัดเจน |
| 3 | ลำดับการส่งต่องาน (handoff order): เอกสาร upstream กำหนดสิ่งที่ต้องส่งมอบ/เกณฑ์จบขั้น; เอกสาร downstream กำหนดวิธีทำงานหลังรับมอบ |
รูปแบบสถาปัตยกรรมหลัก
ประเภทโครงสร้างข้อมูล (แยกให้ชัดเจน)
| ประเภท | ใช้สำหรับ | อยู่ใน |
|---|---|---|
| Contract / DTO | ขอบเขตภายนอก | Entry points / API layer |
| Business entity | Core business logic | Application logic |
| Storage model | การแสดงผลแบบถาวร | Data access |
ความรับผิดชอบของเลเยอร์
การไหลของ dependency เป็นแบบทางเดียว:
Entry point → Application logic → Data access → Storage / External systems
| เลเยอร์ | ความรับผิดชอบ | ต้องไม่ |
|---|---|---|
| Contracts / DTOs | กำหนดรูปร่างข้อมูลขอบเขต | มีกฎทางธุรกิจ รั่วไหลโครงสร้าง storage |
| Entry points | Parse/validate รูปร่างอินพุต แมป DTO ↔ entity เรียกใช้ application logic แมปข้อผิดพลาดเป็น response ของ interface | มี business logic เข้าถึง storage โดยตรง |
| Application logic | บังคับใช้กฎทางธุรกิจ ประสานงาน data access ทำงานกับ entities | รู้เกี่ยวกับรูปแบบ HTTP/CLI ทำงานกับ DTOs/storage models |
| Data access | อ่าน/เขียน storage จัดการ queries/transactions แมป storage ↔ entity รวมระบบภายนอก | ตัดสินใจทางธุรกิจ เปิดเผยรายละเอียด storage/ภายนอกขึ้นไป |
| Storage models | แสดงผลแบบถาวร (tables/records/files) | รั่วไหลเข้า application logic หรือ entry points |
| ผลลัพธ์ |
|---|
| โค้ดทดสอบง่าย เปลี่ยนได้ปลอดภัยกว่า และตรวจสอบได้ชัดเจนกว่า |
Contract-First Workflow (ทีละขั้น)
ใช้ workflow นี้สำหรับระบบใหม่และการเปลี่ยนแปลงที่สำคัญ
| # | ขั้นตอน |
|---|---|
| 1 | กำหนด contracts ก่อน (DTOs ที่ทุกขอบเขต) ตกลงรูปร่างข้อมูลก่อนการดำเนินการ |
| 2 | กำหนด business entities ที่จำเป็นเพื่อให้บริการ contracts |
| 3 | ดำเนินการ application logic โดยใช้ entities เท่านั้น |
| 4 | ดำเนินการ data access (storage/ภายนอก) และการแปล (entity ↔ storage / entity ↔ external) |
| 5 | ดำเนินการ entry points และการแปล (DTO ↔ entity) |
| 6 | เพิ่ม observability ขั้นต่ำ + tests + documentation (ดูด้านล่าง) |
| ผลลัพธ์ |
|---|
| ขอบเขตชัดเจนและการเปลี่ยนแปลงมองเห็นได้และตรวจสอบได้ |
ข้อกำหนดวิศวกรรมขั้นต่ำ
Validation & errors (แบบเลเยอร์)
| ที่ไหน | ต้อง validate อะไร | หมายเหตุ |
|---|---|---|
| Entry points | รูปร่างอินพุต/parsing ฟิลด์ที่จำเป็นพื้นฐาน | ปฏิบัติต่ออินพุตว่าไม่น่าเชื่อถือ; แมปเป็น contracts |
| Application logic | กฎทางธุรกิจ (เสมอ) | แหล่งที่มาของความจริงสำหรับ business validation |
รูปร่างข้อผิดพลาดมาตรฐาน:
{ code: string, message: string, details?: object }
| ผลลัพธ์ |
|---|
| ความล้มเหลวสม่ำเสมอ debug ได้ และปลอดภัยที่จะเปิดเผยภายนอก |
Observability (ขั้นต่ำ)
ทุก use case ควรวินิจฉัยได้โดยไม่ต้อง logging แบบ ad-hoc
| # | การ logging ขั้นต่ำ |
|---|---|
| 1 | Log ที่ entry points สำหรับการเริ่มต้น + เสร็จสิ้น (status, latency) |
| 2 | รวม correlation IDs เมื่อมี (requestId/traceId) + useCase |
| 3 | ไม่ log secrets; หลีกเลี่ยง full payload logs โดยค่าเริ่มต้น |
Configuration & secrets
| กฎ | คำอธิบาย |
|---|---|
| Config flows outside-in | อ่าน config ใน composition root / entry point setup; inject เข้าเลเยอร์ภายใน |
| Never store secrets in code/contracts/logs | ใช้ env/secret managers; redact ค่าที่ละเอียดอ่อน |
Security (ขั้นต่ำ)
| # | ความคาดหวังขั้นต่ำ |
|---|---|
| 1 | Parameterized queries (ไม่ใช้ SQL string concatenation) |
| 2 | ข้อความข้อผิดพลาดที่ปลอดภัยภายนอก; log รายละเอียดภายในด้วย correlation IDs |
| 3 | การตัดสินใจ authorization อยู่ใน application logic (เมื่อใช้ได้) |
Testing (ขั้นต่ำ)
| เลเยอร์ | โฟกัสการทดสอบ |
|---|---|
| Application logic | กฎทางธุรกิจ + error paths (ลำดับความสำคัญสูงสุด) |
| Entry points | การแมป + การแปลข้อผิดพลาด |
| Data access | Query logic + ความถูกต้องของการแปล |
Documentation (ขั้นต่ำ)
ใช้ artifacts ที่เบาและค้นหาได้:
| # | Artifact |
|---|---|
| 1 | Contracts (DTOs) เอกสารที่กำหนดไว้ (comments/readme เมื่อจำเป็น) |
| 2 | หมายเหตุสถาปัตยกรรมสั้น ๆ สำหรับการเปลี่ยนแปลงที่สำคัญ (เช่น การตัดสินใจแบบ ADR) |
Anti-Patterns ที่ควรหลีกเลี่ยง
| # | Anti-pattern | ทำไมถึงเป็นปัญหา |
|---|---|---|
| 1 | Business logic ใน entry points | ทดสอบยาก ทำซ้ำกฎ สร้างพฤติกรรมที่ไม่สอดคล้อง |
| 2 | Application logic ใช้ DTOs/storage models โดยตรง | ขอบเขตเบลอ; การเปลี่ยนแปลงส่งผลกระทบข้ามเลเยอร์ |
| 3 | เข้าถึง storage โดยตรงจาก controllers/handlers | ทำลายขอบเขตความรับผิดชอบ; เพิ่ม coupling |
| 4 | Contracts แบบซ่อนเร้น (ไม่มี DTOs) | การเชื่อมต่อล้มเหลวเงียบ ๆ; ทบทวนและการย้ายข้อมูลยากขึ้น |
| 5 | Logging secrets / raw PII | ความเสี่ยงด้านความปลอดภัยและความเสี่ยงด้านการปฏิบัติตามกฎระเบียบ |
เทมเพลตการ์ด Asana (เมื่อจำเป็น)
ใช้เทมเพลตเมื่อการเปลี่ยนแปลงข้ามขอบเขต ส่งผลกระทบต่อ contracts หรือต้องการการทบทวนที่ชัดเจน
Architecture / Contract Change Review
| เทมเพลตการ์ด Asana | |
|---|---|
| Title | Architecture / contract change review – [System / Feature] |
| Assignee | Technology (owner) |
| Description | กรุณาทบทวนการเปลี่ยนแปลงสถาปัตยกรรม / contract ที่เสนอ: Context • System: [System] • Change summary: [What is changing] • Related proposal / delivery context: [Link] Boundary impact • Contracts/DTOs changed: [Yes/No] (list) • External integrations impacted: [Yes/No] (list) • Data storage impacted: [Yes/No] (list) Requested outcome • Confirm responsibility boundaries and data flow • Confirm backward compatibility or migration plan (if needed) • Confirm minimum logging/testing requirements are met เมื่อเสร็จแล้ว เพิ่มหมายเหตุการตัดสินใจสั้น ๆ และย้ายไปที่ In Review |
เช็กลิสต์สถาปัตยกรรม (แผนกเทคโนโลยีใช้)
Contracts & boundaries
| # | เช็กลิสต์ |
|---|---|
| 1 | ☐ Contracts/DTOs ชัดเจนที่ขอบเขต |
| 2 | ☐ Business entities ใช้เฉพาะภายใน application logic |
| 3 | ☐ Storage models อยู่ใน data access |
Data flow & layering
| # | เช็กลิสต์ |
|---|---|
| 1 | ☐ การไหลของ dependency เป็นทางเดียว (entry point → application logic → data access) |
| 2 | ☐ Entry points แปล DTO ↔ entity |
| 3 | ☐ Data access แปล entity ↔ storage/external contracts |
Safety & operability
| # | เช็กลิสต์ |
|---|---|
| 1 | ☐ ความรับผิดชอบ validation ถูกต้อง (รูปร่างที่ขอบเขต กฎทางธุรกิจใน core) |
| 2 | ☐ การ logging ขั้นต่ำมีอยู่และปลอดภัย (ไม่มี secrets/PII) |
| 3 | ☐ Tests ครอบคลุม critical paths ของ application logic |
| 4 | ☐ มีหมายเหตุการตัดสินใจสั้น ๆ สำหรับการเปลี่ยนแปลงที่สำคัญ (แบบ ADR เมื่อจำเป็น) |