Operations Runbook

Operations Runbook

1) Startup Checklist

1. ยืนยัน environment variables ของ kobi-web และ backend dependencies ครบ
2. ยืนยันว่า endpoint หลักของ kobi-ai ตอบได้: /api/sessions/start, /api/ai/*, /api/chat/*, /api/maps/*, /api/dashboard/*
3. ยืนยันว่าระบบ auth และ project context โหลดได้ในหน้า /chat
4. ยืนยันว่าอย่างน้อย general และ idea mode boot ได้ตาม preload

2) Smoke Test Matrix

Scenario	Expected
New chat ใน general	session start คืน thread + canonical path แล้ว stream ได้
Deep-link thread ของ mode อื่น	auto-switch mode ถูกต้อง
New chat ใน idea/strategy โดยไม่มี board	เปิด scope picker หรือกัน send
Maps realtime connect	ได้ token + room scope ตรง mapId
Analytics ก่อน setup	chat input ถูก block
Analytics หลัง setup	chat send ได้ตามปกติ
Batch HITL resume	actions state และ workspace converge

3) Runtime Verification Flows

flowchart TB
  A[Open /chat] --> B[create/restore thread]
  B --> C[send first message]
  C --> D{actions required?}
  D -- no --> E[stream done persisted]
  D -- yes --> F[approve/reject batch]
  F --> G[/api/ai/resume]
  G --> H[workspace refresh]

4) 400/403/404 Triage Order

1. ตรวจว่า request ส่ง scope key ที่ถูกกับ mode หรือไม่
2. ตรวจว่าข้อมูล scope ใน URL ตรงกับ thread metadata หรือไม่
3. ตรวจ mapping ใน kobi_scope_threads ว่าสัมพันธ์กับ thread ปัจจุบันหรือไม่
4. ตรวจสิทธิ์ project/share session ว่ายัง valid หรือไม่
5. ตรวจว่า metadata มี field นอก allowlist จนโดน reject หรือไม่
6. ถ้า maps mode เจอ 503 ให้ตรวจว่าโดน map_scope_schema_outdated หรือไม่ (ต้อง apply migration ที่เกี่ยวข้อง)

5) Incident Buckets และแนวทางแก้

Symptom	Root cause ที่พบบ่อย	แนวทาง
stream ค้างไม่จบ	provider done event ไม่สมบูรณ์	ใช้ fallback finalization และ persist summary
ส่งข้อความแล้ว notFound	thread หาย/ไม่ตรง scope	recover thread แล้ว retry message persist
เริ่มแชตใหม่แล้ว fail 503 ใน maps	map thread FK ยังชี้ schema เก่า	apply migration 20260304_align_thread_map_fk_to_kobi_maps.sql
maps ต่อ realtime ไม่ได้	token room mismatch / scope mismatch	ตรวจ mapId และ assertion ใน token route
analytics ส่งไม่ได้	dataset/template ยังไม่พร้อม	ทำ onboarding ให้ครบและเช็ก gate status

6) Recommended Operational Metrics

• ai_stream_error_rate
• scope_mismatch_rate
• hitl_resume_fallback_rate
• maps_realtime_connect_failure_rate
• analytics_gate_block_duration