Evolve Safely · Module 05

Data Evolution, External API & Autocomplete

เราจะเปลี่ยน model ที่มีข้อมูลอยู่แล้วและต่อ API โดยไม่ทำของเดิมพังได้อย่างไร?

Safe migrationBackfillAPI contractFallbackAutocompleteRegression

Re-entry · Approved change

เริ่มจาก Change Plan ที่ READY ไม่ใช่เริ่มจาก API documentation

ยืนยัน target model, criteria, fallback, migration/backfill และ rollback ที่คนอนุมัติ จากนั้นแบ่ง implementation เป็น phase ที่ตรวจและย้อนกลับได้

Target model

Book คือ metadata กลาง ส่วน Asset ยังเป็นของผู้ใช้

`Book` เก็บ title, author, normalized ISBN และ provenance ส่วน `Asset` เชื่อม Book กับ Vault Autocomplete ค้น Book ไม่ค้นว่า user คนอื่นมี Asset ใด

User Vault Asset Book metadata

Migration plan

Expand → Backfill → Verify → Contract

เพิ่มโครงใหม่โดยไม่ลบของเดิม, backfill Asset ไปหา Book, ตรวจจำนวน/ความสัมพันธ์, เปลี่ยน code ให้อ่านโครงใหม่ แล้วค่อยพิจารณาลบ column เก่าใน phase หลัง

Prompt · Plan the safe migration

อ่าน approved Data Migration Plan และ schema ปัจจุบัน
เสนอ phases แบบ Expand → Backfill → Verify → Contract
ระบุ migration, data checks, rollback, backups, expected counts และ stop conditions
ห้ามรัน migration หรือลบ column จนกว่าฉันจะอนุมัติแต่ละ phase

ISBN identity

Normalize ก่อน unique และอย่า merge หนังสือแบบเดา

ตกลง ISBN-10/13, punctuation, blank/invalid และ edition boundary พร้อมกฎ conflict เมื่อข้อมูลเดิมสองรายการชี้ไป canonical Book เดียวกัน

External dependency

API response ไม่ใช่ domain model ของเรา

สร้าง adapter แปลง provider response เป็น candidate schema ของ ProudVault เก็บ timeout, rate limit, malformed/missing fields และ provenance ไว้หลัง contract เดียว

Autocomplete UX

Suggestion ยังไม่ใช่ข้อมูลที่บันทึก

Flow คือพิมพ์ title/ISBN → local Book match → API fallback → แสดง candidates → คนเลือก/แก้ → confirm จึงสร้าง Book/Asset

Input Local match API fallback Suggestions Human confirm Persist

Failure is a product state

API ล่มแล้วผู้ใช้ยังเพิ่มหนังสือเองได้

แยก no result, invalid input, timeout, rate limit และ provider error ให้ feedback ที่ไม่ทำให้ผู้ใช้ติด และไม่ retry แบบไร้ขอบเขต

Privacy and quality

Shared catalog ห้ามกลายเป็นช่องดูข้อมูลของคนอื่น

Autocomplete คืน Book metadata เท่านั้น ไม่คืน owner, Vault หรือจำนวน Asset การแก้ shared metadata ต้องมี provenance และ rule ไม่ให้ user หนึ่งทำลายข้อมูลทุกคน

Staging verification

ทดสอบ migration และ API failure ก่อนแตะ production

ใช้ snapshot/test data บน staging ตรวจ old Assets, normalized duplicates, local/API suggestions, manual fallback, cross-user privacy และ regression ของ Search เดิม

Exit Gate

Feature ใหม่ผ่านเมื่อของเก่ายังอยู่และทาง fallback ใช้ได้

ให้ tester คนเดิมลองเพิ่มหนังสือซ้ำ แสดง evidence ของ backfill/rollback, API failure และ Product Plan criteria ก่อน checkpoint

Module checkpoint

สิ่งที่ต้องนำออกจากห้อง

MyShelf milestone

ProudVault ใช้ Book catalog กลางและ autocomplete ได้ โดย Asset เดิมไม่หายและ manual entry ยังทำงาน

Deliverable

Book/Asset migration, API adapter, autocomplete flow, fallback, provenance และ staging regression evidence

Exit gate

Backfill/rollback ซ้อมผ่าน, ISBN ไม่สร้าง Book ซ้ำ, API ล่มแล้วยังเพิ่มเองได้ และ autocomplete ไม่รั่ว ownership