lcbp3/specs/06-Decision-Records/Patch 1.8.1.md

สรุป 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

---