GitLab

สรุปงาน (Summary)

ปิดช่องว่างสถาปัตยกรรมและปรับสัญญาความถูกต้อง (Coverage Closure & Contract Alignment) ตามข้อเสนอแนะในการตรวจรับรอง RFC v4.1 ครอบคลุม 6 กลุ่มสำคัญ:

1. การระบุ Canonical RFC v4.1 ฉบับสมบูรณ์ใน Tracker
2. การผูกระบบ Immutable Audit Trail (qa_audit_event และ QA_WORKSPACE_EVENT_FAMILIES)
3. การบังคับใช้ Pre-Ingress Sanitizer บนทุก Write Path (รวมทั้ง Edit และ Web Quick Entry Create)
4. การตรวจสอบ Typed Evidence (RUN_RESULT), ระบบ Duplicate Advisory และการค้นหาผ่าน evidenceRef
5. การแก้ไข Contract ที่ขัดกัน (Fingerprint บน Sanitized Payload, สิทธิ์ Promotion เฉพาะ Workspace Lead/Admin, และการรองรับ includeDeprecated)
6. การเพิ่มมิติ Authorship (authorType, agentName, agentVersion)

อ้างอิงข้อกำหนดสถาปัตยกรรม: RFC v4.1 (Sections 2–5, 8, 10)

---

รายละเอียดงานที่ต้องดำเนินการ (Specification Breakdown)

กลุ่มที่ 1: Traceability & Canonical RFC v4.1 Reference

