# Data Model (Phase 1)
## Entities Overview
| Entity | Purpose | Key Fields | Derived / Notes |
|--------|---------|-----------|-----------------|
| Runbook | 原始操作知識來源 | frontmatter, bodySections[], commandsExtracted | 忽略缺必填的檔案 (invalid) |
| Frontmatter | Metadata 驅動規則 | title, service, component, severity_default, last_verified_at, owner_slack, owner_team, tags?, depends_on?, risk_ops?[], safe_ops?[] | 解析錯誤即記錄 warning |
| Chunk | 檢索單位 | id, runbookPath, headingPath, text, tokens[], score | score 查詢時計算 |
| CommandExtraction | 指令分類 | command, classification (safe|risk), sourcePath, rollbackHint? | 若 risk 無 rollback -> 產生提醒 |
| SeverityRecommendation | 事件嚴重度輸出 | suggested_sev, matched_keywords[], escalation_contacts[] | 規則表 + frontmatter fallback |
| Answer | 回答主體 | summary?, chunks[], risk_ops[], safe_ops[], citations[], warnings[], staleFlag, secondarySources[] | summary 為可選（LLM 模式）|
| HandoffTemplate | 交接輸出 | statusSummary, executedSteps[], residualRisks[], nextActions[] | 來源：使用者上下文 + 分析 |
| PostmortemTemplate | 事後檢討輸出 | overview, impact, timeline[], rootCause?, actionItems[] | timeline 初始空表頭 |
## Field Definitions
### Frontmatter Required Fields
- title: string (1..120)
- service: string (小寫 kebab-case 推薦)
- component: string (kebab / path-like)
- severity_default: enum {SEV1..SEV5}
- last_verified_at: ISO 8601 date string
- owner_slack: string (@或channel 標識)
- owner_team: string (kebab-case team id)
Optional:
- tags: string[]
- depends_on: string[] (其他 runbook 路徑或 service 名)
- risk_ops: string[]
- safe_ops: string[]
### Chunk
- id: `${runbookPath}#${index}`
- headingPath: 'H1 > H2 > ...'
- text: 原始段文字
- tokens: 正規化後 token 陣列（去除停用詞）
- score: 查詢時計算 (0..1)
### CommandExtraction
- command: 原始指令（單行或整理後）
- classification: 'safe' | 'risk'
- rollbackHint: string? （若無→"VERIFY_ROLLBACK_MANUALLY"）
### Answer
- summary: string?（LLM 摘要 or null）
- citations: {path, chunkIndex}[]
- chunks: 已使用 Chunk (subset)
- safe_ops: command[]
- risk_ops: {command, rollbackHint}
- warnings: string[]
- staleFlag: boolean
- secondarySources: path[]
## Relationships
- Runbook 1..* Chunk
- Runbook 0..* CommandExtraction（由 risk_ops + safe_ops + 解析出的 code fences 合併）
- Answer 使用多個 Chunk 與聚合 CommandExtraction
## Validation Rules
- frontmatter 缺任一必填 → invalid（不進索引）
- last_verified_at 無法解析 → warnings + staleFlag=false（僅不做比較）
- risk_ops/safe_ops 來源可能重覆 → 正規化去重 (字串 trim + toLower)
- 指令抽取：忽略空行與 markdown 語法標記行
## State / Process Notes
- Freshness: staleFlag = (now - last_verified_at > thresholdDays)
- Conflict Resolution: 在 answer 組裝階段決定 primary source (不修改 Chunk 狀態)
- Logging classification: ANSWERED | ESCALATE | STALE | ERROR 決定於組裝完成後
## Open Extensions (Not in MVP)
- 指令 rollback 自動推導 (pattern-based)
- depends_on 遞迴拓撲分析產生影響範圍圖
