// File: specs/200-fullstacks/231-hermes-agent/data-model.md
// Change Log:
// - 2026-05-29: Initial data model for Hermes Agent

# Data Model: Hermes Agent

**Feature**: 231-hermes-agent | **Date**: 2026-05-29

> **Important**: Hermes ไม่เพิ่มหรือแก้ DMS production schema ทุกกรณี (ADR-031, FR-017)
> Data model นี้ทั้งหมดอยู่ใน **Hermes-owned storage** (SQLite / container volume) ไม่ใช่ DMS MariaDB

---

## 1. HermesOperationsLog (SQLite table: `hermes_operations_log`)

บันทึก inbound/outbound DevOps operations ทุก transaction ของ Hermes

| Field | Type | Constraints | Description |
|-------|------|-------------|-------------|
| `id` | TEXT (UUIDv7) | PRIMARY KEY | Transaction ID — ใช้ UUIDv7 ตาม ADR-019 |
| `operator_identity` | TEXT | NOT NULL | Telegram user ID หรือ CLI session identity |
| `command_type` | TEXT | NOT NULL | เช่น `TELEGRAM_INBOUND`, `TELEGRAM_OUTBOUND`, `ORCHESTRATION_TASK`, `GIT_WRITE` |
| `target_system` | TEXT | NOT NULL | เช่น `TELEGRAM`, `GITEA`, `CLOUD_AI`, `DEV_QDRANT` |
| `command_summary` | TEXT | NOT NULL | Redacted command description (ห้ามมี secret/token/sensitive path) |
| `status` | TEXT | NOT NULL | `PENDING` / `IN_PROGRESS` / `COMPLETED` / `FAILED` / `REJECTED` |
| `created_at` | DATETIME | NOT NULL DEFAULT CURRENT_TIMESTAMP | |
| `completed_at` | DATETIME | NULLABLE | |
| `error_classification` | TEXT | NULLABLE | เช่น `AUTH_FAILURE`, `RATE_LIMIT`, `FORBIDDEN_ACTION`, `EXTERNAL_API_ERROR` |
| `gitea_token_identity` | TEXT | NULLABLE | Token scope/identity สำหรับ Git write actions (ไม่ใช่ token value) |
| `target_repo` | TEXT | NULLABLE | สำหรับ Git write actions |
| `target_branch` | TEXT | NULLABLE | สำหรับ Git write actions |

**Retention**: 90 วัน แล้ว archive/delete ตาม DevOps log policy
**Access**: Read เฉพาะ admin/operator ที่จำเป็น
**Redaction**: `command_summary` ต้องผ่าน secret scanner ก่อน insert

---

## 2. HermesRateLimitState (Redis key pattern)

| Key Pattern | Value | TTL | Description |
|-------------|-------|-----|-------------|
| `hermes:telegram:{telegramUserId}` | INT (request count) | 60s | Rate limit counter per user; expire ทุก 60 วินาที |

---

## 3. HermesBullMQJobs (Redis via `hermes-notification-queue`)

### Job: `telegram-devops-outbound`

| Field | Type | Description |
|-------|------|-------------|
| `transactionId` | string (UUIDv7) | Reference ID for tracking |
| `chatId` | string | Telegram chat ID |
| `message` | string | Outbound message text (ไม่มี secret/PII) |
| `retryCount` | number | Current retry count (max 3) |

---

## 4. HermesOrchestrationTask (Redis via `hermes-orchestration-queue`)

### Job: `orchestration-task`

| Field | Type | Description |
|-------|------|-------------|
| `taskId` | string (UUIDv7) | Task tracking ID |
| `taskType` | `DEVOPS` / `DMS_FEATURE` / `SCHEMA_DB` / `BUG_FIX` | กำหนด context loading strategy |
| `description` | string | Task description (no production data) |
| `contextSources` | string[] | Context files to load |
| `maxIterations` | number | Self-correction loop limit (default: 3) |
| `telegramChatId` | string | สำหรับ progress/result notification |
| `createdAt` | string (ISO 8601) | |

---

## 5. SOUL.md (Container File: `/volume1/docker/hermes/SOUL.md`)

ไม่ใช่ DB table แต่เป็น plain Markdown file working journal ใน container volume

**Structure per session entry**:
```markdown
## Session {ISO_DATETIME}
Task: {task description}
TaskType: {DEVOPS|DMS_FEATURE|SCHEMA_DB|BUG_FIX}
Context loaded: {comma-separated context files}
Sub-agents delegated: {count} code generation calls
Iterations: {count} ({result of last iteration})
PR created: {branch} → #{pr_number}
Status: {DONE|ESCALATED|FAILED}
```

**File management**:
- Read at session start for context resumption
- Append only (never overwrite previous entries)
- Rotate (clear and archive) every 30 days or manual clear
- Never synced to repo — container volume only

---

## 6. DevQdrantCollection (`lcbp3_code_chunks` on ASUSTOR:6334)

| Field | Type | Description |
|-------|------|-------------|
| `id` | string (UUID) | Chunk ID |
| `repoName` | string | Repository name (e.g., `lcbp3`) |
| `moduleName` | string | Module path (e.g., `backend/src/modules/correspondence`) |
| `filePath` | string | Relative file path |
| `chunkIndex` | number | Chunk position in file |
| `content` | string | Code chunk text |
| `vector` | float[] | nomic-embed-text embedding (768 dimensions) |

> **ไม่ใช้ `projectPublicId` filter** (ซึ่งเป็น DMS document isolation key) — ใช้ `repoName` + `moduleName` แทน ตาม ADR-031 v2.0

---

## Entity Relationships

```
HermesAgent
  ├── orchestrates → HermesOrchestrationTask (via hermes-orchestration-queue)
  │     ├── delegates → HermesSubAgent (Cloud AI: Claude Haiku / GPT-4o-mini)
  │     ├── searches → DevQdrantCollection (code patterns)
  │     └── records → SOUL.md (session journal)
  └── bridges → HermesTelegramGateway
        ├── validates → HermesRateLimitState (Redis)
        ├── records → HermesOperationsLog (SQLite)
        └── dispatches → HermesBullMQJobs (hermes-notification-queue)
              └── sends → Telegram API
```

---

## State Transitions: HermesOperationsLog.status

```
PENDING → IN_PROGRESS → COMPLETED
                      → FAILED
         → REJECTED (allowlist/rate-limit/forbidden-action check)
```

## State Transitions: HermesOrchestrationTask

```
QUEUED → CONTEXT_LOADING → SUB_AGENT_DELEGATED
                         → SELF_CORRECTION (max 3 iterations)
                         → PR_CREATED → DONE
                         → ESCALATED (>3 iterations, notify Developer)
                         → FAILED
```