# Indexing Workflow สำหรับ Second Brain

ใช้กำหนดวิธีรับข้อมูล เตรียมค้น อัปเดต และตรวจความถูกต้อง เป็น template ของ pipeline ไม่ใช่ script ที่รัน indexing ให้แล้ว

## 1 เลือกสิ่งที่ต้องใช้

| ส่วน | หน้าที่ | ใช้เมื่อ |
|---|---|---|
| Knowledge index | แผนที่และเส้นทางอ่าน เช่น index.md | ให้ agent เริ่มอ่านและเลือกหมวด |
| File search | ค้นตรงในไฟล์ ไม่ต้องมี search database แยก | คลังเล็กหรือค้นชื่อ/คำตรง |
| Keyword index | เตรียมโครงสร้างค้นคำและจัดอันดับ | ต้องค้นข้อความและชื่อเฉพาะ |
| Vector index | เก็บ embeddings เพื่อค้นความหมายใกล้เคียง | คำถามและเอกสารใช้ถ้อยคำต่างกัน |
| Graph index | เก็บความสัมพันธ์ที่ระบุได้ระหว่างรายการ | ต้องตามเชื่อม service, decision หรือ incident |

ไม่ต้องสร้างทุกแบบ ให้เลือกจาก workload และผลทดลอง Graph view ของลิงก์กับ graph retrieval สำหรับ agent ต้องตรวจความสามารถจริงแยกกัน

## 2 กำหนด pipeline

- Corpus และ source of truth: {{paths / APIs}}
- Search backend และรุ่น: {{ชื่อ / file search only}}
- ผู้ดูแล: {{owner}}
- รายการที่เข้า search ได้: {{เช่น published และ access ที่อนุญาต}}
- สิ่งที่ต้องไม่เข้า default search: {{draft, review, examples, superseded ตามนโยบาย}}
- ขอบเขตผู้ค้น: {{user / team / project พร้อมวิธีตรวจ}}
- Trigger: {{publish event / file change / scheduled reconciliation}}
- ระยะเวลาที่ต้อง searchable: {{เป้าหมาย}}

## 3 Dataflow

```mermaid
flowchart TD
    S[เอกสารต้นทางและ Markdown ที่ผ่านตรวจ] --> V[ตรวจ schema, status และสิทธิ์]
    V --> N[แยกเนื้อหาและ normalize]
    N --> C[แบ่งตามหัวข้อ พร้อม metadata และ source revision]
    C --> K[Keyword index ถ้าใช้]
    C --> E[Embedding และ vector index ถ้าใช้]
    N --> G[Entity และ relation index ถ้าใช้]
    K --> T[ตรวจ retrieval และความครบถ้วน]
    E --> T
    G --> T
    T -->|ผ่าน| R[พร้อมให้ค้น revision ใหม่]
    T -->|ไม่ผ่าน| F[บันทึก failure และจำกัดข้อมูลที่ใช้]
    Q[คำถามและ scope ของ agent] --> A[ตรวจสิทธิ์และเลือก index]
    A --> R
    R --> O[ผลค้นพร้อม ID, ที่มา และ revision]
    O --> D[เปิดหน้าหรือหลักฐานเต็มก่อนใช้]
```

Filter ตามสิทธิ์ต้องใช้กับทุกช่องทางค้น รวมชื่อ snippet และ cache ไม่ควรส่งข้อมูลที่ไม่มีสิทธิ์ไปให้ agent แล้วหวังให้ agent กรองเอง

## 4 Document และ chunk metadata

| Field | ใช้ทำอะไร |
|---|---|
| document_id | ID คงที่ของรายการ ไม่ผูกกับ path อย่างเดียว |
| source_path / source_url | เปิดกลับไปยังต้นทาง |
| revision / content_hash | ตรวจว่าค้นเจอเนื้อหาฉบับไหน |
| type / status / scope / access | แยกประเภท สถานะและสิทธิ์ |
| owner / last_verified | ระบุผู้ดูแลและเวลาตรวจเนื้อหา |
| indexed_at | เวลาที่นำฉบับนี้เข้าสู่ search ไม่ใช่เวลายืนยันความรู้ |
| chunk_id / heading_path | ระบุตำแหน่งข้อความและคืนบริบท |
| pipeline_version | รุ่นของ parser, chunking และ extraction |
| embedding_model | ใช้เมื่อมี vector index เพื่อแยกรุ่นที่เข้ากันได้ |

เก็บ mapping จาก document_id ไปยัง chunks/relations ทั้งหมด เพื่อให้ลบหรือแทนที่ได้ครบ ชื่อ field ต้องแปลงให้ตรง backend จริง

## 5 กติกาแบ่งเนื้อหา

