data-contract

name	data-contract
description	ร่าง data contract ระหว่างผู้ผลิตกับผู้ใช้ข้อมูล — schema, ความหมาย (หน่วย, timezone, null), quality SLA, กติกาการเปลี่ยนแปลง — แล้ว generate เทสบังคับใช้จริงตาม stack ที่มี (dbt tests, Great Expectations, pydantic) พร้อมเสนอผูกเข้า CI Trigger on "data contract", "schema contract", "ทำสัญญา schema", "กัน schema พัง", or when upstream schema changes keep breaking downstream consumers.

data-contract — สัญญาที่ไม่มีเทสบังคับ คือความหวัง ไม่ใช่สัญญา

Phase 0 — รู้จักคู่สัญญา

ถามรวบครั้งเดียว (หรืออ่านจาก repo ถ้ามี):

1. Dataset ไหน — ตาราง/topic/ไฟล์ อะไร ใครเป็นเจ้าของฝั่งผลิต
2. ใครใช้ ใช้ทำอะไร — dashboard? โมเดล ML? billing? ความหมายของ "พัง" ต่างกันมาก: dashboard เพี้ยน 1 วันพอทน billing เพี้ยนแถวเดียวคือเรื่องใหญ่ → ความเข้มของ contract ต้องตามนั้น
3. Stack ที่บังคับใช้ได้ — dbt? Great Expectations? Python เพียวๆ (pydantic)? เขียนเทสให้ตรงเครื่องมือที่มีจริง

Phase 1 — ร่าง contract 4 ชั้น

ชั้น	ระบุอะไร	ตัวอย่าง
Schema	คอลัมน์, type, nullable, PK	order_id STRING NOT NULL UNIQUE
Semantics	หน่วย, timezone, enum values, ความหมายของ null	amount = สตางค์ (int) ไม่ใช่บาท, เวลาทั้งหมด UTC, status ∈ {paid, refunded, void}
Quality SLA	freshness, completeness, uniqueness, ช่วงค่าที่ยอมรับ	มาถึงก่อน 06:00 ทุกวัน, row count ±30% ของค่าเฉลี่ย 7 วัน
Change policy	อะไรทำได้เลย อะไรต้องแจ้งล่วงหน้า	เพิ่มคอลัมน์ nullable = ทำได้เลย; ลบ/rename/เปลี่ยน type = breaking ต้องแจ้ง ≥N วัน + ช่วง dual-write

ชั้น Semantics คือชั้นที่คนข้ามบ่อยสุดและเจ็บสุด — schema ตรงแต่หน่วยผิด เทส type จับไม่ได้

Phase 2 — Generate เทสบังคับใช้

• dbt: schema.yml — not_null, unique, accepted_values, dbt_utils.accepted_range, freshness บน source
• Great Expectations / pandera: suite ที่รันใน pipeline ก่อน consume
• pydantic: model สำหรับ validate ตอน ingest แถวต่อแถว
• เขียนไฟล์จริงลง repo แล้วรันให้ดูว่าผ่านกับข้อมูลปัจจุบัน — เทสที่ fail ตั้งแต่วันแรกแปลว่า contract เขียนเกินความจริง ต้องคุยกันว่าจะแก้ข้อมูลหรือแก้สัญญา

Phase 3 — ส่งมอบ

• เอกสาร contract → contracts/<dataset>.md ใน repo (มนุษย์อ่าน) + เทส (เครื่องบังคับ) — ชี้กันไปมา
• เสนอผูกเทสเข้า CI / schedule ของ pipeline — contract ที่รันเฉพาะตอนมีคนนึกได้ ไม่กันอะไร
• ระบุเจ้าของและช่องทางแจ้งเมื่อจะ break — สัญญาไม่มีคู่สัญญา = เอกสารประดับ

กติกา

• อย่าเขียน SLA ที่ไม่มีใครวัดได้จริงในระบบปัจจุบัน — เขียนเท่าที่บังคับได้ แล้วค่อยขยาย
• ค่า threshold (±30%, N วัน) เสนอจากข้อมูลจริงถ้าดูได้ ไม่ใช่เลขสวยลอยๆ