## สรุป Patch 1.8.1

# 📘 1) Formal Spec — Version 1.8.1

**Document ID:** DMS-SPEC-1.8.1
**Status:** Approved for Implementation
**Supersedes:** 1.8.0
**Effective Date:** 2026-02-26

---

## 1. Purpose

Spec 1.8.1 แก้ความไม่สอดคล้องระหว่าง:

- 03-04-legacy-data-migration.md
- 03-05-n8n-migration-setup-guide.md
- ADR-017-ollama-data-migration.md

และกำหนด Production Boundary ที่ชัดเจน

---

## 2. Authoritative Architecture (Binding)

### Infrastructure Layout

| Component           | Host          | Responsibility                                    |
| ------------------- | ------------- | ------------------------------------------------- |
| DMS Frontend        | QNAP          | Production UI                                     |
| DMS Backend         | QNAP          | Core API                                          |
| MariaDB             | QNAP          | Authoritative DB                                  |
| Redis               | QNAP          | Cache / BullMQ                                    |
| Elasticsearch       | QNAP          | Full-text Search                                  |
| Nginx Proxy Manager | QNAP          | Public ingress / SSL                              |
| n8n + n8n-db        | QNAP          | Automation engine                                 |
| Tika                | QNAP          | OCR / PDF extraction                              |
| Gitea               | QNAP          | Git + CI/CD                                       |
| RocketChat          | QNAP          | Team communication                                |
| Grafana             | ASUSTOR       | Metrics dashboard                                 |
| Prometheus          | ASUSTOR       | Metrics collection                                |
| Loki                | ASUSTOR       | Log aggregation                                   |
| Promtail            | ASUSTOR       | Log shipper                                       |
| uptime-kuma         | ASUSTOR       | Service availability                              |
| Gitea Runner        | ASUSTOR       | CI/CD build agent                                 |
| Docker Registry     | ASUSTOR       | Image storage                                     |
| Cloudflared         | ASUSTOR       | Tunnel / remote access                            |
| Ollama              | Admin Desktop | AI processing only (i9-9900K, RTX 2060 SUPER 8GB) |

**Constraints:**

- Ollama MUST NOT run on QNAP (production server)
- AI containers MUST NOT access production DB directly
- n8n calls Ollama via internal VLAN HTTP only

---

## 3. Source of Truth Definition

During Migration:

| Data Type    | Authority                               |
| ------------ | --------------------------------------- |
| File content | Legacy file server                      |
| RFA metadata | Gmail notification                      |
| Assignment   | Circulation sheet                       |
| DMS DB       | NOT authoritative until validation pass |

---

## 4. Metadata Mapping Contract (Mandatory)

| Legacy        | DMS           | Required | Rule              |
| ------------- | ------------- | -------- | ----------------- |
| RFA No        | rfa_number    | YES      | UNIQUE            |
| Title         | title         | YES      | NOT NULL          |
| Issue Date    | issue_date    | YES      | Valid date        |
| Revision      | revision_code | YES      | Pattern validated |
| Assigned User | user_id       | YES      | FK must exist     |
| File Path     | file_path     | YES      | File must exist   |

Migration MUST fail if required fields invalid.

---

## 5. Idempotent Execution Requirement

Automation must:

- Check existence by rfa_number
- Validate file hash
- UPDATE instead of INSERT if exists
- Prevent duplicate revision chain

---

## 6. Folder Standard

```
/data/dms/
 ├── uploads/YYYY/MM/
 ├── staging_ai/
 ├── migration_logs/
 └── archive_legacy/
```

---

## 7. File Naming Standard

```
{RFA_NO}_{REV}_{YYYYMMDD}.pdf
```

Example:

```
RFA-2026-001_A_20260225.pdf
```

---

## 8. Logging Standard

| System           | Required       |
| ---------------- | -------------- |
| Migration script | structured log |
| n8n              | execution log  |
| Ollama           | inference log  |
| DMS              | audit_log      |

Retention: 90 days minimum.

---

## 9. Dry Run Policy

All migrations MUST run with:

```
--dry-run
```

No DB commit until validation approved.

---

## 10. Rollback Strategy

1. Disable n8n
2. Restore DB snapshot
3. Restore file snapshot
4. Clear staging_ai
5. Re-run validation