• บันทึกและแนบข้อกำหนดฉบับสมบูรณ์ RFC v4.1 ลงใน Tracker Issue (#10) เพื่อให้ทีมและ AI Agent ทุกตัวสามารถตรวจสอบย้อนกลับ (Traceability) ได้ 100% โดยไม่ต้องพึ่งพาไฟล์ท้องถิ่นในเครื่อง

กลุ่มที่ 2: Immutable Audit Trail Integration (qa_audit_event)

• การขยาย Event Family ระดับเวิร์กสเปซ:
  • เพิ่ม "brain" ลงใน QA_WORKSPACE_EVENT_FAMILIES ใน packages/qa-data/src/event-log.ts
  • ปรับปรุง SQL CHECK Constraint qa_audit_event_workspace_level_check และ qa_activity_event_workspace_level_check ใน Migration เพื่อยอมรับ starts_with("operation", 'brain.') เมื่อ project_id IS NULL
• การบันทึก Audit ผ่าน appendAudit:
  • ทุกการเปลี่ยนแปลงสถานะ Gotcha (brain.record_gotcha, brain.edit_gotcha, brain.verify_gotcha, brain.deprecate_gotcha, brain.promote_gotcha) ต้องเรียกใช้ appendAudit(tx, ctx, ...) โดยมี subjectType = "QA_BRAIN_GOTCHA", subjectId = gotcha.id
  • ตรวจสอบ Hash Chain ความถูกต้องผ่าน verifyAuditChainRows เพื่อรับประกัน Append-Only Guarantee

กลุ่มที่ 3: Sanitization บนทุก Write Path (All Mutation Endpoints)

• Edit Path Sanitization:
  • ปรับปรุงคำสั่ง POST /api/v1/workspaces/:wsId/brain/:gotchaId/edit ให้ส่งข้อมูลใหม่ผ่าน Sanitizer Policy v1.0.0 ก่อนนำไปบันทึกลงใน QaBrainRevision และอัปเดต QaBrainGotcha
• Web Create Backend Contract:
  • กำหนดและพัฒนา Endpoint POST /api/v1/workspaces/:wsId/brain/create สำหรับ Web UI Quick Entry
  • กำหนด channel = 'WEB_UI', actorUserId = user.id, authorType = 'HUMAN'
  • บังคับรัน Sanitizer Policy v1.0.0 และ Atomic Idempotency เช่นเดียวกับช่องทาง MCP

กลุ่มที่ 4: Typed Evidence, Duplicate Advisory & Search Enhancement

• Typed Evidence Validation (RUN_RESULT):
  • เมื่อ evidenceType === 'RUN_RESULT': ตรวจสอบว่า evidenceRef อ้างอิง ID ของ QaTestRun ที่มีอยู่จริงภายใต้ workspaceId และ projectId เดียวกันที่ผู้เรียกมีสิทธิ์ หากไม่อยู่ในขอบเขต ให้ปฏิเสธด้วย VALIDATION_FAILED (ป้องกันการอ้างอิงข้ามโปรเจกต์)
• Duplicate Advisory Service:
  • ในระหว่างการบันทึก Gotcha (record_gotcha / create): ดำเนินการสแกนหา Gotcha ที่อาจซ้ำซ้อนภายในขอบเขตสิทธิ์ของผู้เรียก (Tag ชนกัน หรือ Keyword ใกล้เคียงกันในโปรเจกต์เดียวกันหรือ Workspace)
  • ส่งคืนข้อความเตือนใน advisoryWarnings: string[]
  • Authorization Isolation: ห้ามสแกนหรือคายหัวข้อ/ID ของ Gotcha จากโปรเจกต์อื่นที่ผู้เรียกไม่มีสิทธิ์เด็ดขาด
• ค้นหาผ่าน evidenceRef:
  • เพิ่ม evidenceRef เข้าไปในเงื่อนไขการค้นหา Case-Insensitive Substring Baseline (ILIKE) ใน Query Service (T4) และ MCP happyqa_brain_query (T6)

กลุ่มที่ 5: การปรับปรุง Contract ที่ขัดกัน (Contract Reconciliation)

• Request Fingerprint Definition:
  • ยืนยันสูตรคำนวณ requestFingerprint จาก Sanitized Payload (Canonical Sanitized Payload Hash) เพื่อให้การ Mask ข้อมูลความลับหรือการจัดเรียงคีย์ไม่มีผลทำให้ Fingerprint เพี้ยน
• Promotion Role Alignment ใน UI:
  • ปรับข้อกำหนดหน้าจอ UI (T7) ให้ปุ่มและ Modal "Promote to Workspace" แสดงผลและทำงานได้เฉพาะผู้ใช้ที่มีบทบาท WORKSPACE_QA_LEAD หรือ WORKSPACE_ADMIN เท่านั้น (สอดคล้องกับ T5)
• รองรับ includeDeprecated ใน Query:
  • เพิ่มพารามิเตอร์ includeDeprecated: boolean (default: false) ใน Input Schema ของ T4 Query Service และ T6 happyqa_brain_query เพื่อให้ Web UI แท็บ "Deprecated" สามารถดึงข้อมูลมาแสดงผลได้จริง

กลุ่มที่ 6: Authorship Dimension (authorType, agentName, agentVersion)

• แยกมิติ Authorship (ผู้สร้างเนื้อหาทางปัญญา) ออกจาก Accountability (ผู้ถือ Token ที่ยิงคำขอ):
  • เพิ่ม Enum QaBrainAuthorType (HUMAN, AGENT, UNKNOWN)
  • เพิ่มฟิลด์ authorType, agentName?, agentVersion? ในโมเดล QaBrainGotcha และ QaBrainRevision
  • รองรับการระบุ Agent Attribution (เช่น "agentName": "claude-code", "agentVersion": "1.0.0") ในคำขอบันทึกบทเรียน

---

ลำดับการขึ้นต่อกัน (Dependency Graph)

T1 (Schema & DB Constraints)
  └── T2 (Sanitizer Policy v1.0.0)
        ├── T3 (Atomic Idempotency)
        ├── T4 (Query Service Baseline)
        └── T5 (CAS Web Domain Commands)
              ├── T6 (MCP Tool Expansion)
              └── T7 (Web UI & Verification Dashboard)
  └── T8 (Historical Vault Seeder)
  └── T9 (Security, Concurrency & Persona Test Suite)
  └── T10 (Coverage Closure & Contract Alignment — Verifies T1-T9 against RFC v4.1)

---

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

• สัญญาณ Audit Trail ทำงานสมบูรณ์: ทุกการ Create, Edit, Verify, Deprecate, Promote มีการบันทึกลง qa_audit_event ด้วยโซ่ Hash ที่ตรวจสอบได้ผ่าน verifyAuditChainRows
• ปราศจากช่องโหว่ Raw Secret/PII: ทดสอบยิง Payload มี Secret ผ่าน Web Edit และ Web Create ต้องถูก Mask ทั้งหมดก่อนลง DB
• ทดสอบส่ง evidenceType = RUN_RESULT ด้วย Run ID ของโปรเจกต์อื่น ระบบต้องปฏิเสธด้วย VALIDATION_FAILED
• Duplicate Advisory ไม่รั่วไหล: ทดสอบบันทึก Gotcha ในโปรเจกต์ A ด้วยคีย์เวิร์ดเดียวกับ Gotcha ในโปรเจกต์ B ระบบต้องไม่ส่งชื่อบทเรียนของโปรเจกต์ B มาใน advisoryWarnings
• การค้นหาผ่าน Query Service และ MCP สามารถสืบค้นข้อความใน evidenceRef และเรียกดู includeDeprecated ได้ถูกต้อง