- วิธีแบ่ง: {{ตามหัวข้อ / ทั้งเอกสารสั้น / อื่น ๆ}}
- ขนาดเป้าหมายและหน่วย: {{tokens หรือ characters}}
- Overlap: {{จำนวนและเหตุผล / ไม่มี}}
- ตารางและ code blocks: {{วิธีรักษาความหมาย}}
- Metadata ที่แนบแต่ละ chunk: {{title, scope, revision, heading}}
- วิธีเปิด parent document: {{lookup หรือ tool}}

อย่าแยกข้อความออกจากเงื่อนไขสำคัญ เช่น ขอบเขต environment หรือข้อยกเว้น ทดสอบขนาด chunk กับคำถามจริง ไม่มีขนาดเดียวที่เหมาะกับทุก corpus

## 6 เพิ่ม แก้ ย้าย ลบ และเปลี่ยนสิทธิ์

| เหตุการณ์ | การจัดการ |
|---|---|
| เพิ่ม | ตรวจ metadata แล้วสร้าง records ของ revision ใหม่ |
| แก้เนื้อหา | เทียบ hash สร้าง chunks ใหม่ และเอา records เก่าออกจาก current retrieval |
| เปลี่ยน metadata | อัปเดต filters/relations; ไม่ต้อง embed ใหม่หาก input ไม่เปลี่ยน |
| ย้ายไฟล์ | คง document_id แก้ path และ references |
| Superseded | ชี้ฉบับใหม่และกันฉบับเก่าจาก current search ตามนโยบาย |
| ลบหรือถอนสิทธิ์ | กัน retrieval ทันที แล้วลบ index records, graph edges และ caches ที่เกี่ยวข้อง |
| เปลี่ยน pipeline/model | rebuild หรือ migrate ไป index รุ่นใหม่ ตรวจแล้วจึงสลับใช้งาน |

การเปลี่ยน embedding model ต้องสร้าง vectors ให้เข้ากันกับรุ่นที่ query ใช้ ห้ามผสมโดยไม่ตรวจรองรับ หาก hash ครอบคลุมเฉพาะเนื้อหา ให้ตรวจการเปลี่ยน metadata/สิทธิ์แยกด้วย

## 7 ความทนทานและสถานะ

- Idempotency: {{key จาก document_id + revision + pipeline_version}}
- Retry และ failure log: {{วิธีและที่เก็บ}}
- วิธีสลับ revision: {{atomic switch หรือ backend-specific approach}}
- การ reconcile: {{เทียบเอกสารที่ควร index กับ records จริงอย่างไร}}
- Rollback: {{กลับ index รุ่นก่อนที่ยัง valid อย่างไร}}

Content status กับ indexing state เป็นคนละเรื่อง:

- Content: draft / review / published / superseded / archived
- Indexing: pending / ready / failed

Published แต่ pending หมายถึงเนื้อหาผ่านแล้ว แต่ search ยังไม่พร้อม หาก indexing ล้มเหลว อย่าให้ฉบับเก่าที่ถูกเพิกถอนกลับมาใช้ การ rollback ไม่ยกเลิกสิทธิ์ล่าสุดหรือการลบข้อมูล

## 8 ตรวจว่าค้นได้ถูกต้อง

| กรณี | ผลที่ต้องได้ | ผลจริง |
|---|---|---|
| ค้นชื่อหรือ ID ตรง | พบเอกสารที่ถูกต้อง | {{ผล}} |
| ค้น alias ไทย/อังกฤษ | พบหน้าที่เกี่ยวข้อง | {{ผล}} |
| ถามด้วยถ้อยคำอื่น | พบหลักฐานที่ใช้ตอบได้ | {{ผล}} |
| เอกสารแก้แล้ว | ได้ revision ใหม่ ไม่มี chunk เก่าค้าง | {{ผล}} |
| เอกสารถูกลบ/ถอนสิทธิ์ | ไม่ได้เนื้อหา ชื่อ snippet หรือ cache ที่ไม่ควรเห็น | {{ผล}} |
| Draft และตัวอย่าง | ไม่ปะปนในผลที่รับรองแล้ว | {{ผล}} |
| ไม่มีหลักฐาน | ไม่คืนข้อมูลอื่นราวกับเป็นคำตอบที่ยืนยัน | {{ผล}} |

## 9 บันทึกการรัน

- Run ID และเวลา: {{ค่า}}
- Source snapshot: {{revision}}
- Pipeline และ model version: {{ค่า}}
- Expected / indexed / skipped / failed documents: {{จำนวนและเหตุผล}}
- Removed records: {{จำนวน}}
- Retrieval verification: {{ผล + logs}}
- Indexing state: {{pending / ready / failed}}
- งานค้างและผู้ดูแล: {{รายละเอียด / ไม่มี}}

ใช้ร่วมกับ Publication checklist การทดสอบ search ต้องตรวจทั้งพบข้อมูลที่ควรพบและไม่พบข้อมูลที่ไม่ควรเห็น