---

---

# 📄 2) ADR-018 — AI Boundary Hardening

**Title:** AI Isolation & Production Boundary Enforcement
**Status:** Accepted
**Date:** 2026-02-26
**Supersedes:** Clarifies ADR-017

---

## Context

AI-based migration using Ollama introduces:

- DB corruption risk
- Hallucinated metadata
- Unauthorized modification
- Privilege escalation risk

Production DMS must remain authoritative.

---

## Decision

### 1. AI Isolation Model

Ollama must:

- Run on **Admin Desktop only** (NOT on QNAP)
- Have NO DB credentials
- Have NO write access to uploads
- Access only `/staging_ai`
- Output JSON only

---

### 2. Data Flow Model

```
Legacy File → staging_ai → Ollama → JSON
             ↓
        Validation Script
             ↓
         DMS API (write)
```

AI never writes directly.

---

### 3. API Gatekeeping

All writes must go through:

- Authenticated DMS API
- RBAC enforced
- Audit log recorded

---

### 4. Hallucination Mitigation

AI output must:

- Match schema
- Pass validation script
- Fail on missing required fields
- Reject unknown users

---

### 5. Security Controls

| Risk               | Control            |
| ------------------ | ------------------ |
| DB corruption      | No DB access       |
| File overwrite     | Read-only mount    |
| Public AI exposure | No exposed port    |
| Data leak          | Internal VLAN only |

---

## Consequences

Pros:

- Production safe
- Predictable migration
- Audit trail preserved

Cons:

- Slightly slower pipeline
- Requires validation layer

---

---

# 🧠 3) Full Migration Runbook

**Production Execution Guide**

---

# PHASE 0 — Pre-Run Validation

☐ Full DB backup
☐ File storage snapshot
☐ Restore test verified
☐ 10-sample manual compare
☐ Dry-run executed
☐ Dry-run report approved

---

# PHASE 1 — Environment Preparation

1. Stop public automation
2. Disable n8n production workflows
3. Clear `/staging_ai`
4. Confirm Ollama healthy
5. Confirm DMS API reachable

---

# PHASE 2 — Controlled Batch Migration

Batch size recommendation:

- 20–50 RFAs per batch

Process:

1. Copy files to `/staging_ai`
2. Run AI extraction
3. Validate JSON
4. Push via DMS API
5. Log result
6. Manual sample verify (10%)

---

# PHASE 3 — Post-Batch Validation

After each batch:

☐ Record count match
☐ File open test
☐ Revision chain correct
☐ Assignment correct
☐ No duplicate rfa_number

If fail → STOP and rollback.

---

# PHASE 4 — Cutover

When all batches pass:

1. Enable n8n automation
2. Monitor logs 24h
3. Lock legacy system (read-only)
4. Final backup snapshot

---

# PHASE 5 — Post-Go-Live Monitoring (72 hours)

Monitor:

- DB errors
- Duplicate insert
- Missing files
- AI extraction errors
- API error rate

If anomaly >5% → trigger rollback plan.

---

# 🚨 Emergency Rollback Procedure

1. Disable n8n
2. Restore DB snapshot
3. Restore file snapshot
4. Clear staging_ai
5. Reconcile delta manually

Target RTO: < 2 hours

---

# 📊 Risk Matrix (Condensed)

| Risk             | Probability | Impact   | Mitigation        |
| ---------------- | ----------- | -------- | ----------------- |
| Duplicate RFA    | Medium      | High     | Idempotent check  |
| Wrong assignment | Medium      | Medium   | Validation rule   |
| AI hallucination | Medium      | High     | Schema validation |
| Storage mismatch | Low         | High     | File hash verify  |
| DB corruption    | Low         | Critical | No AI DB access   |

---

# 🏁 Production Readiness Criteria

System may go live only if:

- All dry-run tests pass
- 100% required fields valid
- 0 duplicate RFA
- Sample QA pass >95%
- Backup verified

---

---

# 🎯 Final Result

ตอนนี้เอกสารทั้งชุด:

✔ Architecture consistent
✔ AI boundary hardened
✔ Migration deterministic
✔ Rollback defined
✔ Production-safe

---
