6.8 KiB
สรุป 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 App | QNAP | Production system |
| MariaDB | QNAP | Authoritative DB |
| File Storage | QNAP | Primary file store |
| Reverse Proxy | QNAP | Public ingress |
| Ollama | ASUSTOR | AI processing only |
| n8n | ASUSTOR | Automation engine |
| Portainer | ASUSTOR | Container management |
Constraint:
- Ollama MUST NOT run on QNAP
- AI containers MUST NOT access production DB directly
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
- Disable n8n
- Restore DB snapshot
- Restore file snapshot
- Clear staging_ai
- 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 ASUSTOR only
- 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
- Stop public automation
- Disable n8n production workflows
- Clear
/staging_ai - Confirm Ollama healthy
- Confirm DMS API reachable
PHASE 2 — Controlled Batch Migration
Batch size recommendation:
- 20–50 RFAs per batch
Process:
- Copy files to
/staging_ai - Run AI extraction
- Validate JSON
- Push via DMS API
- Log result
- 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:
- Enable n8n automation
- Monitor logs 24h
- Lock legacy system (read-only)
- 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
- Disable n8n
- Restore DB snapshot
- Restore file snapshot
- Clear staging_ai
- 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