GitLab

สรุปงาน (Summary)

พัฒนาเครื่องมือสคริปต์ scripts/seed-brain-from-vault.ts สำหรับการตรวจสอบ (Dry-Run Audit) และนำเข้าข้อมูลบทเรียนย้อนหลัง 70+ รายการจากคลัง Markdown เดิม (qa-brain/wiki/personal) เข้าสู่ระบบฐานข้อมูลกลางของ Happy QA อย่างปลอดภัย โดยมีกลไกป้องกันการเขียนทับข้อมูลของมนุษย์ (Anti-Overwrite Protection) และกำหนดสถานะเริ่มต้นเป็น DRAFT ทุกรายการ

อ้างอิงข้อกำหนดสถาปัตยกรรม: RFC v4.1 (Section 3.3, 6 Phase 2)

---

ขอบเขตและงานที่ต้องทำ (Scope of Work)

1. Markdown Parsing & Provenance Extraction

• อ่านไฟล์ Markdown ในไดเรกทอรีคลังความรู้เดิม:
  • สกัด YAML Frontmatter หรือหัวข้อหลัก (Title, What happened, Evidence, How to apply, Tags)
  • คำนวณ SHA-256 Checksum ของไฟล์ต้นฉบับ (source_file_checksum)
  • บันทึก Provenance ชัดเจน:
    • source_repo = "QA-Aqua/qa-brain"
    • source_path = <relative/path/to/file.md>
    • channel = 'IMPORT_SEED'
    • actor_user_id = null, machine_key_id = null

2. โหมดการตรวจสอบล่วงหน้า (Dry-Run Audit Mode)

• รันสคริปต์ด้วยตัวเลือก --dry-run:
  • Sanitization Audit: ส่งเนื้อหาทั้งหมดผ่าน Sanitizer Policy v1.0.0 หากพบข้อความที่เสี่ยงเป็น Secret หรือ PII ให้พิมพ์ Log แจ้งเตือนพร้อมระบุชื่อไฟล์และบรรทัด
  • Scope Mapping Verification: ตรวจสอบการจับคู่ Workspace ID และ Project ID ให้ตรงกับโปรเจกต์จริงในระบบ (เช่น โปรเจกต์ AI Employee, โปรเจกต์ Luna, หรือบทเรียนส่วนกลาง)
  • Uniqueness Pre-check: ตรวจสอบความซ้ำซ้อนของ slug และคู่ (sourceRepo, sourcePath)
  • สรุปผลรายงาน Audit Report: จำนวนไฟล์ทั้งหมด, ไฟล์ที่ผ่านเกณฑ์, ไฟล์ที่พบข้อสงสัย, และรายการที่ต้องตรวจสอบเพิ่มเติม

3. โหมดการนำเข้าจริง (Execution Mode with Anti-Overwrite)

• รันสคริปต์ด้วยตัวเลือก --execute:
  • Strict DRAFT Invariant: ทุกรายการที่นำเข้าถูกกำหนด status = 'DRAFT' เสมอ
  • Anti-Overwrite Protection:
    • ค้นหาแถวเดิมด้วย (workspaceId, sourceRepo, sourcePath)
    • หากพบแถวเดิมและมีค่า manuallyModifiedAt != null:
      • ห้ามเขียนทับเด็ดขาด ให้บันทึก Log เตือน MANUALLY_MODIFIED_CONFLICT และข้ามรายการนั้นไป
    • หากเป็นแถวใหม่ หรือแถวเดิมที่ยังไม่เคยมีมนุษย์แก้ไข: ดำเนินการ Insert หรือ Update ตามปกติ

---

เกณฑ์การตรวจรับ (Acceptance Criteria)

• รัน --dry-run สำเร็จโดยไม่เขียนข้อมูลใดๆ ลงฐานข้อมูล พร้อมแสดงตารางสรุปการ Audit
• รัน --execute สามารถนำเข้าบทเรียน 70+ รายการเข้าสู่ฐานข้อมูล Happy QA ได้ครบถ้วน
• ทุกแถวที่นำเข้าผ่าน Seeder มีสถานะเป็น DRAFT และมี Invariant ครบถ้วนตาม SQL Check Constraints
• Anti-Overwrite Test: เมื่อจำลองการอัปเดตฟิลด์ในแถวใดแถวหนึ่งพร้อมตั้งค่า manuallyModifiedAt แล้วรันสคริปต์ซ้ำ ข้อมูลที่มนุษย์แก้ไขต้องไม่ถูกเขียนทับ