diff --git a/.agents/README.md b/.agents/README.md index 22ae7cb..d674170 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -2,7 +2,7 @@ > **The Event Horizon of Software Quality.** > _Adapted for Google Antigravity IDE from [github/spec-kit](https://github.com/github/spec-kit)._ -> _Version: 1.1.0_ +> _Version: 1.2.0 — LCBP3-DMS Edition (v1.8.1 UAT Ready)_ --- @@ -254,4 +254,50 @@ If you change your mind mid-project: --- +## 🏗️ LCBP3-DMS Project Notes (v1.8.1) + +### 📊 Current Status: UAT Ready (2026-03-11) + +| Area | Status | +|------|--------| +| Backend | ✅ 18 Modules, Production Ready | +| Frontend | ✅ 100% Complete | +| Database | ✅ Schema v1.8.0 Stable | +| Documentation | ✅ **10/10 Gaps Closed** | +| AI Migration | 🔄 Pre-migration Setup (n8n + Ollama) | +| UAT | 🔄 In Progress | +| Deployment | 📋 Pending Go-Live | + +### 📁 Key Spec Files (Always Check Before Writing Code) + +| เอกสาร | Path | ใช้เมื่อ | +|--------|------|--------| +| Schema Tables | `specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql` | ก่อนเขียน Query | +| Data Dictionary | `specs/03-Data-and-Storage/03-01-data-dictionary.md` | ตรวจ Business Rules | +| Edge Cases | `specs/01-Requirements/01-06-edge-cases-and-rules.md` | 37 Rules | +| Migration Scope | `specs/03-Data-and-Storage/03-06-migration-business-scope.md` | Migration Bot | +| Release Policy | `specs/04-Infrastructure-OPS/04-08-release-management-policy.md` | ก่อน Deploy | +| UAT Criteria | `specs/01-Requirements/01-05-acceptance-criteria.md` | ตรวจ Feature | + +### ⚡ Project-Specific Workflow Cheatsheet + +| Task | Workflow / Command | Notes | +|------|--------------------|-------| +| Create Backend Module | `/create-backend-module` | Scaffolds NestJS module | +| Create Frontend Page | `/create-frontend-page` | Next.js App Router page | +| Schema Change | `/schema-change` | ADR-009: No migrations | +| Deploy | `/deploy` | Blue-Green via Gitea CI/CD | +| UAT Feature Check | `/11-speckit.validate` | vs `01-05-acceptance-criteria.md` | +| Security Audit | `@speckit.security-audit` | OWASP + CASL + ClamAV | + +### 🚫 Critical Forbidden Actions + +- ❌ DO NOT bypass Release Gates before deploying — `04-08-release-management-policy.md` +- ❌ DO NOT start Migration without Gate #1 approval — `03-06-migration-business-scope.md` +- ❌ DO NOT use TypeORM Migrations — modify schema SQL directly (ADR-009) +- ❌ DO NOT give Ollama direct DB access — all writes via DMS API (ADR-018) +- ❌ DO NOT use `any` TypeScript type anywhere + +--- + _Built with logic from [Spec-Kit](https://github.com/github/spec-kit). Powered by Antigravity._ diff --git a/.gemini/GEMINI.md b/.gemini/GEMINI.md index b4ff5a0..7820eaa 100644 --- a/.gemini/GEMINI.md +++ b/.gemini/GEMINI.md @@ -12,14 +12,27 @@ You value **Data Integrity**, **Security**, and **Clean Architecture**. ## 🏗️ Project Overview -**LCBP3-DMS (Laem Chabang Port Phase 3 - Document Management System)** — Version 1.8.0 (Patch 1.8.1) +**LCBP3-DMS (Laem Chabang Port Phase 3 - Document Management System)** — Version 1.8.1 (Patch) + +### 📊 Project Status: UAT Ready (2026-03-11) + +| Area | Status | Notes | +|------|--------|-------| +| Backend | ✅ Production Ready | 18 Modules, ADR-018 AI Isolation | +| Frontend | ✅ 100% Complete | App Router, TanStack Query, Zustand | +| Database | ✅ Schema v1.8.0 Stable | MariaDB 11.8, No-migration (ADR-009) | +| Documentation | ✅ **10/10 Gaps Closed** | Product Vision → Release Policy | +| AI Migration | 🔄 Pre-migration Setup | n8n + Ollama (ADR-017/018) | +| Testing | 🔄 UAT In Progress | Per `01-05-acceptance-criteria.md` | +| Deployment | 📋 Pending Go-Live | Blue-Green, QNAP Container Station | - **Goal:** Manage construction documents (Correspondence, RFA, Contract Drawings, Shop Drawings) with complex multi-level approval workflows. - **Infrastructure:** - - **QNAP NAS:** Container Station (Docker), Nginx Proxy Manager, MariaDB, Redis, Elasticsearch, ClamAV - - **ASUSTOR NAS:** Ollama (AI Processing), n8n (Workflow Automation), Portainer - - **Shared:** Gitea (Git + CI/CD), Prometheus + Loki + Grafana (Monitoring/Logging) + - **QNAP NAS:** Container Station — DMS Frontend/Backend, MariaDB, Redis, Elasticsearch, Nginx Proxy Manager, n8n + n8n-db, Tika, Gitea, RocketChat, cAdvisor, exporters + - **ASUSTOR NAS:** Portainer — Monitoring Hub (Grafana, Prometheus, Loki, Promtail, uptime-kuma), Gitea Runner (act_runner), Docker Registry, cAdvisor, Cloudflared + - **Admin Desktop:** Ollama (AI Processing) — i9-9900K, 32GB RAM, RTX 2060 SUPER 8GB + - **Shared Network:** Internal VLAN — QNAP scrapes by ASUSTOR Prometheus ## 💻 Tech Stack & Constraints @@ -28,7 +41,7 @@ You value **Data Integrity**, **Security**, and **Clean Architecture**. - **Frontend:** Next.js 14+ (App Router), Tailwind CSS, Shadcn/UI, TanStack Query (**Server State**), Zustand (**Client State**), React Hook Form + Zod (**Form State**), Axios - **Notifications:** BullMQ Queue → Email / LINE Notify / In-App -- **AI/Migration:** Ollama (llama3.2:3b / mistral:7b) on ASUSTOR + n8n orchestration +- **AI/Migration:** Ollama (llama3.2:3b / mistral:7b) on Admin Desktop (RTX 2060 SUPER) + n8n on QNAP - **Language:** TypeScript (Strict Mode). **NO `any` types allowed.** ## 🛡️ Security & Integrity Rules @@ -39,16 +52,30 @@ You value **Data Integrity**, **Security**, and **Clean Architecture**. 4. **Validation:** Use Zod (frontend) or Class-validator (backend DTO) for all inputs. 5. **Password:** bcrypt with 12 salt rounds. Enforce password policy. 6. **Rate Limiting:** Apply ThrottlerGuard on auth endpoints. -7. **AI Isolation (ADR-018):** Ollama MUST run on ASUSTOR only. AI has NO direct DB access, NO write access to uploads. Output JSON only. +7. **AI Isolation (ADR-018):** Ollama MUST run on Admin Desktop only (NOT on QNAP/production server). AI has NO direct DB access, NO write access to uploads. Output JSON only. ## 📋 Workflow & Spec Guidelines -- Always follow specs in `specs/` (v1.8.0). Priority: `06-Decision-Records` > `05-Engineering-Guidelines` > others. +- Always follow specs in `specs/` (v1.8.1). Priority: `06-Decision-Records` > `05-Engineering-Guidelines` > others. - Always verify database schema against **`specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql`** before writing queries. (Schema split: `01-drop`, `02-tables`, `03-views-indexes`) - Check data dictionary at **`specs/03-Data-and-Storage/03-01-data-dictionary.md`** for field meanings and business rules. - Check seed data: **`lcbp3-v1.8.0-seed-basic.sql`** (reference data), **`lcbp3-v1.8.0-seed-permissions.sql`** (CASL permissions). - For migration context: **`specs/03-Data-and-Storage/03-04-legacy-data-migration.md`** and **`03-05-n8n-migration-setup-guide.md`**. +### 📁 Key Spec Documents (Quick Reference) + +| เอกสาร | Path | ใช้เมื่อ | +|--------|------|--------| +| **Schema Tables** | `03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql` | ก่อนเขียน Query ทุกครั้ง | +| **Data Dictionary** | `03-Data-and-Storage/03-01-data-dictionary.md` | ตรวจ Field Meaning + Business Rules | +| **Seed Permissions** | `03-Data-and-Storage/lcbp3-v1.8.0-seed-permissions.sql` | ตรวจ CASL Permission Matrix | +| **Edge Cases** | `01-Requirements/01-06-edge-cases-and-rules.md` | 37 Rules ป้องกัน Bug | +| **Migration Scope** | `03-Data-and-Storage/03-06-migration-business-scope.md` | งาน Migration Bot | +| **Release Policy** | `04-Infrastructure-OPS/04-08-release-management-policy.md` | ก่อน Deploy / Hotfix | +| **UAT Criteria** | `01-Requirements/01-05-acceptance-criteria.md` | ตรวจความสมบูรณ์ Feature | +| **ADR-009** | `06-Decision-Records/ADR-009-db-strategy.md` | Schema Change Process | +| **ADR-018** | `06-Decision-Records/ADR-018-ai-boundary.md` | AI/Ollama Integration Rules | + ### ADR Reference (All 17 + Patch) Adhere to all ADRs in `specs/06-Decision-Records/`: @@ -97,9 +124,13 @@ Use `/slash-command` to trigger these workflows. Always prefer spec-driven devel - DO NOT use SQL Triggers (Business logic must be in NestJS services). - DO NOT use `.env` files for production deployment — QNAP Container Station requires secrets directly in `docker-compose.yml` environment section. -- DO NOT run database migrations — modify the schema SQL file directly. +- DO NOT run database migrations — modify the schema SQL file directly (ADR-009). - DO NOT invent table names or columns — use ONLY what is defined in the schema SQL file. - DO NOT generate code that violates OWASP Top 10 security practices. - DO NOT use `any` TypeScript type anywhere. -- DO NOT let AI (Ollama) access production database directly — all writes go through DMS API. +- DO NOT let AI (Ollama) access production database directly — all writes go through DMS API (ADR-018). - DO NOT bypass StorageService for file operations — all file moves must go through the API. +- DO NOT deploy to Production without completing Release Gates — see `04-08-release-management-policy.md`. +- DO NOT start Legacy Migration without Go/No-Go Gate #1 approval — see `03-06-migration-business-scope.md`. +- DO NOT modify Migration Bot Token scope — IP Whitelist + 7-day Expiry + REVOKE after migration. +- DO NOT close UAT sign-off without all Acceptance Criteria ✅ — see `01-05-acceptance-criteria.md`. diff --git a/AGENTS.md b/AGENTS.md index 38298f8..12c8eb2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,14 +10,27 @@ You value **Data Integrity**, **Security**, and **Clean Architecture**. ## 🏗️ Project Overview -**LCBP3-DMS (Laem Chabang Port Phase 3 - Document Management System)** — Version 1.8.0 (Patch 1.8.1) +**LCBP3-DMS (Laem Chabang Port Phase 3 - Document Management System)** — Version 1.8.1 (Patch) + +### 📊 Project Status: UAT Ready (2026-03-11) + +| Area | Status | Notes | +|------|--------|-------| +| Backend | ✅ Production Ready | 18 Modules, ADR-018 AI Isolation | +| Frontend | ✅ 100% Complete | App Router, TanStack Query, Zustand | +| Database | ✅ Schema v1.8.0 Stable | MariaDB 11.8, No-migration (ADR-009) | +| Documentation | ✅ **10/10 Gaps Closed** | Product Vision → Release Policy | +| AI Migration | 🔄 Pre-migration Setup | n8n + Ollama (ADR-017/018) | +| Testing | 🔄 UAT In Progress | Per `01-05-acceptance-criteria.md` | +| Deployment | 📋 Pending Go-Live | Blue-Green, QNAP Container Station | - **Goal:** Manage construction documents (Correspondence, RFA, Contract Drawings, Shop Drawings) with complex multi-level approval workflows. - **Infrastructure:** - - **QNAP NAS:** Container Station (Docker), Nginx Proxy Manager, MariaDB, Redis, Elasticsearch, ClamAV - - **ASUSTOR NAS:** Ollama (AI Processing), n8n (Workflow Automation), Portainer - - **Shared:** Gitea (Git + CI/CD), Prometheus + Loki + Grafana (Monitoring/Logging) + - **QNAP NAS:** Container Station — DMS Frontend/Backend, MariaDB, Redis, Elasticsearch, Nginx Proxy Manager, n8n + n8n-db, Tika, Gitea, RocketChat, cAdvisor, exporters + - **ASUSTOR NAS:** Portainer — Monitoring Hub (Grafana, Prometheus, Loki, Promtail, uptime-kuma), Gitea Runner (act_runner), Docker Registry, cAdvisor, Cloudflared + - **Admin Desktop:** Ollama (AI Processing) — i9-9900K, 32GB RAM, RTX 2060 SUPER 8GB + - **Shared Network:** Internal VLAN — QNAP scrapes by ASUSTOR Prometheus ## 💻 Tech Stack & Constraints @@ -26,7 +39,7 @@ You value **Data Integrity**, **Security**, and **Clean Architecture**. - **Frontend:** Next.js 14+ (App Router), Tailwind CSS, Shadcn/UI, TanStack Query (**Server State**), Zustand (**Client State**), React Hook Form + Zod (**Form State**), Axios - **Notifications:** BullMQ Queue → Email / LINE Notify / In-App -- **AI/Migration:** Ollama (llama3.2:3b / mistral:7b) on ASUSTOR + n8n orchestration +- **AI/Migration:** Ollama (llama3.2:3b / mistral:7b) on Admin Desktop (RTX 2060 SUPER) + n8n on QNAP - **Language:** TypeScript (Strict Mode). **NO `any` types allowed.** ## 🛡️ Security & Integrity Rules @@ -37,14 +50,28 @@ You value **Data Integrity**, **Security**, and **Clean Architecture**. 4. **Validation:** Use Zod (frontend) or Class-validator (backend DTO) for all inputs. 5. **Password:** bcrypt with 12 salt rounds. Enforce password policy. 6. **Rate Limiting:** Apply ThrottlerGuard on auth endpoints. -7. **AI Isolation (ADR-018):** Ollama MUST run on ASUSTOR only. AI has NO direct DB access, NO write access to uploads. Output JSON only. +7. **AI Isolation (ADR-018):** Ollama MUST run on Admin Desktop only (NOT on QNAP/production server). AI has NO direct DB access, NO write access to uploads. Output JSON only. ## 📋 Spec Guidelines -- Always follow specs in `specs/` (v1.8.0). Priority: `06-Decision-Records` > `05-Engineering-Guidelines` > others. +- Always follow specs in `specs/` (v1.8.1). Priority: `06-Decision-Records` > `05-Engineering-Guidelines` > others. - Always verify database schema against **`specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql`** before writing queries. (Schema split: `01-drop`, `02-tables`, `03-views-indexes`) - Check data dictionary at **`specs/03-Data-and-Storage/03-01-data-dictionary.md`** for field meanings and business rules. +### 📁 Key Spec Documents (Quick Reference) + +| เอกสาร | Path | ใช้เมื่อ | +|--------|------|--------| +| **Schema Tables** | `03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql` | ก่อนเขียน Query ทุกครั้ง | +| **Data Dictionary** | `03-Data-and-Storage/03-01-data-dictionary.md` | ตรวจ Field Meaning + Business Rules | +| **Seed Permissions** | `03-Data-and-Storage/lcbp3-v1.8.0-seed-permissions.sql` | ตรวจ CASL Permission Matrix | +| **Edge Cases** | `01-Requirements/01-06-edge-cases-and-rules.md` | 37 Rules ป้องกัน Bug | +| **Migration Scope** | `03-Data-and-Storage/03-06-migration-business-scope.md` | งาน Migration Bot | +| **Release Policy** | `04-Infrastructure-OPS/04-08-release-management-policy.md` | ก่อน Deploy / Hotfix | +| **UAT Criteria** | `01-Requirements/01-05-acceptance-criteria.md` | ตรวจความสมบูรณ์ Feature | +| **ADR-009** | `06-Decision-Records/ADR-009-db-strategy.md` | Schema Change Process | +| **ADR-018** | `06-Decision-Records/ADR-018-ai-boundary.md` | AI/Ollama Integration Rules | + ### ADR Reference (All 17 + Patch) | ADR | Topic | Key Decision | @@ -69,9 +96,13 @@ You value **Data Integrity**, **Security**, and **Clean Architecture**. - DO NOT use SQL Triggers (Business logic must be in NestJS services). - DO NOT use `.env` files for production deployment — QNAP Container Station requires secrets directly in `docker-compose.yml` environment section. -- DO NOT run database migrations — modify the schema SQL file directly. +- DO NOT run database migrations — modify the schema SQL file directly (ADR-009). - DO NOT invent table names or columns — use ONLY what is defined in the schema SQL file. - DO NOT generate code that violates OWASP Top 10 security practices. - DO NOT use `any` TypeScript type anywhere. -- DO NOT let AI (Ollama) access production database directly — all writes go through DMS API. +- DO NOT let AI (Ollama) access production database directly — all writes go through DMS API (ADR-018). - DO NOT bypass StorageService for file operations — all file moves must go through the API. +- DO NOT deploy to Production without completing Release Gates — see `04-08-release-management-policy.md`. +- DO NOT start Legacy Migration without Go/No-Go Gate #1 approval — see `03-06-migration-business-scope.md`. +- DO NOT modify Migration Bot Token scope — IP Whitelist + 7-day Expiry + REVOKE after migration. +- DO NOT close UAT sign-off without all Acceptance Criteria ✅ — see `01-05-acceptance-criteria.md`. diff --git a/CHANGELOG.md b/CHANGELOG.md index d430478..4e01447 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,8 +4,96 @@ ### In Progress -- Continuous Integration & End-to-End Test (E2E) Improvements -- Advanced Analytics Dashboard Planning +- UAT (User Acceptance Testing) — ตาม `01-05-acceptance-criteria.md` +- KPI Baseline Collection (As-Is Metrics ก่อน Go-Live) +- Legacy Data Migration — Tier 1 (2,000 docs Critical) +- Final Security Audit — ตาม `04-06-security-operations.md` +- Go-Live: Blue-Green Deploy บน QNAP Container Station + +--- + +## 1.8.1 Patch (2026-03-11) + +### Summary + +**Product Owner Documentation Complete** — ปิด 10/10 Documentation Gaps สำหรับ UAT Readiness +ระบบมีเอกสารครบถ้วนสำหรับ Stakeholder Sign-off และ Go-Live Process + +### Documentation 📚 — 10/10 Gaps Closed + +#### Gap 1: Product Vision Statement ✅ `specs/00-Overview/00-03-product-vision.md` +- Elevator Pitch, Problem Statement, Geoffrey Moore Vision Format +- Strategic Pillars: Speed / Security / Visibility +- Phase Roadmap (Now → 24 เดือน), Guardrails, Success Metrics + +#### Gap 2: User Stories ✅ `specs/01-Requirements/01-04-user-stories.md` +- 27 User Stories ครอบคลุม 8 Epics +- MoSCoW Prioritization per Story +- Acceptance Criteria + Definition of Done + +#### Gap 3: Acceptance Criteria (UAT) ✅ `specs/01-Requirements/01-05-acceptance-criteria.md` +- 35 Acceptance Criteria (All Modules) +- UAT Plan: 4 Phases, Sign-off Process +- Go-Live Criteria Matrix + +#### Gap 4: UI/UX Wireframes ✅ `specs/01-Requirements/01-07-ui-wireframes.md` +- Screen Inventory: 26 Screens พร้อม Role + Priority +- Navigation Map / Site Map ครบทุก Route +- ASCII Wireframes: Login, Dashboard, Correspondence, RFA, Circulation, Admin +- Design System Tokens + Interaction Patterns + +#### Gap 5: Stakeholder Sign-off & Risk ✅ `specs/00-Overview/00-04-stakeholder-signoff-and-risk.md` +- Sign-off Process 4-Step + Digital Sign Matrix +- Risk Register: 15 Risks (Impact × Probability Matrix) +- Change Control Policy + Emergency Change Process + +#### Gap 6: KPI Baseline Data ✅ `specs/00-Overview/00-05-kpi-baseline.md` +- 14 KPIs พร้อม Baseline Collection Form +- SQL Measurement Queries + Grafana Dashboard Specs +- User Satisfaction Survey Template + +#### Gap 7: Migration Business Scope ✅ `specs/03-Data-and-Storage/03-06-migration-business-scope.md` +- Data Scope: IN/OUT SCOPE (ปี 2564 → Go-Live) +- Migration Tiers: Tier 1 (2K Critical) / Tier 2 (10K) / Tier 3 (8K Archive) +- Excel Metadata Mapping (11 Columns → Field ใหม่) +- Organization Code Lookup Table +- Timeline: T-6 สัปดาห์ → Go-Live → T+30 +- Go/No-Go Gates 3 ด่าน +- Data Security: AI Isolation (ADR-018) + Token 7 วัน + IP Whitelist + +#### Gap 8: Release Management Policy ✅ `specs/04-Infrastructure-OPS/04-08-release-management-policy.md` +- SemVer Strategy + Git Flow (main/release/develop/hotfix) +- 5 Release Gates: Code Complete → QA → Staging → Approval → Production +- Quality Thresholds: TS 0 errors, ≥80% Test Coverage, 0 Critical Vuln +- Hotfix Process: P0 < 4h / P1 < 24h + Decision Tree +- Rollback Policy: SLA < 30 วิ (Blue-Green) + Auto-trigger Rules +- CI/CD Pipeline: 5 Stages (Quality → Security → Build → Integration → Release) +- Release Checklist + Security Pre-release Requirements + +#### Gap 9: Training Plan ✅ `specs/00-Overview/00-06-training-plan.md` +- Curriculum แบ่งตาม Role (4 Roles) +- 4-Phase Training Timeline +- Hands-on Lab + Assessment Criteria + +#### Gap 10: Edge Cases & Business Rules ✅ `specs/01-Requirements/01-06-edge-cases-and-rules.md` +- 37 Edge Cases ครอบคลุมทุก Module +- Business Logic Guards + Error Handling Matrix + +### Architecture Decision Records 🏛️ + +- **ADR-018** (Patch 1.8.1): AI Boundary — Ollama Isolation Policy + - Ollama ไม่มี Direct DB/Storage Access + - AI Output ต้องผ่าน Backend Validation ก่อน Write + - Migration Bot Token: IP Whitelist + 7-day Expiry + +### READMEs Updated 📄 + +- `README.md`: Status badge v1.8.1, UAT Ready, 10/10 Gaps table, fixed schema commands, updated Roadmap +- `CONTRIBUTING.md`: Spec tree updated (new files), schema filenames corrected, category table updated +- `specs/00-Overview/README.md`: Quick Links table เพิ่ม Gap 4/7/8 links +- `specs/01-Requirements/README.md`: Gap documents registered +- `specs/03-Data-and-Storage/README.md`: Migration Scope registered +- `specs/04-Infrastructure-OPS/README.md`: Release Policy registered ## 1.8.0 (2026-02-24) diff --git a/CLAUDE.md b/CLAUDE.md index 94b09c4..5bc32aa 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,9 +13,10 @@ You value **Data Integrity**, **Security**, and **Clean Architecture**. - **Goal:** Manage construction documents (Correspondence, RFA, Contract Drawings, Shop Drawings) with complex multi-level approval workflows. - **Infrastructure:** - - **QNAP NAS:** Container Station (Docker), Nginx Proxy Manager, MariaDB, Redis, Elasticsearch, ClamAV - - **ASUSTOR NAS:** Ollama (AI Processing), n8n (Workflow Automation), Portainer - - **Shared:** Gitea (Git + CI/CD), Prometheus + Loki + Grafana (Monitoring/Logging) + - **QNAP NAS:** Container Station — DMS Frontend/Backend, MariaDB, Redis, Elasticsearch, Nginx Proxy Manager, n8n + n8n-db, Tika, Gitea, RocketChat, cAdvisor, exporters + - **ASUSTOR NAS:** Portainer — Monitoring Hub (Grafana, Prometheus, Loki, Promtail, uptime-kuma), Gitea Runner (act_runner), Docker Registry, cAdvisor, Cloudflared + - **Admin Desktop:** Ollama (AI Processing) — i9-9900K, 32GB RAM, RTX 2060 SUPER 8GB + - **Shared Network:** Internal VLAN — QNAP scrapes by ASUSTOR Prometheus ## 💻 Tech Stack & Constraints @@ -24,7 +25,7 @@ You value **Data Integrity**, **Security**, and **Clean Architecture**. - **Frontend:** Next.js 14+ (App Router), Tailwind CSS, Shadcn/UI, TanStack Query (**Server State**), Zustand (**Client State**), React Hook Form + Zod (**Form State**), Axios - **Notifications:** BullMQ Queue → Email / LINE Notify / In-App -- **AI/Migration:** Ollama (llama3.2:3b / mistral:7b) on ASUSTOR + n8n orchestration +- **AI/Migration:** Ollama (llama3.2:3b / mistral:7b) on Admin Desktop (RTX 2060 SUPER) + n8n on QNAP - **Language:** TypeScript (Strict Mode). **NO `any` types allowed.** ## 🛡️ Security & Integrity Rules @@ -35,7 +36,7 @@ You value **Data Integrity**, **Security**, and **Clean Architecture**. 4. **Validation:** Use Zod (frontend) or Class-validator (backend DTO) for all inputs. 5. **Password:** bcrypt with 12 salt rounds. Enforce password policy. 6. **Rate Limiting:** Apply ThrottlerGuard on auth endpoints. -7. **AI Isolation (ADR-018):** Ollama MUST run on ASUSTOR only. AI has NO direct DB access, NO write access to uploads. Output JSON only. +7. **AI Isolation (ADR-018):** Ollama MUST run on Admin Desktop only (NOT on QNAP/production server). AI has NO direct DB access, NO write access to uploads. Output JSON only. ## 📋 Workflow & Spec Guidelines diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2871153..08f659f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,15 +25,23 @@ ``` specs/ ├── 00-Overview/ # ภาพรวมโครงการ -│ ├── README.md # Project overview -│ ├── 00-02-glossary.md # คำศัพท์เทคนิค -│ └── 00-01-quick-start.md # Quick start guide +│ ├── README.md +│ ├── 00-01-quick-start.md # Quick start guide +│ ├── 00-02-glossary.md # คำศัพท์เทคนิค +│ ├── 00-03-product-vision.md # Gap 1: Vision, Strategy, Guardrails [★ NEW] +│ ├── 00-04-stakeholder-signoff-and-risk.md # Gap 5: Sign-off, Risk [★ NEW] +│ ├── 00-05-kpi-baseline.md # Gap 6: 14 KPIs + Baseline Plan [★ NEW] +│ └── 00-06-training-plan.md # Gap 9: Training Curriculum [★ NEW] │ -├── 01-Requirements/ # ข้อกำหนดระบบ (21 docs) -│ ├── README.md # Requirements overview -│ ├── 01-01-objectives.md # วัตถุประสงค์ -│ ├── 01-02-business-rules/ # กฏธุรกิจที่ห้ามละเมิด -│ └── 01-03-modules/ # สเปกของแต่ละฟีเจอร์หลัก +├── 01-Requirements/ # ข้อกำหนดระบบ (21+ docs) +│ ├── README.md +│ ├── 01-01-objectives.md # วัตถุประสงค์ +│ ├── 01-02-business-rules/ # กฏธุรกิจที่ห้ามละเมิด +│ ├── 01-03-modules/ # สเปกของแต่ละฟีเจอร์หลัก +│ ├── 01-04-user-stories.md # Gap 2: 27 Stories, 8 Epics, MoSCoW [★ NEW] +│ ├── 01-05-acceptance-criteria.md # Gap 3: UAT Criteria + Sign-off [★ NEW] +│ ├── 01-06-edge-cases-and-rules.md # Gap 10: 37 Edge Cases [★ NEW] +│ └── 01-07-ui-wireframes.md # Gap 4: 26 Screens, Design System [★ NEW] │ ├── 02-Architecture/ # สถาปัตยกรรมระบบ (4 docs) │ ├── README.md @@ -42,17 +50,23 @@ specs/ │ ├── 02-03-network-design.md │ └── 02-04-api-design.md │ -├── 03-Data-and-Storage/ # Database Schema (4 files) +├── 03-Data-and-Storage/ # Database Schema v1.8.0 (3-file split) │ ├── README.md -│ ├── lcbp3-v1.7.0-schema.sql -│ ├── lcbp3-v1.7.0-seed-basic.sql -│ └── 03-01-data-dictionary.md +│ ├── lcbp3-v1.8.0-schema-01-drop.sql # DROP statements +│ ├── lcbp3-v1.8.0-schema-02-tables.sql # CREATE TABLE +│ ├── lcbp3-v1.8.0-schema-03-views-indexes.sql # Views + Indexes +│ ├── lcbp3-v1.8.0-seed-basic.sql # Master Data Seed +│ ├── lcbp3-v1.8.0-seed-permissions.sql # RBAC Permissions Seed +│ ├── 03-01-data-dictionary.md +│ └── 03-06-migration-business-scope.md # Gap 7: Migration Scope [★ NEW] │ -├── 04-Infrastructure-OPS/ # Deployment & Operations (9 docs) +├── 04-Infrastructure-OPS/ # Deployment & Operations (8 docs) │ ├── README.md │ ├── 04-01-docker-compose.md │ ├── 04-03-monitoring.md -│ └── ... +│ ├── 04-04-deployment-guide.md +│ ├── 04-07-incident-response.md +│ └── 04-08-release-management-policy.md # Gap 8: Release Policy [★ NEW] │ ├── 05-Engineering-Guidelines/# แผนการพัฒนา (5 docs) │ ├── README.md @@ -61,11 +75,12 @@ specs/ │ ├── 05-03-frontend-guidelines.md │ └── 05-04-testing-strategy.md │ -├── 06-Decision-Records/ # Architecture Decision Records (17 ADRs) +├── 06-Decision-Records/ # Architecture Decision Records (17+1 ADRs) │ ├── README.md │ ├── ADR-001-unified-workflow.md │ ├── ADR-002-document-numbering.md -│ └── ... +│ ├── ... (ADR-003 to ADR-017) +│ └── ADR-018-ai-boundary.md # AI Isolation Policy [★ Patch 1.8.1] │ └── 99-archives/ # ประวัติการทำงานและ Tasks เก่า ├── history/ @@ -75,16 +90,16 @@ specs/ ### 📋 หมวดหมู่เอกสาร -| หมวด | วัตถุประสงค์ | ผู้ดูแล | -| ----------------------------- | ----------------------------- | ----------------------------- | -| **00-Overview** | ภาพรวมโครงการและคำศัพท์ | Project Manager | -| **01-Requirements** | ข้อกำหนดฟังก์ชันและระบบ | Business Analyst + Tech Lead | -| **02-Architecture** | สถาปัตยกรรมและการออกแบบ | Tech Lead + Architects | -| **03-Data-and-Storage** | Database Schema & Seed Data | Backend Lead + DBA | -| **04-Infrastructure-OPS** | Deployment และ Operations | DevOps Team | -| **05-Engineering-Guidelines** | แผนการพัฒนาและ Implementation | Development Team Leads | -| **06-Decision-Records** | Architecture Decision Records | Tech Lead + Senior Developers | -| **99-archives** | Archived / Tasks | All Team Members | +| หมวด | วัตถุประสงค์ | ไฟล์สำคัญ | ผู้ดูแล | +|------|---------|---------|--------| +| **00-Overview** | ภาพรวม, Product Vision, KPI, Training | Gap 1/5/6/9 | Project Manager / PO | +| **01-Requirements** | User Stories, UAT, UI, Edge Cases | Gap 2/3/4/10 | Business Analyst + PO | +| **02-Architecture** | สถาปัตยกรรมและการออกแบบ | — | Tech Lead + Architects | +| **03-Data-and-Storage** | Schema v1.8.0, Migration Scope | Gap 7 | Backend Lead + DBA | +| **04-Infrastructure-OPS** | Deployment, Operations, Release Policy | Gap 8 | DevOps Team | +| **05-Engineering-Guidelines** | แผนการพัฒนาและ Implementation | — | Development Team Leads | +| **06-Decision-Records** | Architecture Decision Records (17+1) | ADR-018 | Tech Lead + Senior Devs | +| **99-archives** | Archived / Tasks | — | All Team Members | --- diff --git a/README.md b/README.md index 85c5b88..cb555f8 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,28 @@ # 📋 LCBP3-DMS - Document Management System > **Laem Chabang Port Phase 3 - Document Management System** -> > ระบบบริหารจัดการเอกสารโครงการแบบครบวงจร สำหรับโครงการก่อสร้างท่าเรือแหลมฉบังระยะที่ 3 -[![Version](https://img.shields.io/badge/version-1.8.0-blue.svg)](./CHANGELOG.md) +[![Version](https://img.shields.io/badge/version-1.8.1-blue.svg)](./CHANGELOG.md) [![License](https://img.shields.io/badge/license-Internal-red.svg)]() -[![Status](https://img.shields.io/badge/status-Production%20Ready-brightgreen.svg)]() +[![Status](https://img.shields.io/badge/status-UAT%20Ready-brightgreen.svg)]() +[![Docs](https://img.shields.io/badge/docs-10%2F10%20Gaps%20Closed-success.svg)](./specs/00-Overview/README.md) --- -## 📈 Current Status (As of 2026-02-24) +## 📈 Current Status (As of 2026-03-11) -**Overall Progress: ~98% Feature Complete - Production Ready Preparation** +**Version 1.8.1 (Patch) — UAT Ready** -- ✅ **Backend**: Core modules implemented, refactoring for v1.8.0 Schema -- ✅ **Frontend**: UI tasks completed (100%), integrating new v1.8.0 features -- ✅ **Database**: Schema v1.8.0 active (Stabilized for Production) -- ✅ **Documentation**: Comprehensive specs/ at v1.8.0 -- ✅ **Admin Tools**: Unified Workflow & Advanced Numbering Config -- 🔄 **Testing**: E2E tests and UAT preparation -- 📋 **Next**: Final Security Audit & Deployment +| Area | Status | หมายเหตุ | +|------|--------|--------| +| 🔧 **Backend** | ✅ Production Ready | 18 Modules, ADR-018 AI Isolation | +| 🎨 **Frontend** | ✅ 100% Complete | App Router, TanStack Query, Zustand | +| 💾 **Database** | ✅ Schema v1.8.0 Stable | MariaDB 11.8, No-migration Policy | +| 📘 **Documentation** | ✅ **10/10 Gaps Closed** | Product Vision → Release Policy | +| 🤖 **AI Migration** | 🔄 Pre-migration Setup | n8n + Ollama (ADR-017/018) | +| 🧪 **Testing** | 🔄 UAT Preparation | E2E + Acceptance Criteria ready | +| 🚀 **Deployment** | 📋 Pending Go-Live Gate | Blue-Green on QNAP Container Station | --- @@ -43,6 +45,7 @@ LCBP3-DMS เป็นระบบบริหารจัดการเอก - 🔐 **RBAC 4-Level** - ควบคุมสิทธิ์แบบละเอียด (Global, Organization, Project, Contract) - 📁 **Two-Phase File Storage** - จัดการไฟล์แบบ Transactional พร้อม Virus Scanning - 🔢 **Document Numbering** - สร้างเลขที่เอกสารอัตโนมัติ ป้องกัน Race Condition +- 🤖 **AI-Assisted Migration** - Ollama + n8n นำเข้าเอกสารเก่า ~20,000 ไฟล์ (ADR-017/018) --- @@ -165,11 +168,14 @@ cp .env.local.example .env.local #### 4. ตั้งค่า Database ```bash -# Import schema -mysql -u root -p lcbp3_dev < docs/8_lcbp3_v1_4_5.sql +# Import schema (v1.8.0 — ดู ADR-009: No migrations, แก้ไข SQL ตรง) +mysql -u root -p lcbp3_dev < specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-01-drop.sql +mysql -u root -p lcbp3_dev < specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql +mysql -u root -p lcbp3_dev < specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-03-views-indexes.sql # Import seed data -mysql -u root -p lcbp3_dev < docs/8_lcbp3_v1_4_5_seed.sql +mysql -u root -p lcbp3_dev < specs/03-Data-and-Storage/lcbp3-v1.8.0-seed-basic.sql +mysql -u root -p lcbp3_dev < specs/03-Data-and-Storage/lcbp3-v1.8.0-seed-permissions.sql ``` #### 5. รัน Development Server @@ -269,14 +275,22 @@ lcbp3-dms/ │ ├── types/ # TypeScript definitions │ └── package.json │ -├── specs/ # 📘 Project Specifications (v1.8.0) -│ ├── 00-Overview/ # ภาพรวมระบบและแบบย่อ -│ ├── 01-Requirements/ # Business Requirements & กฎระเบียบ (21 docs) -│ ├── 02-Architecture/ # สถาปัตยกรรมระบบ -│ ├── 03-Data-and-Storage/ # โครงสร้างฐานข้อมูล v1.8.0 & Data Dictionary -│ ├── 04-Infrastructure-OPS/ # การเตรียม Operations & Infrastructure -│ ├── 05-Engineering-Guidelines/ # มาตรฐานการพัฒนาสำหรับโปรแกรมเมอร์ -│ ├── 06-Decision-Records/ # สรุปเหตุผลด้านสถาปัตยกรรม (ADRs) +├── specs/ # 📘 Project Specifications v1.8.1 — 10/10 Gaps Closed +│ ├── 00-Overview/ # ภาพรวม: Product Vision, KPI Baseline, Training, Stakeholder +│ │ ├── 00-03-product-vision.md # Gap 1 — Product Vision Statement +│ │ ├── 00-04-stakeholder-signoff-and-risk.md # Gap 5 — Risk & Sign-off +│ │ ├── 00-05-kpi-baseline.md # Gap 6 — KPI Baseline & 14 Metrics +│ │ └── 00-06-training-plan.md # Gap 9 — Training Curriculum +│ ├── 01-Requirements/ # Requirements: User Stories, UAT, UI Wireframes, Edge Cases +│ │ ├── 01-04-user-stories.md # Gap 2 — 27 User Stories (8 Epics) +│ │ ├── 01-05-acceptance-criteria.md # Gap 3 — UAT Acceptance Criteria +│ │ ├── 01-06-edge-cases-and-rules.md # Gap 10 — 37 Edge Cases +│ │ └── 01-07-ui-wireframes.md # Gap 4 — 26 Screens, Navigation Map +│ ├── 02-Architecture/ # สถาปัตยกรรมระบบ (4 docs) +│ ├── 03-Data-and-Storage/ # Schema v1.8.0 (split 3 files) + 03-06-migration-business-scope.md +│ ├── 04-Infrastructure-OPS/ # Ops: Deploy, Monitoring, Security + 04-08-release-management-policy.md +│ ├── 05-Engineering-Guidelines/ # มาตรฐานการพัฒนา Backend/Frontend +│ ├── 06-Decision-Records/ # 17+1 ADRs รวม ADR-018-ai-boundary │ └── 99-archives/ # ประวัติการทำงานและ Tasks เก่า │ ├── docs/ # 📚 Legacy documentation @@ -296,24 +310,33 @@ lcbp3-dms/ ### เอกสารหลัก (specs/ folder) -| เอกสาร | คำอธิบาย | โฟลเดอร์ | -| ------------------- | ------------------------------ | ---------------------------------- | -| **Overview** | ภาพรวมโครงการ, Glossary | `specs/00-Overview/` | -| **Requirements** | ข้อกำหนดระบบและฟังก์ชันการทำงาน | `specs/01-Requirements/` | -| **Architecture** | สถาปัตยกรรมระบบ | `specs/02-Architecture/` | -| **Database** | Schema v1.8.0 + Seed Data | `specs/03-Data-and-Storage/` | -| **Ops & Deploy** | วิธีการนำระบบขึ้นเซิร์ฟเวอร์ | `specs/04-Infrastructure-OPS/` | -| **Guidelines** | แนวทางการพัฒนา Backend/Frontend | `specs/05-Engineering-Guidelines/` | -| **Decisions (ADR)** | เหตุผลการตัดสินใจทางสถาปัตยกรรม | `specs/06-Decision-Records/` | +| เอกสาร | คำอธิบาย | Gap | ไฟล์หลัก | +|--------|---------|-----|--------| +| **Product Vision** | Vision, Strategic Pillars, Guardrails | Gap 1 ✅ | `00-03-product-vision.md` | +| **User Stories** | 27 Stories, 8 Epics, MoSCoW | Gap 2 ✅ | `01-04-user-stories.md` | +| **Acceptance Criteria** | UAT Criteria, Sign-off Process | Gap 3 ✅ | `01-05-acceptance-criteria.md` | +| **UI/UX Wireframes** | 26 Screens, ASCII Wireframes, Design System | Gap 4 ✅ | `01-07-ui-wireframes.md` | +| **Stakeholder & Risk** | Sign-off, Risk Register, Change Control | Gap 5 ✅ | `00-04-stakeholder-signoff-and-risk.md` | +| **KPI Baseline** | 14 KPIs, SQL Queries, Grafana Specs | Gap 6 ✅ | `00-05-kpi-baseline.md` | +| **Migration Scope** | 20K Docs, 3 Tiers, Go/No-Go Gates | Gap 7 ✅ | `03-06-migration-business-scope.md` | +| **Release Policy** | SemVer, 5 Gates, Hotfix, Rollback | Gap 8 ✅ | `04-08-release-management-policy.md` | +| **Training Plan** | Curriculum per Role, UAT Training | Gap 9 ✅ | `00-06-training-plan.md` | +| **Edge Cases & Rules** | 37 Edge Cases, Business Logic Guards | Gap 10 ✅ | `01-06-edge-cases-and-rules.md` | +| **Schema v1.8.0** | Tables, Views, Indexes (3-file split) | — | `lcbp3-v1.8.0-schema-*.sql` | +| **Data Dictionary** | Field Meanings, Business Rules | — | `03-01-data-dictionary.md` | +| **ADRs (17+1)** | All Architecture Decisions incl. ADR-018 | — | `06-Decision-Records/` | -### Schema & Seed Data +### Schema & Seed Data (v1.8.0) ```bash -# Import schema -mysql -u root -p lcbp3_dev < specs/03-Data-and-Storage/lcbp3-v1.7.0-schema.sql +# Schema แบ่งเป็น 3 ไฟล์ (ADR-009: ไม่มี TypeORM Migrations) +mysql -u root -p lcbp3_dev < specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-01-drop.sql +mysql -u root -p lcbp3_dev < specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql +mysql -u root -p lcbp3_dev < specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-03-views-indexes.sql -# Import seed data -mysql -u root -p lcbp3_dev < specs/03-Data-and-Storage/lcbp3-v1.7.0-seed-basic.sql +# Seed Data +mysql -u root -p lcbp3_dev < specs/03-Data-and-Storage/lcbp3-v1.8.0-seed-basic.sql +mysql -u root -p lcbp3_dev < specs/03-Data-and-Storage/lcbp3-v1.8.0-seed-permissions.sql ``` ### Legacy Documentation @@ -528,60 +551,48 @@ This project is **Internal Use Only** - ลิขสิทธิ์เป็น ## 🗺️ Roadmap -### Version 1.5.1 (Current - Dec 2025) ✅ **FEATURE COMPLETE** +### ✅ Version 1.8.0 (Feb 2026) — Schema & Type Safety -**Backend (18 Modules - ~95%)** +- ✅ Schema v1.8.0 (3-file split + ADR-009 No-Migration Policy) +- ✅ Purge ทุก `any` type จาก Frontend (Strict TypeScript) +- ✅ Specs restructure เป็น 7 canonical layers +- ✅ 17 ADRs ครอบคลุมทุก Architectural Decision -- ✅ Core Infrastructure (Auth, RBAC, File Storage) -- ✅ Authentication & Authorization (JWT + CASL RBAC 4-Level) -- ✅ Correspondence Module (Master-Revision Pattern) -- ✅ RFA Module (Full CRUD + Workflow) -- ✅ Drawing Module (Contract + Shop Drawings) -- ✅ Workflow Engine (DSL-based Hybrid) -- ✅ Document Numbering (Redlock + Optimistic Locking) -- ✅ Search (Elasticsearch Direct Indexing) -- ✅ Transmittal & Circulation Modules -- ✅ Notification & Audit Systems -- ✅ Master Data Management -- ✅ User Management -- ✅ Dashboard & Monitoring -- ✅ Swagger API Documentation +### ✅ Version 1.8.1 Patch (Mar 2026) — Product Owner Documentation -**Frontend (15 Tasks - 100%)** +**10/10 Documentation Gaps Closed:** -- ✅ Complete UI Implementation (17 component groups) -- ✅ All Business Modules (Correspondence, RFA, Drawings) -- ✅ Admin Panel (10 routes including Workflow & Numbering Config) -- ✅ Dashboard with Real-time Statistics -- ✅ Advanced Search UI -- ✅ RBAC Permission UI -- ✅ Responsive Layout (Desktop & Mobile) +| Gap | เอกสาร | สถานะ | +|-----|--------|------| +| 1 | Product Vision Statement | ✅ | +| 2 | User Stories (27 Stories, 8 Epics) | ✅ | +| 3 | Acceptance Criteria & UAT Plan | ✅ | +| 4 | UI/UX Wireframes (26 Screens) | ✅ | +| 5 | Stakeholder Sign-off & Risk Register | ✅ | +| 6 | KPI Baseline Data (14 KPIs) | ✅ | +| 7 | Migration Business Scope (20K Docs) | ✅ | +| 8 | Release Management Policy (SemVer + Gates) | ✅ | +| 9 | Training Plan (per Role, 4 phases) | ✅ | +| 10 | Edge Cases & Business Rules (37 rules) | ✅ | -**Documentation** +- ✅ ADR-018: AI Boundary (Ollama Isolation มี No Direct DB/Storage Access) +- ✅ Migration n8n Workflow + AI Isolation Plan -- ✅ Complete specs/ v1.6.0 (21 requirements, 17 ADRs) -- ✅ Database Schema v1.6.0 with seed data -- ✅ Implementation & Operations Guides +### 🔄 Next: Go-Live Preparation -### Version 1.8.0 (Current - Feb 2026) +- 🔄 **UAT**: ทำ User Acceptance Testing ตาม `01-05-acceptance-criteria.md` +- 🔄 **KPI Baseline Collection**: เก็บ As-Is Metrics ก่อน Go-Live +- 🔄 **Legacy Migration**: เริ่ม Tier 1 (2,000 เอกสาร Critical) T-3 สัปดาห์ +- 🔄 **Security Audit**: ตาม `04-06-security-operations.md` +- 📋 **Go-Live**: Blue-Green Deploy บน QNAP Container Station -**Schema & Documentation Realignment** +### 📅 Version 1.9.0+ (Planned — Post Go-Live) -- ✅ **Specs Refactoring**: Merged infrastructure docs, reorganized `specs` tree to standard structure. -- ✅ **Database & Models**: Fully aligned Next.js features and TanStack Query with real v1.8.0 implementation. -- ✅ **Clean Code**: Comprehensive purge of `any` types from Frontend and robust Error Handling. -- 📋 **Deployment Readiness**: Preparing robust healthcheck and Nginx configurations for QNAP/ASUSTOR. - -### Version 1.9.0+ (Planned) - -**Production Enhancements** - -- 📊 Advanced Reporting & Analytics Dashboard -- 🔔 Enhanced Notifications (Real-time WebSocket) -- 📈 Prometheus Metrics & Grafana Dashboards -- 🔍 Queue-based Elasticsearch Indexing +- 📊 Advanced Reporting & Grafana KPI Dashboards (ตาม `00-05-kpi-baseline.md`) +- 🔔 Real-time Notifications (WebSocket) +- 🔍 Queue-based Elasticsearch Indexing (BullMQ) - 🚀 Performance Optimization & Caching Strategy -- 📱 Mobile App (React Native) +- 📱 Mobile App (React Native) — Phase 3 Vision --- diff --git a/backend/src/modules/migration/dto/import-correspondence.dto.ts b/backend/src/modules/migration/dto/import-correspondence.dto.ts index 93804af..eae3de6 100644 --- a/backend/src/modules/migration/dto/import-correspondence.dto.ts +++ b/backend/src/modules/migration/dto/import-correspondence.dto.ts @@ -54,10 +54,22 @@ export class ImportCorrespondenceDto { @IsOptional() received_date?: string; + @IsString() + @IsOptional() + document_date?: string; + @IsNumber() @IsOptional() discipline_id?: number; + @IsNumber() + @IsOptional() + sender_id?: number; + + @IsNumber() + @IsOptional() + receiver_id?: number; + @IsString() @IsOptional() body?: string; diff --git a/backend/src/modules/migration/migration.service.ts b/backend/src/modules/migration/migration.service.ts index 74d3c02..2c5489d 100644 --- a/backend/src/modules/migration/migration.service.ts +++ b/backend/src/modules/migration/migration.service.ts @@ -83,8 +83,7 @@ export class MigrationService { ); } - // Migrate documents typically end up as 'Closed by Owner' or a similar terminal state, unless specifically pending. - // For legacy, let's use a default terminal status 'CLBOWN' if available. If not, fallback to 'DRAFT'. + // Default status for correspondence let status = await this.correspondenceStatusRepo.findOne({ where: { statusCode: 'CLBOWN' }, }); @@ -99,16 +98,18 @@ export class MigrationService { ); } - // We assume migration runs for LCBP3 project + // We now use project_id from n8n (instead of hardcoding LCBP3) const project = await this.projectRepo.findOne({ - where: { projectCode: 'LCBP3' }, + where: { id: dto.project_id }, }); if (!project) { - throw new InternalServerErrorException( - 'Project LCBP3 not found in database' + throw new BadRequestException( + `Project ID ${dto.project_id} not found in database` ); } + const isRFA = type?.typeCode === 'RFA' || dto.category === 'RFA'; + const queryRunner = this.dataSource.createQueryRunner(); await queryRunner.connect(); await queryRunner.startTransaction(); @@ -128,14 +129,39 @@ export class MigrationService { correspondenceTypeId: typeId, projectId: project.id, disciplineId: dto.discipline_id || undefined, + originatorId: dto.sender_id || undefined, // Set explicitly from DTO isInternal: false, createdBy: userId, }); await queryRunner.manager.save(correspondence); - } else if (dto.discipline_id && !correspondence.disciplineId) { - // อัพเดต discipline_id หากเอกสารเดิมยังไม่มี - correspondence.disciplineId = dto.discipline_id; - await queryRunner.manager.save(correspondence); + + // --- CTI: insert RFA class --- + if (isRFA) { + // Default RFA type generic mapping + const rfaTypeRes = (await queryRunner.manager.query( + "SELECT id FROM rfa_types WHERE type_code = 'GEN' LIMIT 1" + )) as Array<{ id: number }>; + const rfa = queryRunner.manager.create('Rfa', { + id: correspondence.id, + rfaTypeId: rfaTypeRes[0]?.id || 1, // fallback to id 1 + createdBy: userId, + }); + await queryRunner.manager.save('Rfa', rfa); + } + } else { + // Update values if missing + let hasChanges = false; + if (dto.discipline_id && !correspondence.disciplineId) { + correspondence.disciplineId = dto.discipline_id; + hasChanges = true; + } + if (dto.sender_id && !correspondence.originatorId) { + correspondence.originatorId = dto.sender_id; + hasChanges = true; + } + if (hasChanges) { + await queryRunner.manager.save(correspondence); + } } // 4. File Handling @@ -158,6 +184,9 @@ export class MigrationService { } } + // Helper function to parse Date safety + const parseDateStr = (d?: string) => (d ? new Date(d) : undefined); + // 5. Create Revision const revisionCount = await queryRunner.manager.count( CorrespondenceRevision, @@ -175,7 +204,10 @@ export class MigrationService { statusId: status.id, subject: dto.title, description: 'Migrated from legacy system via Auto Ingest', - body: dto.body || undefined, // Map from DTO + body: dto.body || undefined, + documentDate: parseDateStr(dto.document_date || dto.issued_date), + issuedDate: parseDateStr(dto.issued_date), + receivedDate: parseDateStr(dto.received_date), details: { ...dto.details, ai_confidence: dto.ai_confidence, @@ -197,7 +229,26 @@ export class MigrationService { await queryRunner.manager.save(revision); - // 5. Track Transaction + // --- CTI: insert RfaRevision --- + if (isRFA) { + // Map Status code to RFA Equivalent 'APP' (Approved) if exist, or id 3 (typically Approved) + const rfaStatusRes = (await queryRunner.manager.query( + "SELECT id FROM rfa_status_codes WHERE status_code = 'APP' LIMIT 1" + )) as Array<{ id: number }>; + + const rfaRev = queryRunner.manager.create('RfaRevision', { + id: revision.id, + rfaStatusCodeId: rfaStatusRes[0]?.id || 3, // Fallback to 3 if APP not found + details: { + // Keep drawingCount as 0 for migration stub + drawingCount: 0, + }, + schemaVersion: 1, + }); + await queryRunner.manager.save('RfaRevision', rfaRev); + } + + // 6. Track Transaction const transaction = queryRunner.manager.create(ImportTransaction, { idempotencyKey, documentNumber: dto.document_number, diff --git a/specs/.vscode/settings.json b/specs/.vscode/settings.json deleted file mode 100644 index 3f228f6..0000000 --- a/specs/.vscode/settings.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "editor.fontSize": 18 -} diff --git a/specs/00-overview/00-03-product-vision.md b/specs/00-overview/00-03-product-vision.md new file mode 100644 index 0000000..dfa26bb --- /dev/null +++ b/specs/00-overview/00-03-product-vision.md @@ -0,0 +1,183 @@ +# 🎯 Product Vision Statement — LCBP3-DMS v1.8.0 + +--- +title: 'Product Vision Statement' +version: 1.0.0 +status: APPROVED (Internal) +owner: Nattanin Peancharoen (Product Owner) +last_updated: 2026-03-11 +related: + - specs/00-Overview/README.md + - specs/01-Requirements/01-01-objectives.md + - specs/00-Overview/00-04-stakeholder-signoff-and-risk.md +--- + +--- + +## 1. 🗣️ Elevator Pitch (30 วินาที) + +> **LCBP3-DMS** คือระบบบริหารจัดการเอกสารก่อสร้าง On-Premise ที่ออกแบบมาเพื่อโครงการท่าเรือแหลมฉบัง เฟส 3 โดยเฉพาะ +> +> ระบบแปลงกระบวนการอนุมัติเอกสาร RFA ที่เคยใช้เวลา 2–3 สัปดาห์ผ่านอีเมล ให้กลายเป็น Workflow อัตโนมัติที่โปร่งใส ตรวจสอบได้ และเสร็จสิ้นภายใน 3–5 วัน +> +> รองรับการทำงานร่วมกันของ 5 องค์กรใน 4 โครงการ ด้วยสิทธิ์การเข้าถึงข้อมูลระดับองค์กร ที่ปลอดภัย ไม่มีข้อมูลรั่วไหลข้ามองค์กร + +--- + +## 2. ❗ Problem Statement + +### ปัญหาที่เกิดขึ้นจริง (Pain Points) + +| # | ปัญหา | ผลกระทบ | +|---|------|---------| +| P1 | **RFA ใช้ Email** → ตามงานยาก, ตกหล่น | Cycle Time 14–21 วัน, งานช้า | +| P2 | **เลขเอกสารทำมือ** → ซ้ำ, ผิด | ต้องยกเลิกและออกเลขใหม่ | +| P3 | **ไม่รู้สถานะ** → ต้องโทรถาม | เสียเวลา ≥ 30 นาที/ครั้ง | +| P4 | **หลาย Version ใน Email** → งง | ใช้แบบเวอร์ชันเก่า ก่อสร้างผิด | +| P5 | **ไม่มี Audit Trail** → ตรวจสอบยาก | พิสูจน์ไม่ได้ว่าใครอนุมัติ | +| P6 | **ไม่มี Permission Control** → Contractor เห็นข้อมูลกัน | ความลับทางธุรกิจรั่ว | +| P7 | **ไม่มีการแจ้งเตือน** → พลาด Deadline | งานเกินเวลา | +| P8 | **ค้นหาเอกสารยาก** → ต้องขอซ้ำ | ทำงานซ้ำ เสียเวลา | + +### ผู้ที่ได้รับผลกระทบ + +- **Document Control:** ทำงานซ้ำซ้อน, นับเลขเอกสารมือ +- **Engineers / Reviewers:** รับงาน Review ช้า ไม่รู้ว่ามีงานรอ +- **PM / Supervisors:** ไม่มีภาพรวม Status ของเอกสารทั้งหมด +- **Management:** ไม่สามารถตรวจสอบ Audit Trail ย้อนหลังได้ + +--- + +## 3. 🌟 Vision Statement + +> **"For construction document teams at LCBP3 who struggle with manual, email-based approval processes, LCBP3-DMS is an on-premise document intelligence platform that delivers automated multi-organization workflows, tamper-proof audit trails, and real-time visibility into every document's lifecycle.** +> +> **Unlike general-purpose DMS products, LCBP3-DMS is purpose-built for Thai construction project complexity — multi-contractor isolation, Thai document numbering conventions, and on-premise security requirements — making it the only system that truly fits how LCBP3 teams work."** + +### โดยย่อ (3 คำ) + +> **"Document. Approve. Trust."** + +--- + +## 4. 🏛️ Strategic Pillars (3 เสาหลัก) + +### Pillar 1: ⚡ Speed & Automation + +ลด Cycle Time ของ RFA จาก 14 วัน → 3 วัน ด้วย: +- Auto Document Number (Redis Redlock — ไม่ซ้ำ, ไม่ต้องนับมือ) +- Workflow Automation (DSL-based — Route, Notify, Track อัตโนมัติ) +- Instant Notification (Email + LINE + In-App — ไม่ต้องโทรถาม) + +### Pillar 2: 🔒 Security & Trust + +ไม่มีข้อมูลรั่วไหล ไม่มีการปลอมแปลง ด้วย: +- 4-Level RBAC (Org Isolation — Contractor A ไม่เห็น Contractor B) +- Immutable Audit Trail (ทุก Action บันทึก ≥ 7 ปี ไม่แก้ไขได้) +- ClamAV Virus Scan ทุกไฟล์ + File Encryption at Rest +- On-Premise Deployment (ข้อมูลไม่ออก Internet) + +### Pillar 3: 👁️ Visibility & Control + +ทุกคนรู้ว่าเอกสารอยู่ที่ไหน ใครถือ ครบด้วย: +- Real-time Workflow Diagram (คลิกดู History ทุก Step) +- Dashboard: My Tasks, Overdue, KPI Cards +- Elasticsearch Full-text Search (ค้นหาได้ภายใน 500ms) +- Graceful Degradation (Core ยังทำงานแม้ Service รองล่ม) + +--- + +## 5. 👥 Target Users (Primary) + +| Persona | ต้องการอะไร | ได้อะไรจากระบบ | +|---------|-----------|--------------| +| **Document Control** | ออกเลข, ส่ง, Track เร็ว | Auto-Number + Workflow Dashboard | +| **Engineer / Reviewer** | รับแจ้ง, Review ง่าย, Comment | Notification + PDF Viewer + History | +| **PM / Supervisor** | เห็น Big Picture, ติดตาม Delay | Dashboard KPI + Overdue Alerts | +| **Management / Auditor** | ตรวจสอบย้อนหลัง | Audit Log + Immutable History | +| **กทท. (Owner)** | Compliance + Control | Permission Isolation + Reports | + +--- + +## 6. 🗺️ Product Roadmap Vision + +``` +Now (v1.8.0 — MVP) +├── Core DMS: Correspondence, RFA, Transmittal, Circulation +├── Workflow Engine: DSL-based Multi-Org Approval +├── Security: RBAC, Audit, ClamAV, JWT +└── ✅ "Every document has a number, a trail, and a home" + +Phase 2 (3–6 เดือน) — Operational Excellence +├── Advanced Reporting & Export (PDF/Excel) +├── Visual Workflow Builder (No-code DSL Editor) +├── LINE Notify Deep Integration (Approve via LINE) +└── Mobile-Optimized Views + +Phase 3 (6–12 เดือน) — Intelligence +├── AI-assisted Document Classification (Ollama) +├── Predictive Delay Alerts ("RFA นี้มีโอกาส Delay 70%") +├── Bulk Legacy Migration Assistant +└── API Gateway สำหรับ Integration กับ ERP/Cost Systems + +Phase 4 (12–24 เดือน) — Enterprise Scale +├── Multi-Project / Multi-Tenant Architecture +├── SaaS Option (Cloud Deployment) +└── ขยายไปใช้กับโครงการท่าเรืออื่นๆ ของ กทท. +``` + +--- + +## 7. ✅ Definition of Success + +### MVP Success (Go-Live + 3 เดือน) + +| Metric | Target | วิธีวัด | +|--------|--------|--------| +| **RFA Cycle Time** | ≤ 5 วัน (จาก 14) | Average จาก Workflow History | +| **User Adoption** | > 90% Login ทุกวันทำการ | System Analytics | +| **Error Rate** | < 1% Document Number Error | Audit Log | +| **Uptime** | ≥ 99.5% | Monitoring Dashboard | +| **User Satisfaction** | ≥ 4.0/5.0 | Post Go-Live Survey | + +### Long-term Success (1 ปีหลัง Go-Live) + +> "ทีมไม่จำเป็นต้องส่ง Email เพื่อติดตามเอกสารอีกต่อไป" +> "เลขเอกสารทุกฉบับถูกต้อง 100% โดยไม่ต้องมีคนนับ" +> "การตรวจสอบ Audit สามารถทำได้ภายใน 5 นาที" + +--- + +## 8. 🚫 What We Are NOT Building (Guardrails) + +การรู้ว่าเราไม่ทำอะไรสำคัญพอกับรู้ว่าเราทำอะไร: + +| ❌ ไม่ทำ | เหตุผล | ทางเลือก | +|---------|-------|---------| +| ระบบบัญชี / Finance | Out of Scope — ใช้ ERP | SAP / Oracle Integration (Phase 4) | +| Project Scheduling (Gantt) | Domain ต่างกัน | Microsoft Project / Primavera | +| HR / Payroll | ไม่เกี่ยวข้อง | ระบบ HR ที่มีอยู่ | +| Mobile Native App | Phase 2+ | Web Responsive เพียงพอ ช่วงแรก | +| Cloud SaaS | Data Sovereignty | On-Premise (ADR-005) | +| AI Document Generation | Risk สูง ใน MVP | Phase 3 (Ollama) | +| Real-time Video Conferencing | Out of Scope | Microsoft Teams / Zoom | + +--- + +## 9. 📐 Design Principles + +1. **Security First** — ไม่มี Feature ไหนสำคัญกว่าความปลอดภัยของข้อมูล +2. **Data Never Lies** — ทุก Action มี Audit Trail ไม่มีข้อยกเว้น +3. **Fail Gracefully** — ถ้า Service รองล่ม Core ต้องทำงานต่อได้ +4. **Built for Thailand** — Thai language, Thai calendar, Thai org structure +5. **On-Premise by Design** — ไม่ส่งข้อมูลออก Internet โดยไม่จำเป็น +6. **Boring Technology** — ใช้เทคโนโลยีที่ Proven ไม่ใช่ Trendy + +--- + +## 📝 Document Control + +- **Version:** 1.0.0 | **Status:** APPROVED (Internal) +- **Created:** 2026-03-11 | **Owner:** Nattanin Peancharoen +- **Approved By:** Nattanin Peancharoen (PO) | กทท. Sign-off pending +- **Classification:** Internal Use Only diff --git a/specs/00-overview/00-04-stakeholder-signoff-and-risk.md b/specs/00-overview/00-04-stakeholder-signoff-and-risk.md new file mode 100644 index 0000000..0b01716 --- /dev/null +++ b/specs/00-overview/00-04-stakeholder-signoff-and-risk.md @@ -0,0 +1,541 @@ +# 📋 Stakeholder Sign-off & Risk Management — LCBP3-DMS v1.8.0 + +--- +title: 'Stakeholder Sign-off Process & Risk Register' +version: 1.0.0 +status: DRAFT — Awaiting Stakeholder Review +owner: Nattanin Peancharoen (Product Owner / System Architect) +last_updated: 2026-03-11 +related: + - specs/01-Requirements/01-05-acceptance-criteria.md + - specs/01-Requirements/01-04-user-stories.md + - specs/00-Overview/00-06-training-plan.md + - specs/06-Decision-Records/ADR-016-security-authentication.md +--- + +> [!IMPORTANT] +> เอกสารนี้ต้องได้รับการ **Sign-off จากตัวแทนทุกองค์กร** ก่อนที่ระบบจะ Go-Live สู่ Production +> การ Sign-off ถือเป็นการยืนยันว่าองค์กรรับทราบ Scope, Risks, และพร้อมรับผิดชอบ UAT ในส่วนของตน + +--- + +## ส่วนที่ 1: Stakeholder Sign-off Process + +### 1.1 วัตถุประสงค์ + +การ Sign-off Process ทำหน้าที่: +1. **ยืนยัน Scope** — ทุกฝ่ายเห็นชอบ Feature ที่จะส่งมอบใน MVP +2. **ยืนยัน UAT Criteria** — เห็นชอบเกณฑ์การพิจารณาว่า "ผ่าน" คืออะไร (อ้างอิง `01-05-acceptance-criteria.md`) +3. **ยืนยัน Go-Live Readiness** — แต่ละองค์กรยืนยันว่าทีมพร้อม (Training, Data, User Access) +4. **รับทราบ Risks** — รับทราบความเสี่ยงที่อาจเกิดขึ้น และ Mitigation Plan + +--- + +### 1.2 Stakeholder Registry + +| # | Organization | บทบาทในโครงการ | บทบาทในระบบ DMS | ตัวแทน Sign-off | +|---|-------------|--------------|----------------|----------------| +| 1 | **กทท.** (การท่าเรือแห่งประเทศไทย) | Project Owner | System Owner, ผู้ใช้ระดับบน | TBD | +| 2 | **สค.** (สำนักงานโครงการ) | Project Management | Org Admin, Document Control | TBD | +| 3 | **TEAM** (ที่ปรึกษาออกแบบ) | Design Consultant | Document Control, Reviewer | TBD | +| 4 | **คคง.** (คณะกรรมการตรวจงาน) | Construction Supervisor | Reviewer, Approver | TBD | +| 5 | **ผรม.** (ผู้รับจ้างหลัก) | Main Contractor | Document Control, Submitter | TBD | +| 6 | **NAP** (ผู้พัฒนาระบบ) | System Developer | Superadmin, Support | Nattanin P. | + +--- + +### 1.3 Sign-off Workflow + +``` +Phase 1: Pre-Sign-off Review (T-3 สัปดาห์ก่อน Go-Live) +┌─────────────────────────────────────────────────────────┐ +│ NAP ส่งร่างเอกสารนี้ให้ตัวแทนทุกองค์กรรีวิว │ +│ + ส่ง Acceptance Criteria (01-05) ควบคู่ │ +│ + นัด Review Meeting (1 ชั่วโมง) กับทุกฝ่าย │ +└─────────────────────────────────────────────────────────┘ + ↓ +Phase 2: Clarification (T-2 สัปดาห์) +┌─────────────────────────────────────────────────────────┐ +│ แต่ละองค์กรส่ง Comments / ข้อสงสัย กลับมา │ +│ NAP ตอบและปรับปรุงเอกสาร (ถ้าจำเป็น) │ +│ ระบุ Open Issues และ Resolution │ +└─────────────────────────────────────────────────────────┘ + ↓ +Phase 3: UAT (T-2 ถึง T-1 สัปดาห์) +┌─────────────────────────────────────────────────────────┐ +│ แต่ละองค์กรทดสอบบน Staging ตาม AC Scenarios │ +│ Internal Trainer นำทีมทำ Hands-on Scenario 1-3 │ +│ บันทึก Issues ใน Bug Tracker │ +└─────────────────────────────────────────────────────────┘ + ↓ +Phase 4: Sign-off (T-1 สัปดาห์) +┌─────────────────────────────────────────────────────────┐ +│ ทุก P0/P1 Issues ถูก Fix แล้ว │ +│ P2/P3 Issues มี Workaround หรือ Timeline Fix │ +│ ตัวแทนแต่ละองค์กรลงนาม (Section 1.5) │ +└─────────────────────────────────────────────────────────┘ + ↓ +Go-Live ✅ +``` + +--- + +### 1.4 Sign-off Criteria (เกณฑ์การอนุมัติ) + +**ต้องผ่านทั้งหมดก่อน Sign-off:** + +#### Functional Requirements +- [ ] AC-AUTH-001~005 ผ่าน (Authentication) +- [ ] AC-ADMIN-001~005 ผ่าน (User & Org Management) +- [ ] AC-CORR-001~002 ผ่าน (Correspondence Core) +- [ ] AC-RFA-001~003 ผ่าน (RFA Core) +- [ ] AC-WF-001~003 ผ่าน (Workflow Engine) +- [ ] AC-DN-001 ผ่าน (Document Number Concurrent) +- [ ] AC-STOR-001 ผ่าน (File Storage + ClamAV) + +#### Security & Compliance +- [ ] AC-SEC-001~005 ผ่าน (OWASP Top 10 Security) +- [ ] AC-AUDIT-001 ผ่าน (Audit Log Coverage) +- [ ] Penetration Test ผ่าน (Pre Go-Live) + +#### Performance +- [ ] AC-PERF-001 ผ่าน (Response Time < 200ms P90) +- [ ] AC-PERF-003 ผ่าน (Doc Number Concurrent Safe) + +#### Operations +- [ ] AC-DATA-001 ผ่าน (Backup & DR Test) +- [ ] Monitoring Stack ทำงาน (Grafana แสดง Metrics) +- [ ] Alerting ตั้งค่าแล้ว (PagerDuty/Slack หรือ LINE) + +#### Readiness +- [ ] Training ทุก Role เสร็จแล้ว (>90% Attendance) +- [ ] User Accounts ทุกองค์กรสร้างแล้ว +- [ ] Support LINE Group พร้อม +- [ ] ไม่มี Open P0/P1 Issues + +--- + +### 1.5 🖊️ Stakeholder Sign-off Table + +> **คำชี้แจง:** การลงนามในตารางนี้หมายถึง ตัวแทนองค์กรได้อ่าน รับทราบ และเห็นชอบกับ: +> 1. Feature Scope ของ LCBP3-DMS v1.8.0 ตามที่อธิบายใน `specs/01-Requirements/` +> 2. Acceptance Criteria ตามที่กำหนดใน `01-05-acceptance-criteria.md` +> 3. Risk Register และ Mitigation Plan ในเอกสารนี้ (ส่วนที่ 2) +> 4. ยืนยันว่าทีมงานขององค์กรได้รับการ Training และพร้อม Go-Live + +| Organization | ตัวแทน | ตำแหน่ง | ลายมือชื่อ | วันที่ | หมายเหตุ | +|-------------|--------|---------|----------|-------|---------| +| **กทท.** | | | | | | +| **สค.** | | | | | | +| **TEAM** | | | | | | +| **คคง.** | | | | | | +| **ผรม.** | | | | | | +| **NAP** | Nattanin P. | System Architect | | | | + +**เงื่อนไข Go-Live:** +- ต้องได้รับ Sign-off จากอย่างน้อย **4 จาก 5 องค์กร** (กทท., สค., TEAM, คคง./ผรม. อย่างน้อย 1) +- กทท. **ต้องลงนาม** ในฐานะ Project Owner (Mandatory) +- หาก < 4 ลายเซ็น → ต้องนัด Emergency Review ก่อน Go-Live + +--- + +### 1.6 Open Issues Log (Pre Sign-off) + +> เพิ่ม Issues ที่พบระหว่าง UAT ที่นี่ ก่อน Sign-off + +| # | Issue | Priority | หน่วยงานที่พบ | Status | Resolution / Timeline | +|---|-------|---------|--------------|--------|----------------------| +| — | *ยังไม่มี Issue (UAT ยังไม่เริ่ม)* | — | — | — | — | + +--- + +## ส่วนที่ 2: Risk Management + +### 2.1 Risk Assessment Matrix + +``` + │ ผลกระทบ (Impact) + │ ต่ำ (1) ปานกลาง (2) สูง (3) วิกฤต (4) +───────────┼──────────────────────────────────────────────── +โอกาส สูง │ 🟡 M 🟠 H 🔴 C 🔴 C +เกิด กลาง│ 🟢 L 🟡 M 🟠 H 🔴 C +(Prob) ต่ำ │ 🟢 L 🟢 L 🟡 M 🟠 H + +🔴 C = Critical 🟠 H = High 🟡 M = Medium 🟢 L = Low +``` + +| Level | Action Required | +|-------|----------------| +| 🔴 Critical | แก้ก่อน Go-Live — Blocker | +| 🟠 High | ต้องมี Mitigation Plan ก่อน Go-Live | +| 🟡 Medium | ต้องมี Contingency Plan | +| 🟢 Low | Monitor + Document | + +--- + +### 2.2 Risk Register + +#### 🔴 CRITICAL — ต้องแก้ก่อน Go-Live + +--- + +**RISK-001: ผู้ใช้ปฏิเสธการเปลี่ยนแปลง (User Adoption Failure)** + +| Attribute | Detail | +|-----------|--------| +| **Category** | People / Change Management | +| **Probability** | สูง (3) — คนที่คุ้นชิน Email มักต้านระบบใหม่ | +| **Impact** | วิกฤต (4) — ระบบดีแค่ไหนก็ไร้ประโยชน์ถ้าคนไม่ใช้ | +| **Level** | 🔴 Critical (3×4=12) | +| **Trigger Signs** | Login Rate < 50% ในสัปดาห์แรก, Support Tickets > 30/วัน | + +**Mitigation (ก่อน Go-Live):** +- Training ทุก Role ครบตาม `00-06-training-plan.md` +- Train-the-Trainer ทุกองค์กร (Internal Champion) +- Demo Session ก่อน Go-Live: แสดงว่าระบบช่วยลดงานจริง +- ผู้บริหารทุกองค์กร Endorse การใช้ระบบใหม่อย่างเป็นทางการ + +**Contingency (ถ้าเกิดขึ้น):** +- Hypercare Period: เพิ่ม NAP On-site Support 1 สัปดาห์แรก +- "Buddy System": Internal Trainer นั่งข้างๆ User ใหม่ 2-3 วันแรก +- Quick Win Campaign: รางวัล/การยอมรับสำหรับ "First 10 Submitters" + +**Owner:** Nattanin P. + Internal Trainers ทุกองค์กร + +--- + +**RISK-002: Data Migration Legacy ผิดพลาดหรือล่าช้า** + +| Attribute | Detail | +|-----------|--------| +| **Category** | Technical / Data | +| **Probability** | สูง (3) — ข้อมูลเก่ามักมี Format ไม่สม่ำเสมอ | +| **Impact** | สูง (3) — เอกสารเก่าหาย/ผิด → ความน่าเชื่อถือระบบลดลง | +| **Level** | 🔴 Critical (3×3=9) | +| **Trigger Signs** | Migration Error Rate > 5%, Duration > กำหนด + 2 สัปดาห์ | + +**Mitigation (ก่อน Go-Live):** +- กำหนด Legacy Data Scope ที่ชัดเจน (ดู Gap 7): วันที่เริ่มต้น, ประเภทเอกสาร +- Test Migration บน Staging ก่อน (Dry Run 3 รอบ) +- Validation Script ตรวจ Record Count + Sample Check หลัง Migrate +- เก็บ Legacy System ไว้ Read-only อย่างน้อย 3 เดือน + +**Contingency (ถ้าเกิดขึ้น):** +- Rollback Plan: เปิด Legacy System กลับมา Operate แบบ Parallel +- Manual Entry Team: กำหนดทีม Manual Key-in เอกสาร Critical ที่ Migrate ไม่ได้ +- Timeline Extension: เลื่อน Go-Live ได้สูงสุด 4 สัปดาห์ ถ้า Migration ล้มเหลว > 20% + +**Owner:** Nattanin P. (Migration Lead) + สค. (Data Provider) + +--- + +**RISK-003: Security Breach / Unauthorized Access** + +| Attribute | Detail | +|-----------|--------| +| **Category** | Security | +| **Probability** | ต่ำ (1) — Internal Network, Authentication แข็ง | +| **Impact** | วิกฤต (4) — ข้อมูลโครงการ Confidential รั่วไหล | +| **Level** | 🟠 High (1×4=4) → **ยก Priority เพราะ Impact สูงมาก** | +| **Trigger Signs** | Failed Login Spike, Unauthorized 403 Burst, File Access Anomaly | + +**Mitigation (ก่อน Go-Live):** +- Penetration Test โดยทีมภายนอก ก่อน Go-Live +- Security Checklist `ADR-016` ผ่านทั้งหมด +- ClamAV Virus Scan ทุกไฟล์อัปโหลด +- Network Isolation: Backend ไม่ expose ตรงสู่ Internet +- JWT + CASL RBAC + Helmet.js + Rate Limiting ครบ + +**Contingency (ถ้าเกิดขึ้น):** +- Incident Response Plan: ปิดระบบ + แจ้ง กทท. ภายใน 1 ชั่วโมง +- Audit Log ทุก Access → ตรวจ Forensics ได้ +- Password Reset Force ทุก User ที่อาจได้รับผลกระทบ +- แจ้ง DPA (PDPA Compliance) ถ้าข้อมูลส่วนบุคคลรั่วไหล + +**Owner:** Nattanin P. (Security) + กทท. IT (Infrastructure) + +--- + +#### 🟠 HIGH — ต้องมี Mitigation Plan ก่อน Go-Live + +--- + +**RISK-004: Infrastructure Downtime (QNAP / Docker)** + +| Attribute | Detail | +|-----------|--------| +| **Category** | Infrastructure / Operations | +| **Probability** | กลาง (2) — Hardware ล้มเหลวได้ | +| **Impact** | สูง (3) — ระบบใช้งานไม่ได้ ส่งผลต่อ Deadline เอกสาร | +| **Level** | 🟠 High (2×3=6) | +| **Trigger Signs** | Uptime Alert < 99.5%, Container Crash, Disk Full | + +**Mitigation:** +- Docker Health Check + Auto-restart Policy ทุก Container +- Monitoring: Prometheus + Grafana Alerts (Slack/LINE) +- Database Backup ทุกวัน (MariaDB Dump + Volume Snapshot) +- RTO < 4 ชั่วโมง, RPO < 1 ชั่วโมง ตาม ADR-015 + +**Contingency:** +- ASUSTOR NAS พร้อม Rollover ถ้า QNAP ล้ม (Manual Process) +- Runbook: `specs/04-Infrastructure-OPS/` สำหรับ Common Failure Scenarios +- Emergency Contact: ทีม QNAP Support + NAP On-call + +**Owner:** Nattanin P. (DevOps) + กทท. IT (Hardware) + +--- + +**RISK-005: Workflow DSL Configuration ผิดพลาด** + +| Attribute | Detail | +|-----------|--------| +| **Category** | Technical / Configuration | +| **Probability** | กลาง (2) — DSL ซับซ้อน, Config เยอะ | +| **Impact** | สูง (3) — Workflow เดินผิด → เอกสารติดอยู่ในระบบ | +| **Level** | 🟠 High (2×3=6) | +| **Trigger Signs** | Workflow State ไม่เปลี่ยน, User ร้องเรียนว่า Approve ไม่ได้ | + +**Mitigation:** +- UAT ทดสอบ Workflow ทุก Document Type จนครบ (ตาม AC-WF-001~006) +- Force Proceed สำหรับ Document Control เป็น Safety Valve +- Workflow DSL ถูก Version Control (Git) → Rollback ได้ +- Unit Test ครอบคลุม Transition ทุก State ใน DSL + +**Contingency:** +- Force Proceed: Document Control ข้าม Step ที่ติดขัดได้ทันที +- Admin สามารถ Edit Workflow Definition + Force Re-evaluate ได้ +- Hotfix Deploy ภายใน 24 ชั่วโมง สำหรับ Bug Priority P1 + +**Owner:** Nattanin P. (Workflow Dev) + +--- + +**RISK-006: Document Number Duplication (Race Condition)** + +| Attribute | Detail | +|-----------|--------| +| **Category** | Technical / Data Integrity | +| **Probability** | ต่ำ (1) — Redis Redlock + Optimistic Lock ป้องกัน | +| **Impact** | วิกฤต (4) — เลขซ้ำทำให้ระบบไม่น่าเชื่อถือ | +| **Level** | 🟠 High (1×4=4) | +| **Trigger Signs** | Duplicate Key Error ใน Document Numbering Log | + +**Mitigation:** +- Redis Redlock + DB Optimistic Locking (ADR-002) +- Two-Phase Commit (Reserve → Confirm) +- Load Test: 50 concurrent requests → Assert ไม่มี Duplicate (AC-PERF-003) +- Unique Constraint ระดับ DB เป็น Last Resort + +**Contingency:** +- DB Constraint ป้องกัน Record Duplicate จาก SQL Level +- Audit Log บันทึกทุก Operation → ตรวจสอบและ Correct ได้ +- Admin API: Void + Re-issue เลขที่ผิดพลาด + +**Owner:** Nattanin P. (Backend Dev) + +--- + +#### 🟡 MEDIUM — ต้องมี Contingency Plan + +--- + +**RISK-007: Email / LINE Notification Delivery Failure** + +| Attribute | Detail | +|-----------|--------| +| **Category** | Integration | +| **Probability** | กลาง (2) — Email Server / LINE API อาจมีปัญหา | +| **Impact** | ปานกลาง (2) — User ไม่รู้มีงาน → Delay | +| **Level** | 🟡 Medium (2×2=4) | + +**Mitigation:** BullMQ Retry 3 ครั้ง + Dead Letter Queue + In-App Notification Fallback + +**Contingency:** ผู้ใช้ยังสามารถดู "My Tasks" บน Dashboard ได้โดยไม่ต้องรอ Notification + +**Owner:** Nattanin P. + +--- + +**RISK-008: Search Index Out of Sync (Elasticsearch)** + +| Attribute | Detail | +|-----------|--------| +| **Category** | Technical | +| **Probability** | กลาง (2) — Index lag เกิดได้ | +| **Impact** | ปานกลาง (2) — ค้นหาไม่เห็นเอกสารใหม่ชั่วคราว | +| **Level** | 🟡 Medium (2×2=4) | + +**Mitigation:** Eventual Consistency — Index ทันที หลัง Document Submit (BullMQ Job) + +**Contingency:** Re-index ได้โดย Admin ผ่าน API; Filter-based search ยังใช้ได้แม้ ES ล่ม + +**Owner:** Nattanin P. + +--- + +**RISK-009: Scope Creep จาก Stakeholders ระหว่าง UAT** + +| Attribute | Detail | +|-----------|--------| +| **Category** | Project Management | +| **Probability** | สูง (3) — UAT มักทำให้เห็น Feature ใหม่ที่อยาก | +| **Impact** | ปานกลาง (2) — Delay Go-Live ถ้าไม่จัดการ | +| **Level** | 🟡 Medium (3×2=6) | + +**Mitigation:** +- ใช้ Acceptance Criteria (`01-05`) เป็น Scope Gate — ถ้าไม่อยู่ใน AC → Phase 2 +- Change Request Process: ทุก Change Request ต้องผ่าน PO Review ก่อน Accept +- "Parking Lot" List สำหรับ Feature ที่ดีแต่ไม่ใช่ MVP + +**Contingency:** +- Emergency Change: กรณีที่ Change มีผล Business Critical → PO + กทท. ตัดสิน +- Timeline Extension: ≤ 2 สัปดาห์ สำหรับ Critical Change ที่ทุกฝ่ายเห็นชอบ + +**Owner:** Nattanin P. (PO) + +--- + +**RISK-010: Third-party Service Dependency (ClamAV / Redis / Elasticsearch)** + +| Attribute | Detail | +|-----------|--------| +| **Category** | Technical / Infrastructure | +| **Probability** | ต่ำ (1) — On-Premise, ไม่ขึ้น Internet | +| **Impact** | สูง (3) — ระบบส่วนหนึ่งหยุดทำงาน | +| **Level** | 🟡 Medium (1×3=3) | + +**Mitigation:** Circuit Breaker Pattern — ถ้า Service รอง (Search, Notification) ล่ม → Core CRUD ทำงานต่อ (Graceful Degradation) + +**Contingency:** Runbook สำหรับ Restart แต่ละ Container แยกกัน + +**Owner:** Nattanin P. + +--- + +#### 🟢 LOW — Monitor & Document + +| Risk | Description | Owner | +|------|-------------|-------| +| **RISK-011** | ClamAV False Positive — ปฏิเสธไฟล์ปกติ | Nattanin (Whitelist Update) | +| **RISK-012** | Browser Compatibility — ระบบไม่ทำงานบน IE/Old Safari | Nattanin (Modern Browser Policy) | +| **RISK-013** | Large File Upload Timeout (>100MB) | Nattanin (Nginx Timeout Config) | +| **RISK-014** | User กรอกข้อมูลผิด Format แล้วเข้าใจผิดว่าระบบ Bug | Training (FAQ ข้อที่พบบ่อย) | +| **RISK-015** | Monitoring Stack (Grafana) ล่มทำให้ไม่เห็น Metrics | Nattanin (Alert ผ่าน Uptime Kuma) | + +--- + +### 2.3 Risk Summary Dashboard + +| Risk ID | Description | Level | Owner | Status | +|---------|-------------|-------|-------|--------| +| RISK-001 | User Adoption Failure | 🔴 Critical | NAP + Trainers | 🔄 Mitigating | +| RISK-002 | Data Migration Error | 🔴 Critical | NAP + สค. | 🔄 Mitigating | +| RISK-003 | Security Breach | 🔴 Critical→🟠 High | NAP + กทท. IT | 🔄 Mitigating | +| RISK-004 | Infrastructure Downtime | 🟠 High | NAP + กทท. IT | 🔄 Mitigating | +| RISK-005 | Workflow Config Error | 🟠 High | NAP | ✅ AC Test Coverage | +| RISK-006 | Doc Number Duplicate | 🟠 High | NAP | ✅ Load Test + DB Constraint | +| RISK-007 | Notification Failure | 🟡 Medium | NAP | ✅ BullMQ Retry + Fallback | +| RISK-008 | ES Index Out of Sync | 🟡 Medium | NAP | ✅ Eventual Consistency | +| RISK-009 | Scope Creep | 🟡 Medium | NAP (PO) | 🔄 AC as Gate | +| RISK-010 | 3rd Party Service Failure | 🟡 Medium | NAP | ✅ Graceful Degradation | +| RISK-011~015 | Low Risks (5 items) | 🟢 Low | NAP | 📋 Documented | + +--- + +### 2.4 Risk Response Timeline + +``` +ปัจจุบัน → T-4 สัปดาห์ (Pre-UAT): + ├── RISK-001: Train-the-Trainer เสร็จ + ├── RISK-002: Migration Dry Run ครั้งที่ 1 เสร็จ + ├── RISK-003: Penetration Test เริ่ม + └── RISK-005: Workflow UAT เริ่ม + +T-3 → T-2 สัปดาห์ (UAT): + ├── RISK-003: PenTest Report ได้รับ + Fix + ├── RISK-002: Migration Dry Run ครั้งที่ 2 เสร็จ + ├── RISK-006: Load Test 50 Concurrent เสร็จ + └── RISK-009: Scope Creep — PO ตัดสิน In/Out + +T-1 สัปดาห์ (Pre Go-Live): + ├── RISK-001: Training ครบทุก Group + ├── RISK-004: DR Test (Backup Restore) เสร็จ + └── Sign-off ทุกองค์กร (Section 1.5) + +Go-Live: + └── RISK-001~010: Active Monitoring (Hypercare) +``` + +--- + +## ส่วนที่ 3: Change Control Process + +### 3.1 Change Request Types + +| Type | ตัวอย่าง | ผู้อนุมัติ | Timeline | +|------|---------|----------|---------| +| **Emergency Fix** | Security Bug, System Down | NAP PO + กทท. | < 4 ชั่วโมง | +| **Critical Change** | Business Rule ผิดพลาด Critical | NAP PO + 2 Stakeholders | < 2 วัน | +| **Standard Change** | UI Improvement, Minor Feature | NAP PO | Sprint (2 สัปดาห์) | +| **Phase Change** | Feature ใหม่นอก MVP Scope | NAP PO + ทุกองค์กร | Phase 2 Planning | + +### 3.2 Change Request Form (Template) + +```markdown +## Change Request #[CR-XXX] + +**วันที่:** +**ผู้ขอ:** +**Organization:** +**Priority:** Emergency / Critical / Standard + +### คำอธิบาย +[อธิบายการเปลี่ยนแปลงที่ต้องการ] + +### เหตุผลธุรกิจ +[ทำไมต้องเปลี่ยน? ผลกระทบถ้าไม่เปลี่ยน?] + +### Acceptance Criteria ของ Change นี้ +[เกณฑ์การ "Done" ของ Change นี้] + +### Impact Assessment +- ผลกระทบต่อ Features อื่น: +- ผลกระทบต่อ Timeline: +- RP&DO (Risk): + +### Decision +- [ ] Approved → Sprint: ___ +- [ ] Deferred → Phase: ___ +- [ ] Rejected → เหตุผล: ___ + +**Approved by:** _______________ Date: ___________ +``` + +--- + +## ส่วนที่ 4: Escalation Path + +``` +ปัญหา Operational ทั่วไป + ↓ User (Internal Trainer / Org Admin) + ↓ ไม่แก้ได้ใน 4 ชั่วโมง +NAP Support (Nattanin) — LINE / Email + ↓ ไม่แก้ได้ใน 24 ชั่วโมง (P1) หรือ 48 ชั่วโมง (P2) +Project Management Level (สค. + กทท.) + ↓ ไม่แก้ได้ใน 72 ชั่วโมง หรือ กระทบ Milestone +Executive Level (ผู้บริหาร กทท.) + Decision: Emergency Fix / Rollback / Scope Change +``` + +--- + +## 📝 Document Control + +- **Version:** 1.0.0 | **Status:** DRAFT — Awaiting Stakeholder Review +- **Created:** 2026-03-11 | **Owner:** Nattanin Peancharoen (PO) +- **Next Review:** T-4 สัปดาห์ก่อน Go-Live (Pre-UAT Review Meeting) +- **Classification:** Confidential — ส่งเฉพาะตัวแทนที่ Sign-off เท่านั้น + +> [!NOTE] +> เมื่อได้รับลายมือชื่อครบทุกองค์กร ให้ Scan และบันทึกฉบับ PDF ไว้ใน +> `specs/00-Overview/signed/00-04-stakeholder-signoff-SIGNED.pdf` diff --git a/specs/00-overview/00-05-kpi-baseline.md b/specs/00-overview/00-05-kpi-baseline.md new file mode 100644 index 0000000..384901d --- /dev/null +++ b/specs/00-overview/00-05-kpi-baseline.md @@ -0,0 +1,564 @@ +# 📊 KPI Baseline Data & Measurement Plan — LCBP3-DMS v1.8.0 + +--- +title: 'KPI Baseline Data, Measurement Methodology, and Success Tracking' +version: 1.0.0 +status: DRAFT — Baseline Collection Pending +owner: Nattanin Peancharoen (Product Owner) +last_updated: 2026-03-11 +related: + - specs/00-Overview/00-03-product-vision.md + - specs/00-Overview/README.md + - specs/01-Requirements/01-05-acceptance-criteria.md + - specs/00-Overview/00-04-stakeholder-signoff-and-risk.md +--- + +> [!IMPORTANT] +> **ต้องเก็บข้อมูล Baseline (As-Is State) ก่อน Go-Live อย่างน้อย T-2 สัปดาห์** +> ข้อมูล Baseline คือ "ตัวเลขก่อนระบบ" — ใช้เปรียบเทียบหลัง Go-Live เพื่อพิสูจน์ Value ของระบบ + +--- + +## 1. 🎯 KPI Framework Overview + +``` +Business Goal → Success Metric → KPI → Baseline → Target → Measurement Method +``` + +### Category ของ KPIs + +| Category | วัดอะไร | Primary Audience | +|----------|--------|----------------| +| **Efficiency** | ลดเวลาและลดงานซ้ำซ้อน | PM, ผู้บริหาร | +| **Data Quality** | ความถูกต้องและสมบูรณ์ของข้อมูล | Document Control | +| **Adoption** | การใช้งานระบบจริง | PO, IT | +| **System Performance** | ความเสถียรและความเร็ว | Dev, IT | +| **User Satisfaction** | ความพึงพอใจของผู้ใช้ | PO, Management | +| **Security/Compliance** | ความปลอดภัยและการตรวจสอบ | กทท., Auditor | + +--- + +## 2. 📋 KPI Register พร้อม Baseline + +### KPI-EFF-001: RFA Cycle Time (วัฏจักรอนุมัติ) +**Category:** Efficiency | **Priority:** 🔴 Critical + +| Attribute | Value | +|-----------|-------| +| **คำอธิบาย** | เวลาเฉลี่ยตั้งแต่ Contractor ส่ง RFA จนถึงได้รับคำตอบสุดท้าย | +| **หน่วย** | วัน (Calendar Days) | +| **Baseline (As-Is)** | 📋 **รอเก็บข้อมูล** — ประมาณ 14–21 วัน (จาก Email เดิม) | +| **Target (Month 1)** | ≤ 7 วัน | +| **Target (Month 3)** | ≤ 5 วัน | +| **Target (Month 6)** | ≤ 3 วัน | +| **วิธีเก็บ Baseline** | Analyze Email Thread: วัน Submit Email → วัน Reply สุดท้าย (30 RFAs ล่าสุด) | +| **วิธีวัดหลัง Go-Live** | `SELECT AVG(DATEDIFF(closed_date, submitted_date)) FROM workflow_instances WHERE type='RFA' AND status='CLOSED'` | +| **Frequency** | Monthly Report | +| **Owner** | PO + สค. (Data Collection) | + +**ข้อมูล Baseline ที่ต้องเก็บ:** +``` +แบบฟอร์ม Baseline RFA: +- เลขที่ RFA (เดิม): +- วันที่ส่ง (Email): +- วันที่ได้รับคำตอบ: +- ระยะเวลา (วัน): +- ผลลัพธ์: Approved / AW Comments / Rejected +- องค์กรที่ส่ง: +- Discipline: +``` + +--- + +### KPI-EFF-002: Document Number Error Rate +**Category:** Efficiency + Data Quality | **Priority:** 🔴 Critical + +| Attribute | Value | +|-----------|-------| +| **คำอธิบาย** | % ของเลขเอกสารที่ผิดพลาด (ซ้ำ, ผิด Format, ต้องยกเลิกและออกใหม่) | +| **หน่วย** | % จากเอกสารทั้งหมดที่ออกในเดือนนั้น | +| **Baseline (As-Is)** | 📋 **รอเก็บข้อมูล** — ประมาณ 5–15% (จากการนับมือ) | +| **Target** | 0% (Zero Tolerance — ระบบ Auto-Number) | +| **วิธีเก็บ Baseline** | สัมภาษณ์ Document Control แต่ละองค์กร + นับจากเอกสาร 3 เดือนล่าสุด | +| **วิธีวัดหลัง Go-Live** | Count `document_number_reservations.status = 'CANCELLED'` / Total Issued | +| **Frequency** | Monthly | +| **Owner** | Document Control (Baseline) + System (Auto-measure) | + +--- + +### KPI-EFF-003: Time to Find Document (ค้นหาเอกสาร) +**Category:** Efficiency | **Priority:** 🟠 High + +| Attribute | Value | +|-----------|-------| +| **คำอธิบาย** | เวลาเฉลี่ยที่ใช้ค้นหาเอกสารที่ต้องการ | +| **หน่วย** | นาที | +| **Baseline (As-Is)** | 📋 **รอเก็บข้อมูล** — ประมาณ 15–30 นาที (ผ่าน Email/Drive แบบเดิม) | +| **Target** | < 1 นาที (ผ่าน Elasticsearch) | +| **วิธีเก็บ Baseline** | User Survey + Observation: จับเวลาค้นหาเอกสาร 5 ครั้ง × 5 User | +| **วิธีวัดหลัง Go-Live** | Search Response Time จาก Elasticsearch API Metrics + User Survey | +| **Frequency** | Quarterly Survey + Continuous System Metric | +| **Owner** | PO | + +--- + +### KPI-EFF-004: Manual Follow-up Calls Reduction +**Category:** Efficiency | **Priority:** 🟠 High + +| Attribute | Value | +|-----------|-------| +| **คำอธิบาย** | จำนวนครั้งที่ต้องโทร/Line เพื่อถามสถานะเอกสารต่อสัปดาห์ | +| **หน่วย** | ครั้ง/สัปดาห์ (per Document Control) | +| **Baseline (As-Is)** | 📋 **รอเก็บข้อมูล** — บันทึก 2 สัปดาห์ก่อน Go-Live | +| **Target** | ลดลง > 80% (Real-time tracking ช่วย) | +| **วิธีเก็บ Baseline** | Document Control บันทึกจำนวน Follow-up Calls ต่อวัน 2 สัปดาห์ก่อน Go-Live | +| **วิธีวัดหลัง Go-Live** | Survey (Month 1, Month 3): "สัปดาห์ที่ผ่านมาโทรถามสถานะเอกสารกี่ครั้ง?" | +| **Frequency** | Monthly Survey | +| **Owner** | PO + Document Control | + +--- + +### KPI-ADOPT-001: User Adoption Rate (Login Rate) +**Category:** Adoption | **Priority:** 🔴 Critical + +| Attribute | Value | +|-----------|-------| +| **คำอธิบาย** | % ของ Active Users ที่ Login เข้าระบบอย่างน้อย 1 ครั้ง/วัน | +| **หน่วย** | % จาก Total Active User Accounts | +| **Baseline** | N/A (ระบบใหม่ — ไม่มี Baseline) | +| **Target Week 1** | > 50% | +| **Target Month 1** | > 70% | +| **Target Month 3** | > 90% | +| **วิธีวัด** | `SELECT COUNT(DISTINCT user_id) / total_users FROM audit_logs WHERE action='USER_LOGIN' AND created_at >= today-1` | +| **Dashboard** | Grafana Panel: "Daily Active Users" | +| **Frequency** | Daily (Hypercare) → Weekly (Month 2+) | +| **Owner** | PO + IT | + +--- + +### KPI-ADOPT-002: Feature Adoption Rate (Core Workflows) +**Category:** Adoption | **Priority:** 🟠 High + +| Attribute | Value | +|-----------|-------| +| **คำอธิบาย** | % ของ Active Users ที่ใช้ Core Feature จริง (ไม่ใช่แค่ Login) | +| **หน่วย** | % | +| **Target Month 1** | > 50% ใช้ Dashboard + Search | +| **Target Month 3** | > 80% ใช้ Workflow (Submit/Approve อย่างน้อย 1 ครั้ง) | +| **วิธีวัด** | Audit Log Analysis: count unique users ที่มี action = 'DOCUMENT_SUBMITTED' หรือ 'WORKFLOW_TRANSITION' | +| **Frequency** | Monthly | +| **Owner** | PO | + +--- + +### KPI-ADOPT-003: Support Ticket Volume Trend +**Category:** Adoption | **Priority:** 🟠 High + +| Attribute | Value | +|-----------|-------| +| **คำอธิบาย** | จำนวน Support Tickets ต่อสัปดาห์ (Trend ลดลง = ระบบ Usable มากขึ้น) | +| **หน่วย** | Tickets/สัปดาห์ | +| **Baseline** | N/A | +| **Target Week 1** | < 30 tickets (Hypercare acceptable) | +| **Target Month 1** | < 15 tickets | +| **Target Month 3** | < 5 tickets | +| **วิธีวัด** | LINE Group message count (manual) หรือ Helpdesk ticketing tool ถ้ามี | +| **Frequency** | Weekly | +| **Owner** | NAP Support | + +--- + +### KPI-PERF-001: API Response Time (P90) +**Category:** System Performance | **Priority:** 🔴 Critical + +| Attribute | Value | +|-----------|-------| +| **คำอธิบาย** | 90th Percentile response time ของ API requests ทั้งหมด | +| **หน่วย** | Milliseconds | +| **Target** | < 200ms (P90) ตาม AC-PERF-001 | +| **Alert Threshold** | > 500ms ต่อเนื่อง 5 นาที → Alert | +| **Critical** | > 1000ms ต่อเนื่อง 1 นาที → PagerDuty | +| **วิธีวัด** | Prometheus + Grafana: `histogram_quantile(0.9, rate(http_request_duration_seconds_bucket[5m]))` | +| **Frequency** | Continuous (Real-time dashboard) | +| **Owner** | NAP Dev | + +--- + +### KPI-PERF-002: System Uptime +**Category:** System Performance | **Priority:** 🔴 Critical + +| Attribute | Value | +|-----------|-------| +| **คำอธิบาย** | % ของเวลาที่ระบบพร้อมใช้งาน (ในเวลาทำงาน 08:00-18:00) | +| **หน่วย** | % | +| **Target** | ≥ 99.5% (ตาม ADR-015) | +| **คำนวณ** | ≥ 99.5% = Downtime ≤ 2.16 ชม./เดือน | +| **วิธีวัด** | Uptime Kuma + Prometheus: Health Check Endpoint | +| **Frequency** | Real-time + Monthly SLA Report | +| **Owner** | NAP Dev + IT | + +**Uptime Calculation Template:** +``` +เดือน: __________ +Total Hours (08:00-18:00, วันทำงาน): ___ ชั่วโมง +Downtime รวม: ___ นาที +Uptime %: ((Total Hours × 60 - Downtime) / (Total Hours × 60)) × 100 +``` + +--- + +### KPI-PERF-003: File Scan Success Rate +**Category:** Security | **Priority:** 🟠 High + +| Attribute | Value | +|-----------|-------| +| **คำอธิบาย** | % ของไฟล์อัปโหลดที่ถูก Scan โดย ClamAV สำเร็จ (ไม่ใช่ Skip หรือ Error) | +| **หน่วย** | % | +| **Target** | ≥ 99.9% (ทุกไฟล์ต้อง Scan) | +| **วิธีวัด** | Audit Log: COUNT(action='FILE_VIRUS_SCAN_COMPLETED') / COUNT(action='FILE_UPLOADED') | +| **Frequency** | Daily Check | +| **Owner** | NAP Dev | + +--- + +### KPI-SAT-001: User Satisfaction Score (CSAT) +**Category:** User Satisfaction | **Priority:** 🟠 High + +| Attribute | Value | +|-----------|-------| +| **คำอธิบาย** | คะแนนความพึงพอใจโดยรวมของผู้ใช้ระบบ (1–5) | +| **หน่วย** | คะแนน (1.0–5.0) | +| **Baseline** | N/A | +| **Target Month 1** | ≥ 3.5/5.0 (ยังอยู่ใน Learning Curve) | +| **Target Month 3** | ≥ 4.0/5.0 | +| **Target Month 6** | ≥ 4.3/5.0 | +| **วิธีวัด** | Google Forms Survey (แบบสอบถาม) | +| **Frequency** | Month 1, Month 3, Month 6 | +| **Owner** | PO | + +--- + +### KPI-SAT-002: System Ease of Use Score (SUS-lite) +**Category:** User Satisfaction | **Priority:** 🟡 Medium + +| Attribute | Value | +|-----------|-------| +| **คำอธิบาย** | "ระบบนี้ง่ายต่อการใช้งาน" (1=ไม่เห็นด้วยมาก, 5=เห็นด้วยมาก) | +| **หน่วย** | คะแนน (1.0–5.0) | +| **Target Month 3** | ≥ 4.0/5.0 | +| **วิธีวัด** | ใน Survey เดียวกับ KPI-SAT-001 | +| **Frequency** | Month 1, Month 3 | +| **Owner** | PO | + +--- + +### KPI-SEC-001: Audit Log Coverage Rate +**Category:** Security/Compliance | **Priority:** 🔴 Critical + +| Attribute | Value | +|-----------|-------| +| **คำอธิบาย** | % ของ User Actions ที่ถูกบันทึกใน Audit Log | +| **หน่วย** | % | +| **Target** | 100% (ทุก Action ต้องบันทึก — AC-AUDIT-001) | +| **วิธีวัด** | Spot Check: ทำ Action → ตรวจ audit_logs ว่ามี Record หรือไม่ (Manual QA ก่อน Go-Live) | +| **Frequency** | Pre Go-Live Audit + Monthly Spot Check | +| **Owner** | NAP Dev | + +--- + +### KPI-SEC-002: Security Incident Count +**Category:** Security | **Priority:** 🔴 Critical + +| Attribute | Value | +|-----------|-------| +| **คำอธิบาย** | จำนวน Security Incidents ที่ตรวจพบ (Unauthorized access, Virus, etc.) | +| **หน่วย** | จำนวนครั้ง | +| **Target** | 0 (Zero Incidents ในเวลาทำงาน) | +| **Threshold** | > 0 Critical → Immediate escalation | +| **วิธีวัด** | Security Audit Log Dashboard (Grafana) | +| **Frequency** | Daily Check (Hypercare) → Weekly | +| **Owner** | NAP Dev + IT | + +--- + +## 3. 📅 Baseline Data Collection Plan + +### T-4 สัปดาห์ก่อน Go-Live: เตรียม + +- [ ] ออกแบบ Survey Form สำหรับ User Baseline +- [ ] เตรียม Template บันทึกข้อมูล Email-based RFAs +- [ ] นัด Document Control แต่ละองค์กรเพื่อเก็บข้อมูล +- [ ] กำหนด Baseline Period: 3 เดือนย้อนหลัง (ธ.ค. 2568 – ก.พ. 2569) + +### T-3 สัปดาห์: เก็บ Baseline ข้อมูล Process + +**สิ่งที่ต้องเก็บ:** + +``` +📋 BASELINE COLLECTION FORMS: + +Form A: RFA Cycle Time (KPI-EFF-001) +────────────────────────────────── +สัมภาษณ์กับ Document Control แต่ละ Org +เก็บข้อมูล RFA 30 ฉบับล่าสุด (จากระบบเดิม): + +| # | เลข RFA เดิม | วันที่ส่ง | วันที่ตอบ | ระยะเวลา (วัน) | ผลลัพธ์ | +|---|-------------|----------|----------|--------------|--------| +| 1 | | | | | | +... +Average: ___ วัน | Min: ___ | Max: ___ + +Form B: Document Number Error (KPI-EFF-002) +─────────────────────────────────────────── +จากเอกสาร 3 เดือนล่าสุด: +- เอกสารที่ออกทั้งหมด: ___ ฉบับ +- เลขที่ผิดพลาด/ซ้ำ ต้องยกเลิก: ___ ฉบับ +- Error Rate: ___% + +Form C: Follow-up Calls (KPI-EFF-004) +──────────────────────────────────── +Document Control บันทึกเป็นเวลา 2 สัปดาห์: +วันที่ | จำนวนครั้งที่โทรถามสถานะ +... + +Form D: Time to Find Document (KPI-EFF-003) +─────────────────────────────────────────── +สังเกตการณ์ 5 User × 5 ครั้ง: +"ค้นหา [เอกสารที่ระบุ] ใช้เวลากี่นาที?" +| User | ครั้งที่ 1 | 2 | 3 | 4 | 5 | เฉลี่ย | +... +``` + +### T-2 สัปดาห์: เก็บ Baseline ข้อมูล User Perception + +``` +📋 PRE-GO-LIVE USER SURVEY (Google Form) + +Section 1: ปัญหาปัจจุบัน (ก่อนระบบใหม่) +1. "ระบบปัจจุบัน (Email) ให้คะแนนความสะดวก" (1–5): ___ +2. "ฉันใช้เวลาค้นหาเอกสารเฉลี่ยครั้งละ" (นาที): ___ +3. "ข้อปัญหาหลักสูงสุด 3 อันดับ" (checkbox) +4. "ฉันต้องโทรถามสถานะเอกสารสัปดาห์ละ" (ครั้ง): ___ + +Section 2: ความคาดหวังจากระบบใหม่ +5. "สิ่งที่คาดหวังมากที่สุดจากระบบใหม่": (text) +6. "ความกังวลเกี่ยวกับการเปลี่ยนระบบ": (text) +``` + +--- + +## 4. 📊 KPI Dashboard Template + +### Monthly KPI Report Template + +```markdown +# Monthly KPI Report — LCBP3-DMS +Period: [เดือน ปี] | Generated: [วันที่] + +## 🟢 On Track / 🟡 Watch / 🔴 Off Track + +| KPI | Baseline | Target | Actual | Status | Delta | +|-----|---------|--------|--------|--------|-------| +| RFA Cycle Time | ___ วัน | ≤ 5 วัน | ___ วัน | 🟢/🟡/🔴 | ___% | +| Doc Number Error | ___% | 0% | ___% | 🟢/🟡/🔴 | ___% | +| User Adoption | N/A | ≥ 70% | ___% | 🟢/🟡/🔴 | ___% | +| API P90 | N/A | < 200ms | ___ms | 🟢/🟡/🔴 | ___% | +| Uptime | N/A | ≥ 99.5% | ___% | 🟢/🟡/🔴 | ___% | +| CSAT Score | N/A | ≥ 4.0 | ___ | 🟢/🟡/🔴 | ___% | + +## 🔍 Highlights +[Key findings this month] + +## ⚠️ Issues & Actions +| Issue | Impact | Action | Owner | Deadline | +... + +## 📈 Trend Charts +[Link to Grafana Dashboard] +``` + +--- + +## 5. 📈 Target vs. Baseline Summary Table + +| KPI ID | ชื่อ KPI | หน่วย | Baseline | Target M1 | Target M3 | Target M6 | +|--------|---------|------|---------|----------|----------|----------| +| KPI-EFF-001 | RFA Cycle Time | วัน | ~14-21 | ≤ 7 | ≤ 5 | ≤ 3 | +| KPI-EFF-002 | Doc Number Error | % | ~5-15% | < 1% | 0% | 0% | +| KPI-EFF-003 | Time to Find Doc | นาที | ~15-30 | < 3 | < 1 | < 1 | +| KPI-EFF-004 | Follow-up Calls | ครั้ง/สัปดาห์ | ~10-20 | < 10 | < 5 | < 2 | +| KPI-ADOPT-001 | User Adoption | % | N/A | > 50% | > 70% | > 90% | +| KPI-ADOPT-002 | Feature Adoption | % | N/A | > 30% | > 60% | > 80% | +| KPI-ADOPT-003 | Support Tickets | ครั้ง/สัปดาห์ | N/A | < 30 | < 15 | < 5 | +| KPI-PERF-001 | API Response P90 | ms | N/A | < 200 | < 200 | < 200 | +| KPI-PERF-002 | System Uptime | % | N/A | ≥ 99.5% | ≥ 99.5% | ≥ 99.9% | +| KPI-PERF-003 | File Scan Success | % | N/A | 100% | 100% | 100% | +| KPI-SAT-001 | CSAT Score | /5.0 | Survey Pre | ≥ 3.5 | ≥ 4.0 | ≥ 4.3 | +| KPI-SAT-002 | Ease of Use | /5.0 | Survey Pre | ≥ 3.5 | ≥ 4.0 | ≥ 4.2 | +| KPI-SEC-001 | Audit Coverage | % | N/A | 100% | 100% | 100% | +| KPI-SEC-002 | Security Incidents | ครั้ง | N/A | 0 | 0 | 0 | + +--- + +## 6. 🔧 Technical Measurement Implementation + +### Grafana Dashboard Panels (ต้องสร้างก่อน Go-Live) + +```yaml +# Prometheus Metrics to Collect: +panels: + - title: "RFA Cycle Time (Avg)" + query: | + avg( + timestamp(workflow_closed_at) - timestamp(workflow_submitted_at) + ) by (month) WHERE type = 'rfa' + unit: days + + - title: "Daily Active Users" + query: | + count(distinct user_id) FROM audit_logs + WHERE action = 'USER_LOGIN' AND date = today + + - title: "API P90 Response Time" + query: | + histogram_quantile(0.90, + rate(http_request_duration_seconds_bucket[5m]) + ) + unit: ms + alert_threshold: 500 + + - title: "System Uptime (30d)" + query: avg_over_time(up[30d]) * 100 + unit: percent + + - title: "File Virus Scan Queue" + query: bullmq_queue_size{queue="virus-scan"} + + - title: "Support Tickets This Week" + query: custom_metric (manual input) +``` + +### SQL Queries for Business KPIs + +```sql +-- KPI-EFF-001: RFA Cycle Time (ต่อเดือน) +SELECT + DATE_FORMAT(wi.submitted_at, '%Y-%m') AS month, + COUNT(*) AS total_rfas, + AVG(DATEDIFF(wi.closed_at, wi.submitted_at)) AS avg_days, + MIN(DATEDIFF(wi.closed_at, wi.submitted_at)) AS min_days, + MAX(DATEDIFF(wi.closed_at, wi.submitted_at)) AS max_days, + PERCENTILE_CONT(0.50) WITHIN GROUP (ORDER BY DATEDIFF(wi.closed_at, wi.submitted_at)) AS median_days +FROM workflow_instances wi +WHERE wi.document_type = 'RFA' + AND wi.status = 'CLOSED' + AND wi.closed_at IS NOT NULL +GROUP BY DATE_FORMAT(wi.submitted_at, '%Y-%m') +ORDER BY month DESC; + +-- KPI-ADOPT-001: Daily Active Users +SELECT + DATE(created_at) AS date, + COUNT(DISTINCT user_id) AS daily_active_users, + (SELECT COUNT(*) FROM users WHERE is_active = 1) AS total_active_users, + ROUND(COUNT(DISTINCT user_id) * 100.0 / + (SELECT COUNT(*) FROM users WHERE is_active = 1), 1) AS adoption_rate +FROM audit_logs +WHERE action = 'USER_LOGIN' + AND created_at >= DATE_SUB(NOW(), INTERVAL 30 DAY) +GROUP BY DATE(created_at) +ORDER BY date DESC; + +-- KPI-EFF-002: Document Number Error Rate +SELECT + DATE_FORMAT(created_at, '%Y-%m') AS month, + COUNT(*) AS total_reserved, + SUM(CASE WHEN status = 'CANCELLED' THEN 1 ELSE 0 END) AS cancelled, + ROUND(SUM(CASE WHEN status = 'CANCELLED' THEN 1 ELSE 0 END) * 100.0 / COUNT(*), 2) AS error_rate_pct +FROM document_number_reservations +WHERE created_at >= DATE_SUB(NOW(), INTERVAL 6 MONTH) +GROUP BY DATE_FORMAT(created_at, '%Y-%m'); +``` + +--- + +## 7. 📋 User Survey Templates + +### Post Go-Live Survey (Month 1 & Month 3) + +``` +📝 LCBP3-DMS User Satisfaction Survey +Period: [เดือน] | ใช้เวลา: ประมาณ 3 นาที + +Section 1: ภาพรวม +━━━━━━━━━━━━━━━ +Q1. โดยรวม ระบบ LCBP3-DMS ช่วยให้การทำงานของคุณดีขึ้น? + ⬜ 1-ไม่เลย ⬜ 2 ⬜ 3 ⬜ 4 ⬜ 5-ดีขึ้นมาก + +Q2. ระบบนี้ง่ายต่อการใช้งานมากแค่ไหน? + ⬜ 1-ยากมาก ⬜ 2 ⬜ 3 ⬜ 4 ⬜ 5-ง่ายมาก + +Section 2: Feature Specific +━━━━━━━━━━━━━━━━━━━━━━━━ +Q3. Feature ที่คุณใช้บ่อยที่สุด: (checkbox, เลือกได้หลายข้อ) + ⬜ Dashboard ⬜ สร้าง Correspondence ⬜ Review RFA + ⬜ ค้นหาเอกสาร ⬜ Circulation ⬜ ดู Workflow + +Q4. Feature ที่ยังมีปัญหาหรืออยากให้ปรับปรุง: (text) + _______________________________________________ + +Section 3: เปรียบเทียบกับระบบเดิม +━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +Q5. เวลาค้นหาเอกสาร เปรียบกับระบบเดิม: + ⬜ เร็วกว่ามาก ⬜ เร็วกว่านิดหน่อย ⬜ เหมือนเดิม ⬜ ช้ากว่า + +Q6. จำนวนครั้งที่ต้องโทรถามสถานะ เปรียบกับเดิม: + ⬜ น้อยกว่ามาก ⬜ น้อยกว่า ⬜ เหมือนเดิม ⬜ มากกว่า + +Section 4: Open Feedback +━━━━━━━━━━━━━━━━━━━━ +Q7. สิ่งที่คุณชอบมากที่สุดในระบบนี้: _______________ +Q8. สิ่งที่คุณอยากให้ปรับปรุงเร่งด่วนที่สุด: ___________ +Q9. คะแนนรวม (NPS): 0-10 — "คุณจะแนะนำระบบนี้ให้เพื่อนร่วมงาน?" + 0──────────────────10 + [0-6: Detractor] [7-8: Passive] [9-10: Promoter] +``` + +--- + +## 8. 📊 KPI Review Meeting Agenda Template + +```markdown +# LCBP3-DMS Monthly KPI Review — [เดือน ปี] +วันที่: | เวลา: 30 นาที | ผู้เข้าร่วม: PO, IT, Document Control Lead + +## Agenda + +1. KPI Dashboard Review (10 นาที) + - Performance KPIs: Uptime, API Response + - Efficiency KPIs: RFA Cycle Time, Error Rate + - Adoption KPIs: DAU, Feature Adoption + +2. Status Discussion (10 นาที) + - 🔴 Off Track KPIs: root cause + action plan + - 🟡 Watch KPIs: monitoring plan + +3. User Feedback Summary (5 นาที) + - Key themes from support tickets + - Survey results (if applicable) + +4. Actions for Next Month (5 นาที) + - [Action] | [Owner] | [Deadline] + +## Notes / Decisions +``` + +--- + +## 📝 Document Control + +- **Version:** 1.0.0 | **Status:** DRAFT — Baseline Collection Pending +- **Created:** 2026-03-11 | **Owner:** Nattanin Peancharoen +- **Baseline Collection Deadline:** T-2 สัปดาห์ก่อน Go-Live +- **First KPI Review:** T+1 เดือนหลัง Go-Live +- **Classification:** Internal Use Only diff --git a/specs/00-overview/00-06-training-plan.md b/specs/00-overview/00-06-training-plan.md new file mode 100644 index 0000000..26f30b6 --- /dev/null +++ b/specs/00-overview/00-06-training-plan.md @@ -0,0 +1,414 @@ +# 🎓 Training & Change Management Plan — LCBP3-DMS v1.8.0 + +--- +title: 'Training & Change Management Plan' +version: 1.0.0 +status: DRAFT +owner: Nattanin Peancharoen (Product Owner / System Architect) +last_updated: 2026-03-11 +related: + - specs/00-Overview/README.md + - specs/01-Requirements/01-01-objectives.md + - specs/01-Requirements/01-02-business-rules/01-02-01-rbac-matrix.md +--- + +## 1. 🎯 วัตถุประสงค์ + +> **"ระบบที่ดีที่สุดก็ล้มเหลวได้ ถ้าผู้ใช้ไม่รู้วิธีใช้"** + +แผนนี้ครอบคลุม: +1. **Training Curriculum** — หลักสูตรฝึกอบรมแยกต่อ Role +2. **Training Materials** — สื่อและเอกสารการฝึกอบรม +3. **Train-the-Trainer** — กระบวนการเตรียม Trainer ภายในองค์กร +4. **Support Desk Setup** — ระบบ Support หลัง Go-Live +5. **Change Management** — การสื่อสารและรับมือกับ Change + +--- + +## 2. 📅 Training Timeline + +``` +T-4 สัปดาห์ก่อน Go-Live: +├── สร้าง Training Materials ครบ +├── ติดตั้ง Staging Environment สำหรับ Training +└── เตรียม Trainer (Train-the-Trainer) + +T-3 สัปดาห์: +├── Training: Superadmin + Org Admin (ทุกองค์กร) +└── UAT Pre-check กับ Admin ทุกคน + +T-2 สัปดาห์: +├── Training: Document Control (ทุกองค์กร) +└── UAT ทดสอบ Workflow จริงบน Staging + +T-1 สัปดาห์: +├── Training: Engineers / Reviewers / Viewers +├── UAT Sign-off +└── Dry Run Go-Live + +Go-Live Day: +├── Hypercare Support (8:00–18:00 on-call) +└── ทีม Dev พร้อม Hotfix ตลอด + +T+1 เดือน: +├── Hypercare สิ้นสุด +└── Handover ไป Standard Support +``` + +--- + +## 3. 👥 Target Audience & Training Groups + +| Group | Role ในระบบ | ผู้เข้าอบรม | ระยะเวลา | รูปแบบ | +|-------|------------|------------|---------|-------| +| **A** | Superadmin | ทีม NAP (1-2 คน) | 4 ชั่วโมง | 1-on-1 Workshop | +| **B** | Org Admin | 1 คนต่อองค์กร × 5 องค์กร | 3 ชั่วโมง | Group Workshop | +| **C** | Document Control | 1-3 คนต่อองค์กร | 4 ชั่วโมง | Group Workshop | +| **D** | Engineer / Reviewer | หลายคนต่อองค์กร | 2 ชั่วโมง | Group + Self-paced | +| **E** | Viewer / Auditor | ผู้บริหาร + Observer | 1 ชั่วโมง | Video + Quick Guide | + +> **หมายเหตุ:** Train-the-Trainer: แต่ละองค์กรมี Trainer 1 คน ก่อนอบรมองค์กรอื่น + +--- + +## 4. 📚 Training Curriculum per Role + +### 4.1 Group A — Superadmin (4 ชั่วโมง) + +**เป้าหมาย:** ดูแลระบบทั้งหมด, Config Master Data, จัดการ Permission + +| Module | หัวข้อ | เวลา | +|--------|--------|------| +| A1 | System Architecture Overview (ภาพรวมระบบ, Docker, QNAP) | 30 นาที | +| A2 | สร้าง Organization, Project, Contract | 30 นาที | +| A3 | User Management — สร้าง/แก้ไข/Deactivate User | 20 นาที | +| A4 | Document Number Template Config | 30 นาที | +| A5 | Workflow DSL — อ่านและแก้ไข Workflow Definitions | 45 นาที | +| A6 | Permission & RBAC Matrix — กำหนดสิทธิ์ระดับ Global | 30 นาที | +| A7 | Audit Log & Security Monitoring | 20 นาที | +| A8 | Backup & Restore (DR Runbook) | 20 นาที | +| A9 | Troubleshooting Guide (Common Issues) | 15 นาที | +| — | **Q&A + Hands-on Practice** | 20 นาที | + +**Deliverables:** +- [ ] Admin Quick Reference Card (A4 1 หน้า) +- [ ] System Admin Runbook (PDF) +- [ ] Access ไปยัง Grafana + phpMyAdmin Dashboard + +--- + +### 4.2 Group B — Org Admin (3 ชั่วโมง) + +**เป้าหมาย:** จัดการ User ภายในองค์กร, กำหนดสิทธิ์ระดับ Org + +| Module | หัวข้อ | เวลา | +|--------|--------|------| +| B1 | ภาพรวมระบบและ Role ของ Org Admin | 20 นาที | +| B2 | เพิ่ม/แก้ไข/Deactivate User ในองค์กร | 30 นาที | +| B3 | กำหนด Role: Document Control / Editor / Viewer | 20 นาที | +| B4 | Assign User เข้า Project และ Contract | 20 นาที | +| B5 | ดู Audit Log ภายในองค์กร | 15 นาที | +| B6 | จัดการ Tags สำหรับองค์กร | 15 นาที | +| B7 | การรับมือ Lock Account / Reset Password | 20 นาที | +| — | **Hands-on Practice บน Staging** | 30 นาที | +| — | **Q&A** | 10 นาที | + +**Deliverables:** +- [ ] Org Admin User Manual (PDF, 10-15 หน้า) +- [ ] User Onboarding Checklist + +--- + +### 4.3 Group C — Document Control (4 ชั่วโมง) + +**เป้าหมาย:** สร้าง/ส่ง/ติดตามเอกสารทุกประเภท, จัดการ Workflow + +| Module | หัวข้อ | เวลา | +|--------|--------|------| +| C1 | ภาพรวมระบบ DMS — ทำไมต้องเปลี่ยนจาก Email? | 15 นาที | +| C2 | Login + Dashboard + My Tasks | 15 นาที | +| C3 | **สร้าง Correspondence** — Draft → Submit → Track | 30 นาที | +| C4 | **สร้าง RFA + Shop Drawing** — Draft → Submit via Transmittal | 45 นาที | +| C5 | Upload ไฟล์ — Drag-and-Drop, Main vs Supporting, Virus Scan | 20 นาที | +| C6 | **Circulation Sheet** — สร้าง, Assign, กำหนด Deadline | 30 นาที | +| C7 | ติดตามสถานะ Workflow + Workflow Diagram | 20 นาที | +| C8 | Force Proceed / Revert Workflow (กรณีพิเศษ) | 15 นาที | +| C9 | ค้นหาเอกสาร + Advanced Filter | 15 นาที | +| C10 | Notification Settings + LINE Notify | 15 นาที | +| — | **Hands-on: ทำ Scenario จริงบน Staging** | 40 นาที | +| — | **Q&A** | 20 นาที | + +**Hands-on Scenarios (Staging):** +1. สร้าง Correspondence → Submit → Track Workflow +2. สร้าง RFA + Transmittal → ส่ง → รอ Response +3. รับ Correspondence → สร้าง Circulation → Assign + +**Deliverables:** +- [ ] Document Control User Manual (PDF, 20-30 หน้า) +- [ ] Quick Reference Card: Document Types & Workflow States +- [ ] Video Tutorial: "สร้างและส่ง RFA" (15 นาที) +- [ ] FAQ Document (10 ข้อที่พบบ่อย) + +--- + +### 4.4 Group D — Engineer / Reviewer (2 ชั่วโมง) + +**เป้าหมาย:** รับและ Review เอกสาร, ตอบ RFA, ดู Circulation + +| Module | หัวข้อ | เวลา | +|--------|--------|------| +| D1 | Login + Dashboard + Notification Bell | 15 นาที | +| D2 | ดู Correspondence ที่รับเข้ามา + PDF Viewer | 20 นาที | +| D3 | **Review RFA** — Approved / w.Comments / Rejected | 30 นาที | +| D4 | ดู Shop Drawing ใน PDF Viewer (Streaming) | 15 นาที | +| D5 | ตอบ Circulation ที่ได้รับมอบหมาย | 15 นาที | +| D6 | ค้นหาเอกสาร + ดู Workflow History | 10 นาที | +| D7 | ตั้งค่า Notification (Email/LINE) | 5 นาที | +| — | **Q&A** | 10 นาที | + +**Deliverables:** +- [ ] Reviewer Quick Guide (A4 2 หน้า) +- [ ] Video Tutorial: "วิธี Review RFA" (10 นาที) + +--- + +### 4.5 Group E — Viewer / Auditor / Management (1 ชั่วโมง) + +**เป้าหมาย:** ดู Dashboard, ค้นหา, ดาวน์โหลดรายงาน + +| Module | หัวข้อ | เวลา | +|--------|--------|------| +| E1 | Login + Dashboard Overview | 10 นาที | +| E2 | ค้นหาเอกสารและดู Status | 15 นาที | +| E3 | อ่านเอกสารใน PDF Viewer | 10 นาที | +| E4 | ดู Audit Log (สำหรับ Auditor) | 10 นาที | +| E5 | ตั้งค่า Notification | 5 นาที | +| — | **Q&A** | 10 นาที | + +**Deliverables:** +- [ ] Viewer Quick Start (A4 1 หน้า, ภาษาไทย + อังกฤษ) + +--- + +## 5. 🎥 Training Materials Checklist + +### 5.1 เอกสาร (Documents) + +| Material | Target | สถานะ | Deadline | +|----------|--------|-------|---------| +| System Admin Runbook | Group A | ⬜ ต้องสร้าง | T-4 สัปดาห์ | +| Org Admin User Manual | Group B | ⬜ ต้องสร้าง | T-4 สัปดาห์ | +| Document Control User Manual | Group C | ⬜ ต้องสร้าง | T-4 สัปดาห์ | +| Reviewer Quick Guide | Group D | ⬜ ต้องสร้าง | T-3 สัปดาห์ | +| Viewer Quick Start | Group E | ⬜ ต้องสร้าง | T-3 สัปดาห์ | +| Glossary / คำศัพท์ระบบ | ทุก Role | ✅ มี (`00-02-glossary.md`) | — | +| FAQ (10 ข้อพบบ่อย) | Group C, D | ⬜ ต้องสร้าง | T-2 สัปดาห์ | + +### 5.2 Video Tutorials + +| Video | ความยาว | Target | สถานะ | +|-------|--------|--------|-------| +| ภาพรวมระบบ (System Intro) | 5 นาที | ทุก Role | ⬜ | +| วิธีสร้างและส่ง Correspondence | 10 นาที | Group C | ⬜ | +| วิธีสร้างและส่ง RFA + Transmittal | 15 นาที | Group C | ⬜ | +| วิธี Review RFA | 10 นาที | Group D | ⬜ | +| วิธีสร้าง Circulation Sheet | 8 นาที | Group C | ⬜ | +| ค้นหาเอกสารและใช้ Filter | 5 นาที | ทุก Role | ⬜ | + +> **เครื่องมือแนะนำ:** OBS Studio (Screen Record) + CapCut / DaVinci Resolve (Edit) + Loom (Quick Share) + +### 5.3 Hands-on Training Scenarios (บน Staging) + +```markdown +Scenario 1: "ส่ง RFA ครั้งแรก" (Group C) +─────────────────────────────────────── +1. Login ด้วย Account Contractor A +2. Upload Shop Drawing (ไฟล์ PDF ตัวอย่าง) +3. สร้าง RFA Type: Shop Drawing — Discipline: STR +4. สร้าง Transmittal → แนบ RFA → Submit +5. ยืนยัน: Notification ถูกส่ง | เลขเอกสารถูกออก + +Scenario 2: "Review และ Approve RFA" (Group D) +───────────────────────────────────────────── +1. Login ด้วย Account Engineer (TEAM หรือ คคง.) +2. ดู Notification Bell → เปิด RFA ที่ได้รับ +3. ดู Shop Drawing ใน PDF Viewer +4. คลิก "Approved with Comments" + กรอก Comment +5. ยืนยัน: Contractor ได้รับ Notification + +Scenario 3: "สร้าง Circulation และติดตาม" (Group C) +─────────────────────────────────────────────── +1. รับเอกสาร Correspondence ใน Inbox +2. สร้าง Circulation Sheet → Assign Main, Action, Info +3. กำหนด Deadline 3 วัน +4. Assignee Login → ดู My Tasks → ตอบกลับ +5. Document Control ปิด Circulation +``` + +--- + +## 6. 🏆 Train-the-Trainer Program + +### 6.1 เป้าหมาย +แต่ละองค์กรมี **Internal Trainer** 1 คน ที่สามารถ: +- สอน User ใหม่ในองค์กรได้ด้วยตัวเอง +- ตอบ FAQ เบื้องต้นโดยไม่ต้องติดต่อ NAP +- รายงาน Issues ผ่าน Support Channel ได้ถูกต้อง + +### 6.2 Internal Trainer คุณสมบัติ +- มักเป็น **Document Control** อาวุโส หรือ Org Admin +- เข้าร่วม Training Group A หรือ C ก่อน +- ผ่าน Hands-on Practice Scenario ทั้ง 3 ครบ +- ได้รับ "Trainer Kit" (Materials + Access พิเศษ) + +### 6.3 Trainer Kit +``` +📦 Trainer Kit ประกอบด้วย: +├── 📄 User Manuals (ทุก Role) — สำหรับแจกจ่าย +├── 🎥 Video Tutorials — ลิงก์ internal host +├── 🃏 Training Scenario Scripts (3 Scenarios) +├── ❓ FAQ Document +├── 📊 Staging Environment Access (ไม่กระทบ Production) +└── 📞 Escalation Contact: Nattanin (Line/Email) +``` + +--- + +## 7. 🆘 Support Desk Setup + +### 7.1 Support Tiers + +``` +Level 1 — Internal Trainer (Self-service, 0-4 ชั่วโมง) +│ └── FAQ Document + Video Tutorials +│ ↓ ถ้าแก้ไม่ได้ +Level 2 — Org Admin / Document Control (4-24 ชั่วโมง) +│ └── ติดต่อ Internal Trainer ขององค์กร +│ ↓ ถ้าแก้ไม่ได้ +Level 3 — NAP Support (1-2 วันทำการ) + └── LINE Group / Email → Nattanin + ↓ ถ้าเป็น Bug หรือ System Issue +Level 4 — Dev Team (Hotfix / Patch) + └── Fix + Deploy + Notify +``` + +### 7.2 Support Channels + +| Channel | ใช้เมื่อ | Response Time | +|---------|---------|--------------| +| **LINE Group** (NAP-DMS Support) | ปัญหาเร่งด่วน, ถามวิธีใช้ | 2-4 ชั่วโมง (ในเวลาทำงาน) | +| **Email** nattanin@[domain] | รายงาน Bug, ขอ Feature | 1-2 วันทำการ | +| **FAQ Document** | ปัญหาทั่วไป | ทันที (Self-service) | +| **Video Tutortials** | ต้องการดูวิธีใช้ซ้ำ | ทันที (Self-service) | + +### 7.3 Hypercare Period (Go-Live Month 1) + +**สัปดาห์ 1-2 (Go-Live):** +- NAP ทีม On-Call: 08:00–18:00 ทุกวันทำการ +- Daily Check-in กับ Internal Trainers ทุกองค์กร (15 นาที) +- Bug Tracker: บันทึก Issues ทั้งหมด (Priority P0-P3) + +**สัปดาห์ 3-4:** +- On-Call: ตามปกติ (Response ภายใน 4 ชั่วโมง) +- Weekly Review: สรุป Issues + แก้ไข + FAQ Update + +**หลัง 1 เดือน:** +- Standard Support (Level 1-4 ตามปกติ) +- Monthly Review Meeting + +### 7.4 Bug Priority & SLA + +| Priority | ตัวอย่าง | Response | Resolution | +|----------|---------|---------|-----------| +| **P0 — Critical** | ระบบล่ม, Data Loss | 30 นาที | 4 ชั่วโมง | +| **P1 — High** | Login ไม่ได้, เอกสารหาย | 2 ชั่วโมง | 24 ชั่วโมง | +| **P2 — Medium** | Feature ทำงานผิด | 4 ชั่วโมง | 3 วัน | +| **P3 — Low** | UI ผิดเล็กน้อย, Typo | 24 ชั่วโมง | 2 สัปดาห์ | + +--- + +## 8. 📢 Change Management Communication Plan + +### 8.1 Communication Timeline + +| เวลา | ข้อความ | ช่องทาง | ผู้รับ | +|------|---------|---------|-------| +| T-8 สัปดาห์ | Announcement: ระบบใหม่กำลังจะมา | Email + LINE | ผู้บริหารทุกองค์กร | +| T-4 สัปดาห์ | Training Schedule แจ้งรายละเอียด | Email | Org Admin ทุกองค์กร | +| T-2 สัปดาห์ | Training Reminder + Staging Access | Email + LINE | ทุก User | +| T-1 สัปดาห์ | "1 สัปดาห์แล้ว!" + Go-Live Date | Email + LINE | ทุก User | +| Go-Live Day | Go-Live Announcement + Support Contact | Email + LINE | ทุก User | +| T+2 สัปดาห์ | Feedback Survey (Google Form) | Email | ผู้ใช้งานทุกคน | +| T+1 เดือน | Summary Report ต่อผู้บริหาร | Meeting | Project Management | + +### 8.2 Key Messages + +**สำหรับผู้บริหาร:** +> "ระบบ LCBP3-DMS ช่วยให้ติดตามสถานะเอกสารได้ Real-time, ลดเวลา Cycle RFA จาก 2 สัปดาห์เหลือ 3 วัน, และมี Audit Trail ครบถ้วน" + +**สำหรับ Document Control:** +> "ระบบนี้ช่วยลดการทำงานซ้ำซ้อนจาก Email ไปสู่ Workflow อัตโนมัติ เลขเอกสารออกอัตโนมัติ ไม่ต้องจำหรือนับมือ" + +**สำหรับ Engineer / Reviewer:** +> "รับ Notification ทันทีเมื่อมี RFA ใหม่ ดู PDF ในระบบโดยไม่ต้อง Download คลิก Approve ได้เลย" + +### 8.3 Resistance Management + +| กลุ่มที่อาจต้าน | เหตุผล | วิธีรับมือ | +|--------------|-------|-----------| +| ผู้ใช้ที่คุ้นชิน Email | "Email ง่ายกว่า" | แสดง Case Study: วันไหน RFA ตกหล่น | +| ผู้บริหารอาวุโส | "ไม่ถนัด IT" | เน้น: ดูสถานะได้ 1 คลิก, ไม่ต้องโทรถาม | +| Document Control | "งานเพิ่มขึ้น" | แสดง: Auto-Number, Auto-Notify ลดงานจริง | +| IT/Ops ที่คุ้นระบบเดิม | "Server อะไรอีก" | ADR-015, Docker ง่ายต่อ Maintain | + +--- + +## 9. 📊 Training KPIs & Success Criteria + +| KPI | Target | วิธีวัด | +|-----|--------|--------| +| Training Attendance | > 90% ของ Users ทุก Group | Sign-in Sheet | +| Post-Training Quiz Score | > 80% เฉลี่ย | Online Quiz (Google Form) | +| Hands-on Scenario Pass Rate | > 90% ทำ Scenario 1-3 ได้ | Trainer Assessment | +| Support Tickets Week 1 | < 20 tickets (แสดง Training มีประสิทธิภาพ) | Support Log | +| User Adoption Month 1 | > 70% Login ทุกวันทำการ | System Analytics | +| User Adoption Month 3 | > 90% Active Users | System Analytics | +| Satisfaction Score | > 4.0/5.0 | Feedback Survey (T+2 สัปดาห์) | + +--- + +## 10. ✅ Training Readiness Checklist (Pre Go-Live) + +### Materials +- [ ] System Admin Runbook สร้างเสร็จ + Review แล้ว +- [ ] Document Control User Manual สร้างเสร็จ +- [ ] Quick Guides (Reviewer, Viewer) สร้างเสร็จ +- [ ] Video Tutorials อย่างน้อย 3 clips +- [ ] FAQ Document (10+ ข้อ) สร้างเสร็จ +- [ ] Training Scenarios (Staging Data) เตรียมพร้อม + +### Infrastructure +- [ ] Staging Environment Deploy แล้ว (Mirror Production) +- [ ] Test Users ทุก Role สร้างแล้ว (1 ชุดต่อ Org) +- [ ] Email + LINE Notify บน Staging ทำงาน (Test Mode) +- [ ] Staging URL แจ้ง Trainers แล้ว + +### People +- [ ] Internal Trainer แต่ละองค์กร ระบุชื่อแล้ว +- [ ] Train-the-Trainer Session เสร็จแล้ว +- [ ] Training Schedule แจ้งทุกคนแล้ว +- [ ] Support LINE Group สร้างแล้ว + เพิ่ม Users + +### Process +- [ ] Bug Report Process อธิบายให้ Trainers แล้ว +- [ ] Escalation Path ชัดเจน +- [ ] Hypercare Schedule ตกลงกันแล้ว (ว่าใครรับผิดชอบวันไหน) + +--- + +## 📝 Document Control + +- **Version:** 1.0.0 | **Status:** DRAFT +- **Created:** 2026-03-11 | **Owner:** Nattanin Peancharoen +- **Next Review:** T-4 สัปดาห์ก่อน Go-Live +- **Classification:** Internal Use Only diff --git a/specs/00-overview/README.md b/specs/00-overview/README.md index cd9981e..5799fec 100644 --- a/specs/00-overview/README.md +++ b/specs/00-overview/README.md @@ -206,6 +206,16 @@ lcbp3/ | ------------------ | ---------------------------------------------------------------------------------- | ------------------------------------- | | **Overview** | [Glossary](./00-02-glossary.md) | Technical terminology & abbreviations | | **Overview** | [Quick Start](./00-01-quick-start.md) | 5-minute getting started guide | +| **Overview** | [🎯 Product Vision](./00-03-product-vision.md) | Vision Statement, Strategy, Guardrails | +| **Overview** | [📊 KPI Baseline & Measurement](./00-05-kpi-baseline.md) | 14 KPIs, Baseline Forms, SQL Queries | +| **Overview** | [🎓 Training Plan](./00-06-training-plan.md) | Training curriculum & change management | +| **Overview** | [📋 Stakeholder Sign-off & Risk](./00-04-stakeholder-signoff-and-risk.md) | Sign-off process, Risk Register, Change Control | +| **Overview** | [🚀 Release Management Policy](../04-Infrastructure-OPS/04-08-release-management-policy.md) | SemVer, Release Gates, Hotfix, Rollback Policy | +| **Requirements** | [📖 User Stories](../01-Requirements/01-04-user-stories.md) | 27 User Stories (8 Epics, MoSCoW) | +| **Requirements** | [🛡️ Edge Cases & Business Rules](../01-Requirements/01-06-edge-cases-and-rules.md) | 37 Edge Cases ป้องกัน Bug | +| **Requirements** | [🖼️ UI/UX Wireframes](../01-Requirements/01-07-ui-wireframes.md) | 26 Screens, Navigation Map, Design System | +| **Data** | [📦 Migration Business Scope](../03-Data-and-Storage/03-06-migration-business-scope.md) | 20,000 Docs, 3 Tiers, Go/No-Go Gates | +| **Requirements** | [✅ Acceptance Criteria (UAT)](../01-Requirements/01-05-acceptance-criteria.md) | MVP Go-Live criteria & UAT Sign-off | | **Requirements** | [Functional Requirements](../01-requirements/01-03-functional-requirements.md) | Feature specifications | | **Requirements** | [Document Numbering](../01-requirements/01-03.11-document-numbering.md) | Document numbering requirements | | **Architecture** | [System Architecture](../02-architecture/02-01-system-architecture.md) | Overall system design | diff --git a/specs/01-requirements/01-04-user-stories.md b/specs/01-requirements/01-04-user-stories.md new file mode 100644 index 0000000..c7e9dac --- /dev/null +++ b/specs/01-requirements/01-04-user-stories.md @@ -0,0 +1,460 @@ +# 📖 User Stories — LCBP3-DMS v1.8.0 + +--- +title: 'User Stories — All Modules' +version: 1.0.0 +status: DRAFT +owner: Nattanin Peancharoen (Product Owner) +last_updated: 2026-03-11 +related: + - specs/01-Requirements/01-01-objectives.md + - specs/01-Requirements/01-05-acceptance-criteria.md + - specs/01-Requirements/01-03-modules/ +--- + +## 📖 วิธีอ่าน + +- **Format:** `As a [role] / I want to [goal] / So that [benefit]` +- **Priority:** 🔴 M (Must) | 🟠 S (Should) | 🟡 C (Could) | ⚫ W (Won't-Now) +- **SP:** Story Points (Fibonacci) — 1 SP ≈ ความซับซ้อนระดับ Login +- **AC Link:** → `[AC-XXX-YYY]` อ้างอิง `01-05-acceptance-criteria.md` + +--- + +## 👥 Epic 1: Authentication & User Management + +### US-001 — Login เข้าระบบ +**Priority:** 🔴 M | **SP:** 2 | **AC:** AC-AUTH-001, AC-AUTH-002 + +``` +As a ผู้ใช้งานทุกประเภท +I want to login ด้วย Username + Password +So that ฉันเข้าถึงระบบตามบทบาทของตนได้ +``` +**Done When:** +- Login สำเร็จ → Dashboard | Password ผิด → Error กลางๆ +- ผิดเกิน 5 ครั้งใน 1 นาที → 429 Rate Limit +- Audit Log: `LOGIN_SUCCESS` / `LOGIN_FAILED` + IP + +--- + +### US-002 — เปลี่ยนรหัสผ่านครั้งแรก +**Priority:** 🔴 M | **SP:** 2 | **AC:** AC-AUTH-003 + +``` +As a ผู้ใช้งานใหม่ที่เพิ่งถูกสร้างโดย Admin +I want to ถูกบังคับเปลี่ยนรหัสผ่านใน Login ครั้งแรก +So that ฉันมีรหัสผ่านที่ฉันรู้คนเดียว +``` +**Done When:** +- Login ครั้งแรก → Redirect หน้าเปลี่ยน Password ทันที (ผ่านไม่ได้) +- Password ใหม่ต้องผ่าน Policy (8+ ตัว, อักษรใหญ่-เล็ก-ตัวเลข) + +--- + +### US-003 — จัดการ Profile ส่วนตัว +**Priority:** 🟠 S | **SP:** 2 + +``` +As a ผู้ใช้งานทุกประเภท +I want to แก้ไขข้อมูลส่วนตัวและเปลี่ยนรหัสผ่าน +So that ฉันดูแล Account ของตัวเองได้ +``` +**Done When:** +- แก้ไข ชื่อ, Email, ช่องทาง Notification ได้ +- เปลี่ยน Password ต้องยืนยัน Password เก่า + +--- + +### US-004 — Superadmin สร้างองค์กร + Project + Contract +**Priority:** 🔴 M | **SP:** 5 | **AC:** AC-ADMIN-001, AC-ADMIN-002 + +``` +As a Superadmin +I want to สร้าง Organization, Project, Contract และผูกความสัมพันธ์กัน +So that ระบบพร้อมให้แต่ละองค์กรเริ่มทำงานได้ +``` +**Done When:** +- สร้าง Org → แต่งตั้ง Org Admin ได้ทันที +- สร้าง Project → ผูก Organizations (หลายองค์กร) +- สร้าง Contract → 1 Contractor ต่อ 1 Contract +- กำหนด Document Number Template ต่อ Project + +--- + +### US-005 — Org Admin จัดการ User ในองค์กร +**Priority:** 🔴 M | **SP:** 3 | **AC:** AC-ADMIN-003 + +``` +As a Org Admin +I want to เพิ่ม/แก้ไข/Deactivate User และกำหนด Role +So that ทีมงานเข้าถึงระบบได้ตามหน้าที่ +``` +**Done When:** +- เพิ่ม User → Email แจ้ง Credentials อัตโนมัติ +- Deactivate ได้ (ไม่ Delete — Audit ยังอยู่) +- เห็นเฉพาะ User ในองค์กรตัวเอง + +--- + +### US-006 — Permission Isolation ระหว่าง Contractor +**Priority:** 🔴 M | **SP:** 2 | **AC:** AC-ADMIN-004 + +``` +As a ระบบ +I want to ป้องกัน Contractor A เห็นข้อมูล Contractor B +So that ข้อมูลทางธุรกิจของแต่ละ Contractor เป็นความลับ +``` +**Done When:** +- Contractor A→ ไม่เห็น List เอกสาร B | พยายาม Access URL ตรงๆ → 403 +- Audit Log บันทึก Unauthorized Attempt + +--- + +## 📨 Epic 2: Correspondence Management + +### US-007 — สร้าง Correspondence Draft +**Priority:** 🔴 M | **SP:** 5 | **AC:** AC-CORR-001 + +``` +As a Document Control +I want to สร้าง Correspondence (Letter/RFI) ในสถานะ Draft พร้อมแนบไฟล์ +So that เตรียมเอกสารได้ก่อนส่งโดยองค์กรอื่นยังไม่เห็น +``` +**Done When:** +- Form: Subject, To (หลายองค์กร), CC, Doc Type, Attachments (PDF/ZIP) +- Drag-and-Drop Multi-file | ClamAV Scan ทุกไฟล์ +- Auto-Save Draft → LocalStorage (กันข้อมูลสูญ) +- ผู้ใช้นอกองค์กรไม่เห็น Draft + +--- + +### US-008 — Submit Correspondence + Auto Number +**Priority:** 🔴 M | **SP:** 5 | **AC:** AC-CORR-002 + +``` +As a Document Control +I want to Submit Correspondence และให้ระบบออกเลขอัตโนมัติ +So that เอกสารได้รับเลขที่ไม่ซ้ำและส่งถึงผู้รับทันที +``` +**Done When:** +- ออกเลขตาม Template (เช่น `LCBP3-สค.-กทท.-LETTER-0001-68`) +- เลขไม่ซ้ำแม้ Submit พร้อมกัน (Redis Redlock) +- สถานะ → SUBMITTED | Workflow Instance ถูกสร้าง +- ผู้รับ → Email + In-App Notification + +--- + +### US-009 — ดู Correspondence ใน Inbox +**Priority:** 🔴 M | **SP:** 3 | **AC:** AC-CORR-003 + +``` +As a Document Control ขององค์กรผู้รับ +I want to เห็น Correspondence ที่ส่งมาถึงองค์กรในรายการ +So that ดำเนินการได้ทันที (สร้าง Circulation, ตอบกลับ) +``` +**Done When:** +- List แสดง Received/Sent แยก | PDF Viewer ในแอป (Streaming) +- ดาวน์โหลดไฟล์แนบได้ (ถ้ามีสิทธิ์) + +--- + +### US-010 — อ้างอิง + Tag เอกสาร +**Priority:** 🟠 S | **SP:** 3 | **AC:** AC-CORR-004 + +``` +As a Document Control +I want to อ้างอิงเอกสารเก่าและกำหนด Tag หลาย Tag +So that จัดกลุ่มเอกสารและ Navigate ข้าม Thread ได้ +``` +**Done When:** +- ค้นหาและเลือก Reference Documents | Link ระหว่างเอกสาร (คลิก Navigate) +- กำหนด Tag หลาย Tag | ค้นหาได้จาก Tag + +--- + +### US-011 — ยกเลิก Correspondence (Admin) +**Priority:** 🟡 C | **SP:** 2 | **AC:** AC-CORR-005 + +``` +As a Org Admin / Superadmin +I want to ยกเลิก Correspondence ที่ Submit แล้ว พร้อมระบุเหตุผล +So that เอกสารที่ส่งผิดถูกระงับโดยมีหลักฐาน Audit +``` +**Done When:** +- ต้องกรอก cancel_reason | สถานะ → CANCELLED +- Editor/Viewer ทำ Cancel ไม่ได้ → 403 + +--- + +## 📋 Epic 3: RFA Management + +### US-012 — สร้าง RFA + Shop Drawing +**Priority:** 🔴 M | **SP:** 8 | **AC:** AC-RFA-001 + +``` +As a Document Control ของ Contractor +I want to สร้าง RFA พร้อม Upload Shop Drawing +So that ยื่นขออนุมัติแบบก่อสร้างจากที่ปรึกษาได้อย่างเป็นระบบ +``` +**Done When:** +- Form: RFA Type, Discipline, Shop Drawing (PDF/DWG/ZIP) +- 1 Shop Drawing Revision = 1 RFA เท่านั้น +- ClamAV Scan | Draft (ไม่เห็นข้ามองค์กร) + +--- + +### US-013 — Submit RFA ผ่าน Transmittal +**Priority:** 🔴 M | **SP:** 8 | **AC:** AC-RFA-002, AC-TRM-001 + +``` +As a Document Control ของ Contractor +I want to สร้าง Transmittal รวม RFA หลายฉบับ ส่งไปยังที่ปรึกษา +So that ส่งเอกสารเป็นชุด ที่ปรึกษาได้รับทุกฉบับพร้อมกัน +``` +**Done When:** +- Transmittal → เลือก RFA หลายฉบับ | ออกเลขเองเป็น Correspondence +- RFA แต่ละฉบับ → ออกเลขตาม Format `LCBP3-RFA-{DISCIPLINE}-{SEQ}` +- ที่ปรึกษา → Notification + +--- + +### US-014 — Review RFA (Approved / w.Comments / Rejected) +**Priority:** 🔴 M | **SP:** 5 | **AC:** AC-RFA-003~005 + +``` +As a Engineer ของ Supervisor Organization +I want to เปิดดู Shop Drawing และให้คำตอบ RFA +So that Contractor ได้รับผลพิจารณาและดำเนินการต่อได้ +``` +**Done When:** +- PDF Viewer Streaming | ปุ่ม: Approved / Approved w/Comments / Rejected +- Comment บังคับสำหรับ Approved w/Comments และ Rejected +- Originator → Notification | Workflow History บันทึกครบ + +--- + +### US-015 — ยื่น RFA Revision ใหม่หลัง Reject +**Priority:** 🟠 S | **SP:** 5 | **AC:** AC-RFA-006 + +``` +As a Document Control ของ Contractor +I want to สร้าง RFA Revision ใหม่ (Rev.B) หลัง Rev.A ถูก Rejected +So that แก้ไขและยื่น Shop Drawing เวอร์ชันใหม่ได้ +``` +**Done When:** +- Rev.B ผูกกับ Shop Drawing Rev.B | Rev.A ยังดูได้ +- Revision Code เปลี่ยนตาม Sequence (A→B→C) + +--- + +## 📐 Epic 4: Drawing Management + +### US-016 — Upload Contract Drawing +**Priority:** 🟠 S | **SP:** 5 | **AC:** AC-DRW-001 + +``` +As a Document Control ของ Design Consultant +I want to Upload แบบคู่สัญญา (Contract Drawing) พร้อมกำหนดหมวดหมู่ +So that Contractor ใช้อ้างอิงใน Shop Drawing ได้ +``` +**Done When:** +- Upload PDF → Drawing Number, Category, Discipline +- Shop Drawing Link Reference กับ Contract Drawing ได้ + +--- + +### US-017 — Upload Shop Drawing + Revision Control +**Priority:** 🟠 S | **SP:** 5 | **AC:** AC-DRW-002, AC-DRW-003 + +``` +As a Document Control ของ Contractor +I want to Upload Shop Drawing พร้อม Reference Contract Drawing และจัดการ Revision +So that ผู้ Review เห็น Revision ล่าสุด และ History ทุก Revision +``` +**Done When:** +- ค้นหาและเลือก Contract Drawing ที่ Reference +- Rev.ใหม่ → Rev.เก่า Mark "Superseded" แต่ยังดูได้ +- 1 Revision = 1 RFA เท่านั้น (Constraint enforced) + +--- + +## ⚙️ Epic 5: Workflow Engine + +### US-018 — ดู Workflow Diagram ของเอกสาร +**Priority:** 🟠 S | **SP:** 3 | **AC:** AC-WF-004 + +``` +As a ผู้ใช้งานที่มีสิทธิ์ดูเอกสาร +I want to เห็น Workflow Diagram แบบ Visual +So that รู้ทันทีว่าเอกสารอยู่ขั้นตอนไหน ใครถืออยู่ +``` +**Done When:** +- Workflow Diagram แสดง State ปัจจุบัน (Highlight) +- คลิก Step ที่ผ่านมา → Audit Log ย่อย (ใคร/เมื่อไหร่/Comment) +- Step ที่ยังไม่ถึง → Disabled Style + +--- + +### US-019 — Approve / Reject ผ่าน Workflow +**Priority:** 🔴 M | **SP:** 5 | **AC:** AC-WF-002, AC-WF-003 + +``` +As a Reviewer ที่ถูก Assign ใน Workflow +I want to Approve / Reject เอกสารในขั้นตอนที่ฉันรับผิดชอบ +So that Workflow เดินหน้าหรือส่งกลับตามการตัดสินใจ +``` +**Done When:** +- เห็นปุ่ม Action เฉพาะ Step ที่เป็นของฉัน +- Wrong Role → ปุ่มซ่อน / 403 ถ้าเรียก API ตรงๆ +- ทุก Action → Workflow History + Timestamp + +--- + +### US-020 — Force Proceed + Revert (Document Control) +**Priority:** 🟡 C | **SP:** 3 | **AC:** AC-WF-005 + +``` +As a Document Control +I want to บังคับข้ามหรือย้อน Workflow Step ในกรณีพิเศษ +So that Workflow ที่ติดขัดถูก Unblock ได้อย่างมีหลักฐาน +``` +**Done When:** +- ปุ่ม "Force Proceed" / "Revert" เห็นได้เฉพาะ Document Control ขึ้นไป +- ต้องกรอก reason | Audit Log: FORCE_PROCEED / REVERT + +--- + +### US-021 — กำหนด Deadline ใน Workflow +**Priority:** 🟡 C | **SP:** 3 | **AC:** AC-WF-006 + +``` +As a Document Control +I want to กำหนด Deadline ให้แต่ละ Organization ใน Workflow +So that ดำเนินการทันเวลา ไม่เกิดความล่าช้า +``` +**Done When:** +- กำหนด Due Date ต่อ Org ใน Workflow +- เกิน Deadline → Dashboard Overdue Badge + Notification +- 2 วันก่อน → Reminder Notification + +--- + +## 📄 Epic 6: Circulation Sheet + +### US-022 — สร้าง Circulation Sheet +**Priority:** 🟠 S | **SP:** 5 | **AC:** AC-CIRC-001 + +``` +As a Document Control ภายในองค์กร +I want to สร้างใบเวียนสำหรับ Correspondence พร้อมกำหนดผู้รับผิดชอบ +So that งานถูก Assign ชัดเจนและมีหลักฐาน +``` +**Done When:** +- กำหนด Main / Action / Information Assignees (หลายคน) +- Assignees → In-App + Email Notification +- Internal Only (ไม่เห็นข้ามองค์กร) + +--- + +### US-023 — ติดตาม Circulation Deadline + ปิด +**Priority:** 🟠 S | **SP:** 3 | **AC:** AC-CIRC-002, AC-CIRC-003 + +``` +As a Assignee / Document Control +I want to เห็น Deadline งานของฉันและปิด Circulation เมื่อเสร็จ +So that ไม่พลาดงาน และ Track สถานะได้ชัดเจน +``` +**Done When:** +- Dashboard My Tasks แสดง Deadline + Overdue Badge +- ปิด Circulation → สถานะ CLOSED + Timestamp +- My Tasks ลบรายการที่ปิดแล้ว + +--- + +## 🔍 Epic 7: Search & Notifications + +### US-024 — ค้นหาเอกสาร Full-text +**Priority:** 🟠 S | **SP:** 5 | **AC:** AC-SRCH-001 + +``` +As a ผู้ใช้งานทุกประเภท +I want to ค้นหาเอกสารด้วย Keyword ได้รวดเร็ว +So that พบเอกสารที่ต้องการโดยไม่ต้องจำเลขที่แม่นยำ +``` +**Done When:** +- ผล Search < 500ms (Elasticsearch) | ค้นจาก เลขเอกสาร, Subject, Tag +- แสดงเฉพาะเอกสารที่มีสิทธิ์เห็น + +--- + +### US-025 — รับ Notification (Email + In-App) +**Priority:** 🟠 S | **SP:** 5 | **AC:** AC-NOTIF-001, AC-NOTIF-002 + +``` +As a ผู้ใช้งาน +I want to รับ Email และ In-App Notification เมื่อมี Event เกี่ยวข้องกับฉัน +So that ไม่พลาดงานโดยไม่ต้องเช็คระบบตลอดเวลา +``` +**Done When:** +- Email ถูกส่งภายใน 5 นาที หลัง Event (BullMQ Queue) +- Bell Icon Unread Count | คลิก → Navigate ไปเอกสาร +- Retry 3 ครั้ง ถ้าส่งไม่ได้ → Dead Letter Queue + +--- + +## 💾 Epic 8: File & Dashboard + +### US-026 — Upload ไฟล์ + ดู PDF ในแอป +**Priority:** 🟠 S | **SP:** 5 | **AC:** AC-STOR-001, AC-STOR-003 + +``` +As a Document Control / Reviewer +I want to Upload ไฟล์หลายไฟล์และดู PDF ในแอปได้เลย +So that ทำงานเร็วขึ้นและลดความเสี่ยงข้อมูลรั่วจาก Download +``` +**Done When:** +- Drag-and-Drop Multi-file | ClamAV Scan < 30s +- In-App PDF Viewer (Range Requests Streaming) +- ปุ่ม Download → Disabled สำหรับ Viewer-only + +--- + +### US-027 — Dashboard KPI ส่วนตัว +**Priority:** 🟠 S | **SP:** 5 | **AC:** AC-DASH-001 + +``` +As a ผู้ใช้งานทุกประเภท +I want to เห็น Dashboard สรุปงานของฉันทันทีที่ Login +So that รู้สถานะงานโดยไม่ต้องไล่ดูแต่ละ Module +``` +**Done When:** +- KPI Cards: Pending RFA, Pending Correspondence, Overdue Circulation +- My Tasks Table: Circulation ที่ค้าง + Deadline +- Filter ตาม Permission ของ User + +--- + +## 📊 Story Map Summary + +| Epic | Stories | 🔴 Must | 🟠 Should | 🟡 Could | +|------|---------|---------|----------|--------| +| Auth & Users | US-001~006 | 4 | 1 | 1 | +| Correspondence | US-007~011 | 2 | 2 | 1 | +| RFA | US-012~015 | 2 | 2 | 0 | +| Drawing | US-016~017 | 0 | 2 | 0 | +| Workflow | US-018~021 | 1 | 1 | 2 | +| Circulation | US-022~023 | 0 | 2 | 0 | +| Search & Notify | US-024~025 | 0 | 2 | 0 | +| File & Dashboard | US-026~027 | 0 | 2 | 0 | +| **รวม** | **27** | **9** | **14** | **4** | + +> **MVP Sprint Focus:** US-001~006, US-007~008, US-012~014, US-019 — ครอบคลุม Core Happy Path ทั้งหมด + +--- + +## 📝 Document Control + +- **Version:** 1.0.0 | **Status:** DRAFT +- **Created:** 2026-03-11 | **Owner:** Nattanin Peancharoen +- **Classification:** Internal Use Only diff --git a/specs/01-requirements/01-05-acceptance-criteria.md b/specs/01-requirements/01-05-acceptance-criteria.md new file mode 100644 index 0000000..4841e9a --- /dev/null +++ b/specs/01-requirements/01-05-acceptance-criteria.md @@ -0,0 +1,771 @@ +# ✅ Acceptance Criteria — LCBP3-DMS MVP (UAT) + +--- + +title: 'Acceptance Criteria & UAT Test Scenarios' +version: 1.8.0 +status: DRAFT — Pending Stakeholder Sign-off +owner: Nattanin Peancharoen (Product Owner) +last_updated: 2026-03-11 +related: + - specs/01-Requirements/01-01-objectives.md + - specs/01-Requirements/01-03-modules/ + - specs/01-Requirements/01-02-business-rules/01-02-01-rbac-matrix.md + - specs/01-Requirements/01-02-business-rules/01-02-04-non-functional-rules.md + - specs/06-Decision-Records/ADR-001-unified-workflow-engine.md + - specs/06-Decision-Records/ADR-016-security-authentication.md + +--- + +## 📖 วิธีอ่านเอกสารนี้ + +แต่ละ Scenario ใช้รูปแบบ **Given / When / Then** พร้อม: +- **ID**: รหัส Scenario ใช้อ้างอิง (AC-XXX-YYY) +- **Priority**: 🔴 Blocker | 🟠 Critical | 🟡 Major | 🟢 Minor +- **Role**: ผู้ใช้ที่ทดสอบ Scenario นี้ + +--- + +## 🏗️ Module 1: Authentication & Session Management + +### AC-AUTH-001 — Login Success +**Priority:** 🔴 Blocker | **Role:** ทุก Role + +| | Description | +|---|---| +| **Given** | User มีบัญชีในระบบ และ Password ถูกต้อง | +| **When** | กรอก Username + Password แล้วกด Login | +| **Then** | ✅ ได้รับ JWT Access Token (15 min TTL) + Refresh Token (7 days) | +| | ✅ ถูก Redirect ไปที่ Dashboard | +| | ✅ Audit Log บันทึก `LOGIN_SUCCESS` พร้อม IP Address | + +### AC-AUTH-002 — Login Failed (Wrong Password) +**Priority:** 🔴 Blocker | **Role:** ทุก Role + +| | Description | +|---|---| +| **Given** | User มีบัญชีในระบบ | +| **When** | กรอก Password ผิด | +| **Then** | ✅ แสดง Error "ชื่อผู้ใช้หรือรหัสผ่านไม่ถูกต้อง" (ไม่บอกว่าอันไหนผิด) | +| | ✅ Audit Log บันทึก `LOGIN_FAILED` | +| | ✅ หลัง 5 ครั้งใน 1 นาที → Rate Limit 429 Too Many Requests | + +### AC-AUTH-003 — First Login Force Password Change +**Priority:** 🔴 Blocker | **Role:** ทุก Role (new user) + +| | Description | +|---|---| +| **Given** | User เพิ่งถูกสร้างโดย Admin (password_must_change = true) | +| **When** | Login สำเร็จครั้งแรก | +| **Then** | ✅ ถูก Redirect ไปยังหน้า "เปลี่ยนรหัสผ่าน" ทันที | +| | ✅ ไม่สามารถเข้าถึงหน้าอื่นได้ จนกว่าจะเปลี่ยนรหัสผ่าน | +| | ✅ Password ใหม่ต้องผ่าน Policy (ตัวใหญ่ + ตัวเล็ก + ตัวเลข + 8+ ตัวอักษร) | + +### AC-AUTH-004 — Token Refresh +**Priority:** 🟠 Critical | **Role:** ทุก Role + +| | Description | +|---|---| +| **Given** | Access Token หมดอายุ (15 min) แต่ Refresh Token ยังใช้งานได้ | +| **When** | Frontend ตรวจพบ 401 Response ระหว่างการใช้งาน | +| **Then** | ✅ Frontend auto-refresh token โดยผู้ใช้ไม่รู้สึก | +| | ✅ Request เดิม Retry สำเร็จหลัง Token Refresh | + +### AC-AUTH-005 — Logout +**Priority:** 🟠 Critical | **Role:** ทุก Role + +| | Description | +|---|---| +| **Given** | User กำลัง Login อยู่ | +| **When** | กด Logout | +| **Then** | ✅ Refresh Token ถูก Revoke ใน Database | +| | ✅ Redis Permission Cache ถูกลบ | +| | ✅ Redirect ไปหน้า Login | +| | ✅ Audit Log บันทึก `LOGOUT` | + +--- + +## 🏢 Module 2: User & Organization Management (Admin) + +### AC-ADMIN-001 — Superadmin สร้าง Organization +**Priority:** 🔴 Blocker | **Role:** Superadmin + +| | Description | +|---|---| +| **Given** | Login ด้วย Superadmin Account | +| **When** | สร้าง Organization ใหม่ กรอกชื่อ + รหัสองค์กร | +| **Then** | ✅ Organization ถูกสร้างในฐานข้อมูล | +| | ✅ สามารถกำหนด Org Admin ได้ทันที | +| | ✅ Audit Log บันทึก `ORGANIZATION_CREATED` | + +### AC-ADMIN-002 — Superadmin สร้าง Project + Contract +**Priority:** 🔴 Blocker | **Role:** Superadmin + +| | Description | +|---|---| +| **Given** | มี Organization อย่างน้อย 1 ที่ | +| **When** | สร้าง Project → สร้าง Contract ภายใน Project | +| **Then** | ✅ Project ผูกกับ Organization ได้หลายองค์กร | +| | ✅ Contract ผูกกับ Project (1 Contract ต่อ Contractor) | +| | ✅ การตั้งค่า Document Number Format สำหรับ Project ทำได้ | + +### AC-ADMIN-003 — Org Admin เพิ่ม User เข้า Organization +**Priority:** 🟠 Critical | **Role:** Org Admin + +| | Description | +|---|---| +| **Given** | Login ด้วย Org Admin | +| **When** | เพิ่ม User พร้อม Role (Editor/Viewer/Document Control) | +| **Then** | ✅ User ได้รับ Email แจ้ง Credentials | +| | ✅ User Login แล้วเห็น Dashboard ขององค์กรตัวเอง | +| | ✅ Permission ถูก Cache ใน Redis (ภายใน 30 วินาที) | + +### AC-ADMIN-004 — Permission Isolation ระหว่าง Contractor +**Priority:** 🔴 Blocker | **Role:** Document Control (Contractor A) + +| | Description | +|---|---| +| **Given** | มี Contractor A (Contract 1) และ Contractor B (Contract 2) | +| **When** | Contractor A Login แล้วพยายาม เข้าดู Document ของ Contractor B | +| **Then** | ✅ ได้รับ 403 Forbidden | +| | ✅ Contractor A ไม่เห็น Document ของ Contractor B ในรายการ | +| | ✅ Audit Log บันทึกความพยายาม Unauthorized Access | + +### AC-ADMIN-005 — Permission Cache Invalidation +**Priority:** 🟠 Critical | **Role:** Superadmin + +| | Description | +|---|---| +| **Given** | User กำลัง Login อยู่และมี Permission Cache ใน Redis | +| **When** | Superadmin เปลี่ยน Role ของ User นั้น | +| **Then** | ✅ Redis Cache ของ User นั้นถูกล้างทันที | +| | ✅ Request ถัดไปของ User ใช้ Permission ใหม่ (ภายใน 1 request cycle) | + +--- + +## 📨 Module 3: Correspondence Management + +### AC-CORR-001 — สร้าง Correspondence (Draft) +**Priority:** 🔴 Blocker | **Role:** Document Control + +| | Description | +|---|---| +| **Given** | Login ด้วย Document Control ขององค์กรใด | +| **When** | สร้าง Correspondence ใหม่ (Letter/RFI) กรอก Subject, To, CC, แนบไฟล์ PDF | +| **Then** | ✅ เอกสารถูกบันทึกในสถานะ `DRAFT` | +| | ✅ ผู้ใช้ขององค์กรอื่น **ไม่เห็น** Draft นี้ | +| | ✅ ผู้สร้างเห็นใน "เอกสารฉบับร่างของฉัน" | + +### AC-CORR-002 — Submit Correspondence + Auto Document Number +**Priority:** 🔴 Blocker | **Role:** Document Control + +| | Description | +|---|---| +| **Given** | มี Correspondence ในสถานะ Draft พร้อม Attachment | +| **When** | กด Submit | +| **Then** | ✅ ระบบออกเลขเอกสารอัตโนมัติตาม Format Template (เช่น `LCBP3-สคฉ-กทท-LETTER-0001-68`) | +| | ✅ เลขเอกสารไม่ซ้ำกัน แม้ Submit พร้อมกันหลาย Request | +| | ✅ สถานะเปลี่ยนเป็น `SUBMITTED` | +| | ✅ Workflow Instance ถูกสร้างใน `workflow_instances` | +| | ✅ องค์กรผู้รับ (To) ได้รับแจ้งเตือน (Email + In-App) | + +### AC-CORR-003 — ผู้รับ Correspondence +**Priority:** 🔴 Blocker | **Role:** Document Control (Recipient Org) + +| | Description | +|---|---| +| **Given** | Correspondence ถูก Submit มายังองค์กรเรา | +| **When** | Document Control ขององค์กรผู้รับ เปิดดู | +| **Then** | ✅ เห็นเอกสารใน Inbox/Received | +| | ✅ สามารถสร้าง Circulation Sheet ได้ | +| | ✅ สามารถดาวน์โหลดไฟล์แนบได้ | + +### AC-CORR-004 — อ้างอิงเอกสารก่อนหน้า (References) +**Priority:** 🟡 Major | **Role:** Document Control + +| | Description | +|---|---| +| **Given** | มีเอกสาร Correspondence เก่าในระบบ | +| **When** | สร้าง Correspondence ใหม่และอ้างอิงเอกสารเก่า | +| **Then** | ✅ Link เชื่อมระหว่างเอกสารทั้งสอง | +| | ✅ สามารถคลิก Navigate ไปดูเอกสารที่อ้างถึงได้ | + +### AC-CORR-005 — Cancel Correspondence (Admin Only) +**Priority:** 🟡 Major | **Role:** Org Admin / Superadmin + +| | Description | +|---|---| +| **Given** | Correspondence ถูก Submit แล้ว (สถานะ SUBMITTED+) | +| **When** | Admin กด Cancel พร้อมระบุเหตุผล | +| **Then** | ✅ สถานะเปลี่ยนเป็น `CANCELLED` | +| | ✅ ต้องระบุ `cancel_reason` (ไม่ยอม Empty) | +| | ✅ Audit Log บันทึกพร้อมเหตุผล | +| | ✅ User ระดับ Viewer/Editor ทำ Cancel ไม่ได้ → 403 | + +--- + +## 📋 Module 4: RFA Management + +### AC-RFA-001 — สร้าง RFA + แนบ Shop Drawing +**Priority:** 🔴 Blocker | **Role:** Document Control (Contractor) + +| | Description | +|---|---| +| **Given** | Login ด้วย Document Control ของ Contractor | +| **When** | สร้าง RFA ใหม่ — กรอก RFA Type, Discipline, แนบ Shop Drawing (PDF/DWG/ZIP) | +| **Then** | ✅ RFA ถูกบันทึกในสถานะ `DRAFT` | +| | ✅ Shop Drawing ผูกกับ RFA (1 Revision = 1 RFA) | +| | ✅ ไฟล์ถูก Scan ด้วย ClamAV — ปฏิเสธไฟล์ที่ติด Virus | + +### AC-RFA-002 — Submit RFA + Auto Number +**Priority:** 🔴 Blocker | **Role:** Document Control (Contractor) + +| | Description | +|---|---| +| **Given** | RFA Draft พร้อม Shop Drawing | +| **When** | กด Submit | +| **Then** | ✅ เลขที่ RFA ถูกออกอัตโนมัติตาม Format (`LCBP3-RFA-STR-0001`) | +| | ✅ เลขไม่ reset ตามปี (RFA = No reset policy) | +| | ✅ สถานะ = `SUBMITTED` | +| | ✅ Workflow Routing เริ่มทำงาน (ส่งไปยัง Reviewer) | + +### AC-RFA-003 — Review RFA (Approved) +**Priority:** 🔴 Blocker | **Role:** Engineer/Reviewer (Supervisor Org) + +| | Description | +|---|---| +| **Given** | RFA อยู่ในสถานะรอ Review ที่องค์กรเรา | +| **When** | Engineer คลิก "Approved" | +| **Then** | ✅ สถานะ RFA เปลี่ยนเป็น `APPROVED` | +| | ✅ Originator (Contractor) ได้รับแจ้งเตือน | +| | ✅ Workflow History บันทึก Action + Timestamp + User | + +### AC-RFA-004 — Review RFA (Approved with Comments) +**Priority:** 🟠 Critical | **Role:** Engineer/Reviewer + +| | Description | +|---|---| +| **Given** | RFA อยู่ในสถานะรอ Review | +| **When** | Engineer คลิก "Approved with Comments" + กรอก Comment | +| **Then** | ✅ สถานะ = `APPROVED_WITH_COMMENTS` | +| | ✅ Comment ถูกบันทึกใน Workflow History | +| | ✅ Originator เห็น Comment ได้ | + +### AC-RFA-005 — Review RFA (Rejected) +**Priority:** 🟠 Critical | **Role:** Engineer/Reviewer + +| | Description | +|---|---| +| **Given** | RFA อยู่ในสถานะรอ Review | +| **When** | Engineer คลิก "Rejected" + ระบุเหตุผล | +| **Then** | ✅ สถานะ = `REJECTED` | +| | ✅ เหตุผลการ Reject บันทึกครบถ้วน | +| | ✅ Contractor สามารถยื่น RFA Revision ใหม่ได้ | + +### AC-RFA-006 — Revision RFA +**Priority:** 🟠 Critical | **Role:** Document Control (Contractor) + +| | Description | +|---|---| +| **Given** | RFA Rev.A ถูก Rejected แล้ว | +| **When** | Contractor สร้าง RFA Revision ใหม่ (Rev.B) | +| **Then** | ✅ Rev.B ผูกกับ shop_drawing revision ใหม่ | +| | ✅ เลขที่เอกสารเดิม — Revision Code เปลี่ยน (เช่น `-B`) | +| | ✅ Rev.A ยังอ่านได้ (ไม่ถูกลบ) | + +--- + +## 📐 Module 5: Drawing Management + +### AC-DRW-001 — Upload Contract Drawing +**Priority:** 🟠 Critical | **Role:** Document Control (Design Consultant) + +| | Description | +|---|---| +| **Given** | Login ด้วย Document Control ที่มีสิทธิ์ Contract Drawing | +| **When** | Upload แบบคู่สัญญา (PDF) พร้อมระบุ หมวดหมู่ / Drawing Number | +| **Then** | ✅ Drawing ถูกบันทึกในระบบ | +| | ✅ สามารถอ้างอิงจาก Shop Drawing ได้ | +| | ✅ ไม่สามารถแก้ไขได้โดยไม่มีสิทธิ์ | + +### AC-DRW-002 — Upload Shop Drawing + Link to Contract Drawing +**Priority:** 🟠 Critical | **Role:** Document Control (Contractor) + +| | Description | +|---|---| +| **Given** | มี Contract Drawing ในระบบแล้ว | +| **When** | Upload Shop Drawing พร้อมระบุ Referenced Contract Drawing | +| **Then** | ✅ Shop Drawing ผูก Reference กับ Contract Drawing | +| | ✅ สามารถ Navigate ไปดู Contract Drawing ที่อ้างถึงได้ | + +### AC-DRW-003 — Shop Drawing Revision Control +**Priority:** 🟠 Critical | **Role:** Document Control + +| | Description | +|---|---| +| **Given** | Shop Drawing Rev.A มีอยู่แล้ว | +| **When** | Upload Shop Drawing Rev.B | +| **Then** | ✅ Rev.B ถือเป็น Current Revision | +| | ✅ Rev.A ยังสามารถดูได้ (ไม่ถูกลบ) | +| | ✅ 1 Shop Drawing Revision ผูกกับ RFA ได้ 1 ฉบับเท่านั้น | + +--- + +## ⚙️ Module 6: Unified Workflow Engine + +### AC-WF-001 — Workflow Instance Creation +**Priority:** 🔴 Blocker | **Role:** ระบบ (Auto) + +| | Description | +|---|---| +| **Given** | Document ถูก Submit | +| **When** | ระบบสร้าง Workflow Instance | +| **Then** | ✅ `workflow_instances` record ถูกสร้าง | +| | ✅ `current_state` = Initial State ตาม DSL | +| | ✅ `entity_type` และ `entity_id` ถูกต้อง | + +### AC-WF-002 — Workflow State Transition (Happy Path) +**Priority:** 🔴 Blocker | **Role:** ตาม Workflow Role + +| | Description | +|---|---| +| **Given** | Workflow อยู่ใน State A | +| **When** | User ที่มีสิทธิ์ทำ Action ที่กำหนดใน DSL | +| **Then** | ✅ State เปลี่ยนเป็น State B ตาม Transition Rules | +| | ✅ `workflow_histories` บันทึก from_state, to_state, action, user_id, timestamp | +| | ✅ Event Notifications ถูก Dispatch (ถ้า DSL กำหนด) | + +### AC-WF-003 — Workflow Unauthorized Transition +**Priority:** 🔴 Blocker | **Role:** User ไม่ถูก Role + +| | Description | +|---|---| +| **Given** | Workflow รอ Approve โดย Role X | +| **When** | User ที่เป็น Role Y (ไม่ใช่ X) พยายาม Approve | +| **Then** | ✅ ได้รับ 403 Forbidden | +| | ✅ State ไม่เปลี่ยน | + +### AC-WF-004 — Workflow Visualization (UI) +**Priority:** 🟡 Major | **Role:** ทุก Role ที่มีสิทธิ์ดูเอกสาร + +| | Description | +|---|---| +| **Given** | Workflow กำลังดำเนินการอยู่ | +| **When** | เปิดดูหน้ารายละเอียดเอกสาร | +| **Then** | ✅ แสดง Workflow Diagram พร้อม State ปัจจุบัน | +| | ✅ State ที่ผ่านมาแล้วแสดง History (คลิกดูรายละเอียดได้) | +| | ✅ State ที่ยังไม่ถึง Disabled | + +### AC-WF-005 — Force Proceed (Document Control Override) +**Priority:** 🟡 Major | **Role:** Document Control + +| | Description | +|---|---| +| **Given** | Workflow ติดอยู่ที่ State ใด State หนึ่ง | +| **When** | Document Control กด "Force Proceed" พร้อมระบุเหตุผล | +| **Then** | ✅ Workflow ข้ามไป State ถัดไป | +| | ✅ Audit Log บันทึก `FORCE_PROCEED` + reason + user | + +### AC-WF-006 — Workflow Deadline & Notification +**Priority:** 🟡 Major | **Role:** Document Control + +| | Description | +|---|---| +| **Given** | Workflow ถูกกำหนด Deadline สำหรับ Organization | +| **When** | เวลาผ่าน Deadline ไปแล้ว | +| **Then** | ✅ ระบบส่ง Reminder Notification ให้ผู้รับผิดชอบ | +| | ✅ Dashboard แสดง "Overdue" indicator | + +--- + +## 📧 Module 7: Transmittals Management + +### AC-TRM-001 — สร้าง Transmittal (ส่ง RFA หลายฉบับพร้อมกัน) +**Priority:** 🟠 Critical | **Role:** Document Control + +| | Description | +|---|---| +| **Given** | มี RFA Draft หลายฉบับต้องส่งให้ที่ปรึกษา | +| **When** | สร้าง Transmittal แนบ RFA หลายฉบับ | +| **Then** | ✅ Transmittal ผูกกับ RFA ทุกฉบับ | +| | ✅ Transmittal เป็นส่วนหนึ่งใน Correspondence (มีเลขเอกสาร) | +| | ✅ ผู้รับเห็น Transmittal พร้อม RFA ที่แนบ | + +--- + +## 📄 Module 8: Circulation Sheet Management + +### AC-CIRC-001 — สร้าง Circulation Sheet +**Priority:** 🟠 Critical | **Role:** Document Control (ภายในองค์กร) + +| | Description | +|---|---| +| **Given** | Correspondence เข้ามาในองค์กร | +| **When** | Document Control สร้าง Circulation Sheet กำหนด Main/Action/Info Assignees | +| **Then** | ✅ Circulation ถูกสร้าง ผูกกับ Correspondence | +| | ✅ Assignees ได้รับแจ้งเตือน (In-App + Email) | +| | ✅ ผู้ใช้นอกองค์กรไม่เห็น Circulation Sheet นี้ | + +### AC-CIRC-002 — กำหนด Deadline + แจ้งเตือนล่วงหน้า +**Priority:** 🟡 Major | **Role:** Document Control + +| | Description | +|---|---| +| **Given** | Circulation ถูกกำหนด Deadline ให้ Main Assignee | +| **When** | เหลืออีก 2 วันก่อน Deadline | +| **Then** | ✅ ระบบส่งแจ้งเตือน Reminder | +| | ✅ Dashboard แสดง "ใกล้ Deadline" badge | + +### AC-CIRC-003 — ปิด Circulation +**Priority:** 🟠 Critical | **Role:** Document Control + +| | Description | +|---|---| +| **Given** | ดำเนินการตอบกลับ Originator แล้ว | +| **When** | กด "ปิด Circulation" | +| **Then** | ✅ Circulation สถานะ = `CLOSED` | +| | ✅ Audit Log บันทึก closed_by + timestamp | + +--- + +## 🔢 Module 9: Document Numbering System + +### AC-DN-001 — Auto Number Generation (Concurrent Safe) +**Priority:** 🔴 Blocker | **Role:** ระบบ (Auto) + +| | Description | +|---|---| +| **Given** | User 2 คนกด Submit พร้อมกัน ใน Project/Type เดียวกัน | +| **When** | ทั้งสองส่ง Request พร้อมกัน | +| **Then** | ✅ เลขเอกสารไม่ซ้ำกัน (Redis Redlock + DB Optimistic Lock) | +| | ✅ Response Time < 100ms สำหรับ Generation | +| | ✅ ทั้งสอง Request สำเร็จ — ไม่มี Error | + +> **Test Method:** Load Test ด้วย 50 concurrent requests ไปที่ `POST /document-numbering/reserve` — ตรวจสอบว่าเลขไม่ซ้ำ + +### AC-DN-002 — Cancelled Number ไม่ถูกนำกลับมาใช้ +**Priority:** 🔴 Blocker | **Role:** ระบบ + +| | Description | +|---|---| +| **Given** | เลขที่ 0012 ถูก Reserved แต่ Document ถูก Cancel ก่อน Confirm | +| **When** | มีการ Submit Document ถัดไป | +| **Then** | ✅ เลขที่ถัดไปจะเป็น 0013 (ข้าม 0012) | +| | ✅ เลข 0012 อยู่ใน `document_number_reservations` สถานะ `CANCELLED` | + +### AC-DN-003 — Number Format Template +**Priority:** 🟡 Major | **Role:** Superadmin + +| | Description | +|---|---| +| **Given** | กำหนด Format Template: `{PROJECT}-{ORIGINATOR}-{RECIPIENT}-{CORR_TYPE}-{SEQ:4}-{YY}` | +| **When** | Submit Document ครั้งแรกของปีสำหรับ Pair นั้น | +| **Then** | ✅ เลขออกมาถูก Format (เช่น `LCBP3-สค.-กทท.-LETTER-0001-68`) | +| | ✅ Preview ตัวอย่างเลขได้ก่อน Save Template | + +### AC-DN-004 — Yearly Reset +**Priority:** 🟡 Major | **Role:** ระบบ (Cron) + +| | Description | +|---|---| +| **Given** | Correspondence ใช้ Yearly Reset Policy | +| **When** | ปีใหม่เปลี่ยน (Cron Job ทำงาน) | +| **Then** | ✅ Counter เริ่มนับใหม่จาก 0001 | +| | ✅ เลขของปีก่อนยังคงอยู่ในระบบ (ไม่ถูกลบ) | + +--- + +## 🔍 Module 10: Search & Discovery + +### AC-SRCH-001 — Full-text Search +**Priority:** 🟠 Critical | **Role:** ทุก Role + +| | Description | +|---|---| +| **Given** | มีเอกสารในระบบ (Indexed ใน Elasticsearch) | +| **When** | พิมพ์ค้นหา Keyword ในช่อง Search | +| **Then** | ✅ ผล Search ปรากฏภายใน 500ms | +| | ✅ ค้นหาได้จาก: เลขเอกสาร, Subject, Tag | +| | ✅ แสดงเฉพาะเอกสารที่ User มีสิทธิ์เห็น | + +### AC-SRCH-002 — Advanced Filter +**Priority:** 🟡 Major | **Role:** ทุก Role + +| | Description | +|---|---| +| **Given** | อยู่ในหน้า Correspondence List | +| **When** | Filter ด้วย Document Type + Date Range + Status | +| **Then** | ✅ รายการ Filter ถูกต้อง | +| | ✅ URL อัปเดตให้ Shareable (Query Params) | + +--- + +## 📧 Module 11: Notifications + +### AC-NOTIF-001 — Email Notification (Document Submit) +**Priority:** 🟠 Critical | **Role:** ระบบ (Auto) + +| | Description | +|---|---| +| **Given** | Document ถูก Submit มายังองค์กร | +| **When** | Workflow Transition เกิดขึ้น | +| **Then** | ✅ Email ถูกส่งไปยัง Recipient ภายใน 5 นาที | +| | ✅ Email มี: เลขเอกสาร, Subject, ลิงก์ไปยังเอกสาร | +| | ✅ BullMQ Job อยู่ใน Queue (สามารถ Monitor ได้) | + +### AC-NOTIF-002 — In-App Notification +**Priority:** 🟡 Major | **Role:** ทุก Role + +| | Description | +|---|---| +| **Given** | มี Action เกิดขึ้นที่เกี่ยวข้องกับ User | +| **When** | User เปิดแอป | +| **Then** | ✅ Bell Icon แสดง Unread Count | +| | ✅ คลิกดูรายการ Notifications ได้ | +| | ✅ คลิกที่ Notification นำทางไปเอกสารที่เกี่ยวข้อง | + +### AC-NOTIF-003 — Notification Retry on Failure +**Priority:** 🟡 Major | **Role:** ระบบ + +| | Description | +|---|---| +| **Given** | Email Server ไม่สามารถส่งได้ชั่วคราว | +| **When** | BullMQ Job ส่งไม่สำเร็จ | +| **Then** | ✅ Retry ด้วย Exponential Backoff (3 ครั้ง) | +| | ✅ เมื่อ Retry ครบแล้วยังล้มเหลว → Dead Letter Queue | +| | ✅ In-App Notification ยังส่งได้ (Fallback) | + +--- + +## 📎 Module 12: File Storage & Security + +### AC-STOR-001 — File Upload (Two-Phase Storage) +**Priority:** 🔴 Blocker | **Role:** Document Control + +| | Description | +|---|---| +| **Given** | User อัปโหลดไฟล์ PDF ขนาด 50MB | +| **When** | เลือกไฟล์ + อัปโหลด | +| **Then** | ✅ ไฟล์ถูก Upload ไปยัง Temp Storage ก่อน | +| | ✅ ClamAV Scan ในเวลา < 30 วินาที | +| | ✅ หากผ่าน Scan → ย้ายไปยัง Permanent Storage เมื่อ Document Confirmed | +| | ✅ หากไม่ผ่าน Scan → ปฏิเสธพร้อมแสดง Security Warning | + +### AC-STOR-002 — File Type Restriction +**Priority:** 🔴 Blocker | **Role:** Document Control + +| | Description | +|---|---| +| **Given** | User พยายาม Upload ไฟล์ .exe หรือ .js | +| **When** | เลือกไฟล์นอก Whitelist | +| **Then** | ✅ Frontend Block ก่อน Upload | +| | ✅ Backend ยืนยันซ้ำ (Defense in Depth) — 400 Bad Request | + +### AC-STOR-003 — Secure PDF Viewer (No Download) +**Priority:** 🟡 Major | **Role:** Viewer + +| | Description | +|---|---| +| **Given** | User มีสิทธิ์ดูเอกสารแต่ไม่มีสิทธิ์ Download | +| **When** | คลิกดูเอกสาร PDF | +| **Then** | ✅ เปิดใน In-App PDF Viewer (ไม่ต้อง Download) | +| | ✅ ปุ่ม Download ถูก Disable | +| | ✅ Range Requests (Streaming) ใช้งานได้ | + +--- + +## 📊 Module 13: Dashboard & Audit Log + +### AC-DASH-001 — Dashboard KPI Cards +**Priority:** 🟡 Major | **Role:** ทุก Role + +| | Description | +|---|---| +| **Given** | Login เสร็จ | +| **When** | เข้าหน้า Dashboard | +| **Then** | ✅ KPI Cards แสดง: จำนวน Correspondence, RFA Pending, งานของฉัน, Overdue | +| | ✅ "My Tasks" แสดง Circulation ที่ตัวเองต้องทำ | +| | ✅ ข้อมูลถูกต้องตามสิทธิ์ของตัวเอง | + +### AC-AUDIT-001 — Audit Log Coverage +**Priority:** 🔴 Blocker | **Role:** Superadmin + +| | Description | +|---|---| +| **Given** | ดำเนินการ Action ต่างๆ ในระบบ (Create, Update, Submit, Approve) | +| **When** | ตรวจสอบ Audit Log | +| **Then** | ✅ ทุก Action มีบันทึกใน `audit_logs` | +| | ✅ บันทึกมี: user_id, action, entity_type, entity_id, ip_address, timestamp | +| | ✅ ไม่สามารถแก้ไขหรือลบ Audit Log ได้ (Read-only) | + +--- + +## 🔐 Section 14: Security Acceptance Criteria + +### AC-SEC-001 — SQL Injection Prevention +**Priority:** 🔴 Blocker | **Role:** QA (Security Test) + +| | Description | +|---|---| +| **Given** | ช่อง Input ใดๆ ในระบบ | +| **When** | ใส่ SQL Injection payload เช่น `'; DROP TABLE users; --` | +| **Then** | ✅ คำขอถูกปฏิเสธหรือ Sanitized โดยไม่ทำงาน | +| | ✅ Database ปลอดภัย ไม่เกิด Error จาก Injection | + +### AC-SEC-002 — XSS Prevention +**Priority:** 🔴 Blocker | **Role:** QA (Security Test) + +| | Description | +|---|---| +| **Given** | ช่อง Input เช่น Subject, Comment | +| **When** | ใส่ `` | +| **Then** | ✅ Script ไม่ถูก Execute ใน Browser | +| | ✅ แสดงเป็น Plaintext หรือถูก Escaped | + +### AC-SEC-003 — Authorization Boundary (IDOR Protection) +**Priority:** 🔴 Blocker | **Role:** QA (Security Test) + +| | Description | +|---|---| +| **Given** | User A รู้ Document ID ของ User B | +| **When** | User A เรียก `GET /correspondences/:id` ของ User B โดยตรง | +| **Then** | ✅ ได้รับ 403 Forbidden (ไม่ใช่ 404) | +| | ✅ ข้อมูลของ User B ไม่ถูกเปิดเผย | + +### AC-SEC-004 — Rate Limiting on Auth Endpoint +**Priority:** 🔴 Blocker | **Role:** QA (Security Test) + +| | Description | +|---|---| +| **Given** | ไม่มี Session อยู่ | +| **When** | เรียก `POST /auth/login` เกิน 5 ครั้งใน 1 นาที จาก IP เดียว | +| **Then** | ✅ ครั้งที่ 6+ ได้รับ 429 Too Many Requests | +| | ✅ Audit Log บันทึก Rate Limit Event | + +### AC-SEC-005 — Security Headers +**Priority:** 🟠 Critical | **Role:** QA + +| | Description | +|---|---| +| **Given** | ระบบทำงานบน HTTPS | +| **When** | ตรวจสอบ HTTP Response Headers | +| **Then** | ✅ `X-Content-Type-Options: nosniff` | +| | ✅ `X-Frame-Options: DENY` | +| | ✅ `Strict-Transport-Security` present | +| | ✅ `Content-Security-Policy` defined | + +--- + +## ⚡ Section 15: Performance Acceptance Criteria + +### AC-PERF-001 — API Response Time +**Priority:** 🟠 Critical + +| | Description | +|---|---| +| **Test Condition** | 50 concurrent users, Normal workload | +| **Then** | ✅ P90 Response Time < 200ms สำหรับ CRUD operations | +| | ✅ P90 Search Query < 500ms | +| | ✅ File Upload 50MB < 30 seconds | + +> **Test Tool:** k6 หรือ Apache JMeter +> **Test Script:** `specs/05-Engineering-Guidelines/performance-test-script.js` (TODO: สร้าง) + +### AC-PERF-002 — Concurrent Users +**Priority:** 🟠 Critical + +| | Description | +|---|---| +| **Test Condition** | 100 concurrent active users | +| **Then** | ✅ ระบบไม่ crash หรือ Error Rate > 1% | +| | ✅ Memory ไม่เกิน 80% ของ Container Limit | +| | ✅ CPU ไม่เกิน 80% sustained | + +### AC-PERF-003 — Document Number Concurrent +**Priority:** 🔴 Blocker + +| | Description | +|---|---| +| **Test Condition** | 50 concurrent POST `/document-numbering/reserve` สำหรับ Project/Type เดียวกัน | +| **Then** | ✅ เลขเอกสารไม่ซ้ำกันทั้ง 50 Request | +| | ✅ ทุก Request สำเร็จ (ไม่มี 5xx Error) | + +--- + +## 💾 Section 16: Data Integrity & Recovery + +### AC-DATA-001 — Backup & Restore +**Priority:** 🔴 Blocker | **Role:** DevOps + +| | Description | +|---|---| +| **Given** | Production Database มีข้อมูล 1 วันทำการ | +| **When** | ทดสอบ Restore จาก Backup ล่าสุด | +| **Then** | ✅ Restore สำเร็จภายใน RTO < 4 ชั่วโมง | +| | ✅ ข้อมูลสมบูรณ์ ไม่มี Data Loss เกิน RPO < 1 ชั่วโมง | +| | ✅ ระบบทำงานปกติหลัง Restore | + +### AC-DATA-002 — Orphan File Prevention +**Priority:** 🟠 Critical | **Role:** ระบบ + +| | Description | +|---|---| +| **Given** | User อัปโหลดไฟล์ไปยัง Temp แล้ว Cancel Document ก่อน Confirm | +| **When** | Cleanup Job ทำงาน | +| **Then** | ✅ ไฟล์ใน Temp Storage ถูกลบ | +| | ✅ Permanent Storage ไม่มี Orphan Files | + +--- + +## ✅ UAT Sign-off Checklist + +### Pre-UAT Conditions +- [ ] ระบบ Deploy บน Staging Environment (ใช้ Docker Compose เหมือน Production) +- [ ] Seed Data ตาม `lcbp3-v1.8.0-seed-basic.sql` และ `seed-permissions.sql` +- [ ] Test Users ทุก Role ถูกสร้าง (Superadmin, Org Admin, Document Control, Editor, Viewer) +- [ ] Email + LINE Notify Test Mode เปิดใช้งาน + +### Go-Live Criteria (ต้องผ่านทั้งหมด) + +| # | Criteria | Status | +|---|----------|--------| +| 1 | AC-AUTH-001 ~ AC-AUTH-005 ผ่านทั้งหมด | ⬜ | +| 2 | AC-ADMIN-001 ~ AC-ADMIN-005 ผ่านทั้งหมด | ⬜ | +| 3 | AC-CORR-001 ~ AC-CORR-002 (Happy Path) ผ่าน | ⬜ | +| 4 | AC-RFA-001 ~ AC-RFA-003 (Submit + Approve) ผ่าน | ⬜ | +| 5 | AC-WF-001 ~ AC-WF-003 (Workflow Engine Core) ผ่าน | ⬜ | +| 6 | AC-DN-001 (Concurrent Number) ผ่าน | ⬜ | +| 7 | AC-STOR-001 (Two-Phase Storage + ClamAV) ผ่าน | ⬜ | +| 8 | AC-SEC-001 ~ AC-SEC-004 (Security) ผ่านทั้งหมด | ⬜ | +| 9 | AC-PERF-001 (Response Time) ผ่าน | ⬜ | +| 10 | AC-DATA-001 (Backup & Restore DR Test) ผ่าน | ⬜ | +| 11 | AC-AUDIT-001 (Audit Log Coverage) ผ่าน | ⬜ | +| 12 | ไม่มี Bug Priority P0/P1 ค้างอยู่ | ⬜ | + +### UAT Participant Sign-off + +| Organization | Representative | Signature | Date | +|-------------|----------------|-----------|------| +| กทท. (Owner) | | | | +| สค. (Admin) | | | | +| TEAM (Design Consultant) | | | | +| คคง. (Supervisor) | | | | +| ผรม. (Contractor Rep.) | | | | +| NAP (Developer) | Nattanin P. | | | + +--- + +## 📝 Document Control + +- **Version:** 1.0.0 +- **Status:** DRAFT — Pending Stakeholder Sign-off +- **Created:** 2026-03-11 +- **Owner:** Nattanin Peancharoen (Product Owner / System Architect) +- **Next Review:** Prior to UAT Start +- **Classification:** Internal Use Only + +--- + +> [!NOTE] +> เอกสารนี้ต้องได้รับการ Sign-off จาก Stakeholder ทุกฝ่ายก่อนเริ่ม UAT +> ดู Gap 5 (Stakeholder Sign-off) ใน `po-analysis.md` สำหรับ Process การอนุมัติ diff --git a/specs/01-requirements/01-06-edge-cases-and-rules.md b/specs/01-requirements/01-06-edge-cases-and-rules.md new file mode 100644 index 0000000..9cc2159 --- /dev/null +++ b/specs/01-requirements/01-06-edge-cases-and-rules.md @@ -0,0 +1,642 @@ +# 🛡️ Module Edge Cases & Business Rules — LCBP3-DMS v1.8.0 + +--- +title: 'Edge Cases, Business Rules, and Anti-Bug Specifications' +version: 1.0.0 +status: DRAFT +owner: Nattanin Peancharoen (Product Owner / System Architect) +last_updated: 2026-03-11 +related: + - specs/01-Requirements/01-05-acceptance-criteria.md + - specs/01-Requirements/01-02-business-rules/01-02-02-doc-numbering-rules.md + - specs/06-Decision-Records/ADR-001-unified-workflow-engine.md + - specs/06-Decision-Records/ADR-016-security-authentication.md + - specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql +--- + +> [!IMPORTANT] +> เอกสารนี้ระบุ **Edge Cases ที่ต้อง Implement และ Test อย่างชัดเจน** เพื่อป้องกัน Bug ในระบบ Prod +> ทุก Edge Case มี **Expected Behavior** ที่ Developer และ QA ต้องยึดถือ + +--- + +## 📐 วิธีอ่าน + +- **EC-[MODULE]-[NNN]** = Edge Case ID +- **Severity:** 🔴 Critical | 🟠 High | 🟡 Medium +- **Type:** `Data Integrity` | `Security` | `Concurrency` | `UX` | `Business Rule` + +--- + +## Module 1: Document Numbering Edge Cases + +### EC-DN-001 — Concurrent Submission (Race Condition) +**Severity:** 🔴 Critical | **Type:** Concurrency, Data Integrity + +**Scenario:** User A และ User B กด Submit Correspondence พร้อมกันทุก millisecond สำหรับ Project/Type/Sender/Receiver เดียวกัน + +**Expected Behavior:** +- ทั้งสองได้รับเลขเอกสาร **ต่างกัน** (เช่น 0001 และ 0002) +- ไม่มีเลข Duplicate ในระบบ +- API ทั้งสองตอบ 201 Created สำเร็จ + +**Implementation Rule:** +``` +1. Redis Redlock acquire บน counterKey ก่อน +2. ถ้า Lock ไม่ได้ใน 5 วินาที → 503 Service Unavailable (Retry-After: 3s) +3. DB SELECT FOR UPDATE อีกชั้น (Defense in Depth) +4. Increment counter → COMMIT → Release Lock +5. ห้ามใช้ AUTO_INCREMENT ของ DB โดยตรงสำหรับเลขเอกสาร +``` + +**Test Method:** Load Test 50 concurrent POST `/document-numbering/reserve` → Assert DISTINCT count = 50 + +--- + +### EC-DN-002 — Yearly Reset Boundary Condition +**Severity:** 🟠 High | **Type:** Business Rule, Data Integrity + +**Scenario A:** Document ถูก Submit เวลา 23:59:59 วันที่ 31 ธันวาคม +**Scenario B:** Cron Job Reset Counter ทำงานตอนเที่ยงคืน แต่มี Document ในสถานะ RESERVED อยู่ + +**Expected Behavior (A):** +- ได้รับเลขของปีเก่า (counter ปีเก่า) — เวลา Submit คือที่กำหนด +- ถ้า Confirm หลังเที่ยงคืน → เลขยังเป็นของปีเก่า (ใช้เวลา Reserve ไม่ใช่ Confirm) + +**Expected Behavior (B):** +- Cron Job ต้อง **Skip** เลขที่อยู่ใน RESERVED state — ไม่ Reset Counter จนกว่า Reservation จะ Expire หรือ Confirmed +- ถ้า Reset รันก่อน Expiry: Counter ใหม่เริ่ม 0001 แต่ Reserved เลขยังคงอยู่ (ไม่ถูก Overwrite) + +**Implementation Rule:** +``` +- Cron Job ติด Lock เดียวกับ Reserve Process ก่อน Reset +- Reset scope = 'YEAR_2025' → Counter Key ใหม่ = 'YEAR_2026' +- ไม่ Delete counter เก่า — แค่ Key ใหม่ +``` + +--- + +### EC-DN-003 — Cancelled/Voided Number Must Not Reuse +**Severity:** 🔴 Critical | **Type:** Business Rule, Data Integrity + +**Scenario:** Document ถูก Submit → ได้เลข 0005 → Admin Cancel Document → User Submit ใหม่ + +**Expected Behavior:** +- เลขถัดไปต้อง **0006** ไม่ใช่ 0005 +- เลข 0005 อยู่ใน `document_number_reservations` สถานะ CANCELLED ตลอดไป +- ไม่มีการ Reuse เลขที่ถูก Cancel เด็ดขาด + +**Business Rule:** "เลขที่ออกแล้วต้องไปข้างหน้าเท่านั้น — ห้ามถอยหลัง" + +--- + +### EC-DN-004 — Reservation TTL Expired Cleanup +**Severity:** 🟠 High | **Type:** Data Integrity, UX + +**Scenario:** User Reserve เลข (TTL 5 นาที) แต่ Browser ปิดก่อน Confirm + +**Expected Behavior:** +- หลัง 5 นาที → `document_number_reservations.status` เปลี่ยนเป็น EXPIRED (by Cron/TTL) +- Counter ไม่ถูก Decrement (เลขนั้นหายไปถาวร — ฟัน-หลอ-เลข เป็นที่ยอมรับ) +- ถ้า User กลับมา Confirm Token ที่ Expired → 410 Gone (Token expired) + +**Implementation Rule:** +```sql +-- Cron ทุก 1 นาที +UPDATE document_number_reservations +SET status = 'EXPIRED' +WHERE status = 'RESERVED' AND expires_at < NOW(); +``` + +--- + +### EC-DN-005 — Idempotency Key Duplicate Submission +**Severity:** 🟠 High | **Type:** Concurrency, UX + +**Scenario:** Network ไม่เสถียร → User คลิก Submit 2 ครั้ง → Frontend ส่ง POST 2 ครั้งด้วย Idempotency-Key เดียวกัน + +**Expected Behavior:** +- Request แรก → ออกเลขใหม่ → 201 Created +- Request ที่สอง (same Idempotency-Key) → **Return เลขเดิม** → 200 OK (ไม่ออกเลขใหม่) +- ไม่ว่า Request ที่สองจะมาเร็วแค่ไหน + +**Implementation Rule:** Cache Idempotency-Key ใน Redis (TTL 24h) → ถ้า Key เจอ → Return Cached Response + +--- + +## Module 2: Workflow Engine Edge Cases + +### EC-WF-001 — Concurrent Approval (Parallel Steps) +**Severity:** 🔴 Critical | **Type:** Concurrency, Business Rule + +**Scenario:** Workflow มี Parallel Approval (Engineer A **และ** Engineer B ต้อง Approve พร้อมกัน) +Engineer A Approve พร้อมกับ Engineer B Approve ใน millisecond เดียวกัน + +**Expected Behavior:** +- Workflow System บันทึกทั้งสอง Action อย่างถูกต้อง +- State เปลี่ยนเป็น "Approved" ก็ต่อเมื่อ **ทุก Parallel Branch** Complete แล้ว +- ไม่เกิด State Corruption (เช่น State ถูก Override โดย Action หนึ่ง) + +**Implementation Rule:** +``` +- DB Transaction Isolation: SERIALIZABLE สำหรับ State Transition +- Check: all parallel branches completed → ถ้าใช่ → advance to next state +- ถ้าไม่ใช่ → บันทึก partial approval เท่านั้น +``` + +--- + +### EC-WF-002 — Action on Wrong Workflow State +**Severity:** 🔴 Critical | **Type:** Security, Business Rule + +**Scenario A:** Reviewer พยายาม Approve เอกสารที่ถูก Cancel แล้ว +**Scenario B:** Reviewer Approve เอกสารที่ Approve ไปแล้ว (Double-click) + +**Expected Behavior (A):** +- `GET /correspondences/:id` → status: CANCELLED → ปุ่ม Approve ไม่แสดง (UI) +- ถ้าโจมตีตรงๆ ผ่าน API → 422 Unprocessable Entity (Invalid state transition) + +**Expected Behavior (B):** +- `workflow_state_transitions` ตรวจสอบ current_state + action ก่อน +- ถ้า Action ไม่ Valid สำหรับ State ปัจจุบัน → 409 Conflict (Already processed) +- Idempotency: ถ้า User กด Approve ซ้ำด้วย Action เดียวกัน → Return เดิม ไม่ Error + +--- + +### EC-WF-003 — Force Proceed on Final State +**Severity:** 🟠 High | **Type:** Business Rule, UX + +**Scenario:** Document Control กด "Force Proceed" บนเอกสารที่อยู่ใน APPROVED (Final State) แล้ว + +**Expected Behavior:** +- ถ้าไม่มี Next State ใน DSL → ปุ่ม Force Proceed ไม่แสดง (UI) +- ถ้าเรียก API ตรงๆ → 422 (No next state available from current state) + +--- + +### EC-WF-004 — Workflow Definition Changed During Execution +**Severity:** 🟡 Medium | **Type:** Business Rule, Data Integrity + +**Scenario:** Admin แก้ไข Workflow DSL ขณะที่มี Workflow Instance กำลังดำเนินการอยู่ + +**Expected Behavior:** +- Workflow Instance ที่กำลังเดินอยู่ **ใช้ DSL เวอร์ชันที่สร้าง Instance** (Snapshot at creation) +- Instance ใหม่ที่สร้างหลังจากนั้นใช้ DSL เวอร์ชันใหม่ +- ไม่มีการ Interrupt Instance ที่กำลังเดินอยู่ + +**Implementation Rule:** +``` +workflow_instances.workflow_definition_snapshot (JSON) — บันทึก DSL ณ เวลาสร้าง +ไม่ Reference workflow_definitions.id โดยตรงสำหรับ Active Instances +``` + +--- + +### EC-WF-005 — Deadline Passed — No Action Taken +**Severity:** 🟡 Medium | **Type:** Business Rule, UX + +**Scenario:** Deadline ของ Organization ผ่านไปแล้ว แต่ User ยังไม่ Approve + +**Expected Behavior:** +- Workflow **ไม่ Auto-advance** (ต้องการ Human Decision เสมอ) +- Dashboard แสดง "Overdue" Badge (สีแดง) +- Notification Reminder ส่งซ้ำตาม Schedule (ไม่ใช่ตลอดเวลา — Anti-Spam) +- Document Control สามารถ Force Proceed ได้ (กรณีฉุกเฉิน) + +--- + +## Module 3: File Storage Edge Cases + +### EC-STOR-001 — File Upload During Network Interruption +**Severity:** 🟠 High | **Type:** UX, Data Integrity + +**Scenario:** User Upload ไฟล์ 50MB ผ่าน Wi-Fi แล้วเน็ตหลุดระหว่าง Upload + +**Expected Behavior:** +- Partial upload ไม่ถูก Save ใน Temp Storage +- User เห็น Error: "การอัปโหลดล้มเหลว กรุณาลองใหม่" + ปุ่ม Retry +- Draft ข้อมูล Form (ที่ไม่ใช่ไฟล์) ยังอยู่ใน LocalStorage (Auto-saved) +- ถ้า Retry → อัปโหลดใหม่ทั้งหมด (ไม่มี Resume Upload ใน MVP) + +--- + +### EC-STOR-002 — Virus Detected in Uploaded File +**Severity:** 🔴 Critical | **Type:** Security + +**Scenario:** User พยายาม Upload ไฟล์ที่ ClamAV ตรวจพบ Malware + +**Expected Behavior:** +- ClamAV Scan ใน Temp Storage → พบ → ลบไฟล์ออกจาก Temp ทันที +- API ตอบ 422 Unprocessable Entity: `{ "error": "FILE_VIRUS_DETECTED", "filename": "..." }` +- Audit Log บันทึก: `VIRUS_DETECTED` + filename + user_id + ip_address +- Security Metric Counter ใน Dashboard เพิ่มขึ้น +- ไม่ดำเนินการ Submit Document ต่อ (ไม่ว่าไฟล์อื่นจะผ่านแล้ว) + +--- + +### EC-STOR-003 — File Type Mismatch (MIME Sniffing Attack) +**Severity:** 🔴 Critical | **Type:** Security + +**Scenario:** Attacker เปลี่ยน Extension ไฟล์ `malware.exe` → `document.pdf` แล้ว Upload + +**Expected Behavior:** +- Backend ตรวจ MIME Type จาก **File Content** (ไม่ใช่ Extension) +- ถ้า MIME Type ไม่ตรงกับ Whitelist (PDF, DWG, ZIP, DOCX) → 400 Bad Request +- ถ้า Extension กับ MIME Type ไม่ตรงกัน → 400 Bad Request: "File type mismatch" +- Audit Log บันทึก Security Event + +**Whitelist:** +``` +PDF: application/pdf +DWG: application/acad, image/vnd.dwg +ZIP: application/zip, application/x-zip-compressed +DOCX: application/vnd.openxmlformats-officedocument.wordprocessingml.document +XLSX: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet +``` + +--- + +### EC-STOR-004 — Orphan File Cleanup (Document Cancelled Before Confirm) +**Severity:** 🟠 High | **Type:** Data Integrity, Storage + +**Scenario:** User Reserve Document Number → อัปโหลดไฟล์ไป Temp → Cancel Document → ออกจากหน้า + +**Expected Behavior:** +- Temp files ต้องถูกลบออกจาก Storage ภายใน 1 ชั่วโมง (Cleanup Cron) +- ไม่มี Orphan Files ใน Temp Storage เกิน TTL +- Permanent Storage ไม่มีไฟล์ที่ไม่มี Document Reference + +**Implementation Rule:** +```typescript +// Cron ทุกชั่วโมง +// ลบ Temp files ที่ older than 1 hour และ ไม่ได้ถูก Confirm +``` + +--- + +### EC-STOR-005 — Duplicate File Upload Detection +**Severity:** 🟡 Medium | **Type:** UX, Storage + +**Scenario:** User อัปโหลดไฟล์เดิมซ้ำสองครั้ง (ลืมว่าอัปโหลดแล้ว) + +**Expected Behavior:** +- **ไม่ Block** การ Upload ซ้ำ — เก็บเป็น 2 Attachment แยกกัน +- แสดง Warning (ไม่ใช่ Error): "ไฟล์นี้อาจถูกอัปโหลดแล้ว — ชื่อเดียวกัน" +- User สามารถลบ Duplicate ออกก่อน Submit + +--- + +## Module 4: RFA & Drawing Edge Cases + +### EC-RFA-001 — 1 Shop Drawing Revision = Max 1 RFA Constraint +**Severity:** 🔴 Critical | **Type:** Business Rule, Data Integrity + +**Scenario:** Document Control พยายามสร้าง RFA ที่สอง สำหรับ Shop Drawing Revision เดิม + +**Expected Behavior:** +- ตรวจสอบ: `rfas WHERE shop_drawing_revision_id = X AND status NOT IN ('REJECTED', 'CANCELLED')` +- ถ้ามี Active RFA อยู่แล้ว → 409 Conflict: "Shop Drawing Revision นี้มี RFA อยู่แล้ว" +- UI: Disable ปุ่ม "สร้าง RFA" ถ้า Revision มี Active RFA แล้ว + +**Exception:** ถ้า RFA ก่อนหน้าถูก REJECTED หรือ CANCELLED → สร้างใหม่ได้ + +--- + +### EC-RFA-002 — RFA Revision While Previous Still Pending +**Severity:** 🟠 High | **Type:** Business Rule + +**Scenario:** RFA Rev.A ยัง Pending Review อยู่ แต่ Contractor พยายามสร้าง Rev.B + +**Expected Behavior:** +- ถ้า Rev.A ยังไม่มีคำตอบสุดท้าย (REJECTED/APPROVED/APPROVED_WITH_COMMENTS) → Block +- 409 Conflict: "ต้องรอคำตอบของ Revision ก่อนหน้าก่อน" +- ไม่อนุญาตให้มี 2 Active Revision พร้อมกัน + +--- + +### EC-RFA-003 — Shop Drawing Uploaded to Wrong Category +**Severity:** 🟡 Medium | **Type:** Business Rule, UX + +**Scenario:** User เลือก Discipline = "Structural" แต่ Upload Shop Drawing ที่เป็น Electrical + +**Expected Behavior (MVP):** +- ไม่มี Auto-detection (AI Classification เป็น Phase 3) +- Validation: Discipline ต้องเลือก (ไม่มี Default) +- เตือนผู้ใช้ให้ตรวจสอบก่อน Submit (Review Mode) +- Reviewer ที่ Reject สามารถระบุเหตุผล "Wrong Discipline" ได้ + +--- + +### EC-RFA-004 — Transmittal Contains Mixed-Status RFAs +**Severity:** 🟠 High | **Type:** Business Rule + +**Scenario:** Transmittal ถูกสร้างโดยรวม RFA บางฉบับที่ยัง DRAFT และบางฉบับที่ READY + +**Expected Behavior:** +- Transmittal Submit ได้เฉพาะเมื่อ **ทุก RFA ใน Transmittal** อยู่ในสถานะ READY (ไม่ใช่ DRAFT) +- ถ้ามี DRAFT อยู่ → 422: "RFA [เลข] ยังอยู่ใน Draft กรุณา Submit ก่อน" +- UI: แสดง Status ของแต่ละ RFA ใน Transmittal ก่อน Submit + +--- + +## Module 5: Authentication & Session Edge Cases + +### EC-AUTH-001 — Token Refresh Race Condition +**Severity:** 🔴 Critical | **Type:** Concurrency, Security + +**Scenario:** Browser Tab A และ Tab B ทำ API Call พร้อมกันด้วย Access Token ที่ Expired +ทั้งสองตรวจพบ 401 และพยายาม Refresh Token พร้อมกัน + +**Expected Behavior:** +- ใช้ **Single Refresh Promise Pattern**: Tab แรกที่ Refresh สำเร็จ → Tab ที่สองใช้ Token ใหม่ (ไม่ Refresh ซ้อน) +- ถ้า Tab ที่สอง Refresh ก็ได้ Token ใหม่เหมือนกัน → ถือว่า OK (Refresh Token ยังใช้ได้) +- Refresh Token ถูก Rotate ทุกครั้งที่ใช้ (Refresh Token Rotation) + +**Implementation:** Frontend Singleton Refresh Promise ใน Axios Interceptor + +--- + +### EC-AUTH-002 — Permission Changed While User is Logged In +**Severity:** 🔴 Critical | **Type:** Security, Business Rule + +**Scenario:** Admin เปลี่ยน Role ของ User จาก Document Control → Viewer ขณะที่ User กำลัง Login อยู่ + +**Expected Behavior:** +- Redis Permission Cache ของ User ถูกล้าง **ทันที** (ไม่รอ TTL) +- Access Token เดิมยังใช้ได้จนหมดอายุ (15 นาที) — เป็นที่ยอมรับ +- **Request ถัดไปหลัง Token Refresh** → Permission ใหม่มีผล +- Maximum Lag: 15 นาที (= Access Token TTL) + +--- + +### EC-AUTH-003 — Concurrent Login (Same Account, Multiple Devices) +**Severity:** 🟡 Medium | **Type:** Security, Business Rule + +**Scenario:** User Login จาก 2 Device พร้อมกัน (PC และ Tablet) + +**Expected Behavior (MVP):** +- อนุญาต (Session ทั้งสองทำงาน Independent) +- แต่ละ Device มี Refresh Token แยกกัน +- Logout จาก Device หนึ่ง → Revoke เฉพาะ Refresh Token ของ Device นั้น + +**Future Enhancement (Phase 2):** +- Option: "Logout จาก Device อื่นทั้งหมด" + +--- + +### EC-AUTH-004 — Account Deactivated While Logged In +**Severity:** 🔴 Critical | **Type:** Security + +**Scenario:** Admin Deactivate User Account ขณะที่ User กำลัง Login อยู่ + +**Expected Behavior:** +- Redis: Blacklist User ID (ทุก Token ของ User นั้นถือว่า Invalid ทันที) +- Request ถัดไปของ User → 401 Unauthorized: "Account has been deactivated" +- User ถูก Redirect ไปหน้า Login พร้อม Message ชัดเจน + +**Implementation:** +```typescript +// ใน JWT Guard: ตรวจ Redis Blacklist ก่อน Validate Token +const isBlacklisted = await redis.get(`user:blacklist:${userId}`); +if (isBlacklisted) throw new UnauthorizedException('Account deactivated'); +``` + +--- + +## Module 6: Permission & RBAC Edge Cases + +### EC-PERM-001 — Direct Object Reference (IDOR Attack) +**Severity:** 🔴 Critical | **Type:** Security + +**Scenario:** User A รู้ ID ของเอกสาร User B (เช่น `/correspondences/12345`) แล้วเรียกตรงๆ + +**Expected Behavior:** +- CASL AbilityGuard ตรวจสอบทั้ง Action และ Resource Owner +- ถ้าไม่มีสิทธิ์ → **403 Forbidden** (ไม่ใช่ 404 — เพราะ 404 บอกว่ามีอยู่แต่หาไม่เจอ) +- **Exception:** ถ้าต้องการซ่อน Existence ของ Document → Return 404 +- ทุก API ต้องผ่าน Permission Check โดยไม่มีข้อยกเว้น + +--- + +### EC-PERM-002 — Super Admin Impersonation Prevention +**Severity:** 🔴 Critical | **Type:** Security + +**Scenario:** User พยายาม Forge JWT payload เพิ่ม role: 'SUPERADMIN' + +**Expected Behavior:** +- JWT ถูก Sign ด้วย Secret ที่ไม่เปิดเผย → Signature ไม่ตรง → 401 Invalid token +- Role ไม่ถูก Read จาก Token โดยตรงสำหรับ Permission Check — ต้อง Verify จาก DB/Redis +- JWT payload ใช้แค่ `user_id` → ดึง Permission จาก Redis Cache/DB + +--- + +### EC-PERM-003 — Organization Switch Mid-session +**Severity:** 🟡 Medium | **Type:** Business Rule, UX + +**Scenario (ถ้ามี):** User เป็นสมาชิกในหลาย Organization (กรณี Consultant ที่ทำงานหลายโครงการ) + +**Expected Behavior:** +- User เห็นเฉพาะ Data ขององค์กรที่ Login อยู่ (Active Context) +- ถ้าต้องการดูอีก Org → ต้อง "Switch Organization" (Session Context เปลี่ยน) +- ไม่มี Cross-org Data Leak แม้ User เป็นสมาชิกทั้งสอง Org + +--- + +## Module 7: Correspondence Edge Cases + +### EC-CORR-001 — Cancel Correspondence with Downstream Circulation +**Severity:** 🔴 Critical | **Type:** Business Rule, Data Integrity + +**Scenario:** Correspondence ถูก Submit → ผู้รับสร้าง Circulation แล้ว → Originator ขอ Cancel + +**Expected Behavior:** +- ต้องแจ้งเตือน Admin ว่า "มี Circulation ที่เปิดอยู่ [X รายการ] สำหรับเอกสารนี้" +- ต้องยืนยันก่อน Cancel: "การ Cancel จะส่งผลให้ Circulation ที่เกี่ยวข้องถูกปิดทั้งหมด" +- เมื่อ Confirm → Correspondence = CANCELLED + Circulation ที่เกี่ยวข้อง = FORCE_CLOSED +- Audit Log บันทึกทั้งหมด (CANCELLED + FORCE_CLOSED + reason + user) + +--- + +### EC-CORR-002 — Reply to Cancel Correspondence +**Severity:** 🟡 Medium | **Type:** Business Rule + +**Scenario:** Document Control พยายามสร้าง Correspondence เพื่อ Reply ต่อ Correspondence ที่ถูก Cancel + +**Expected Behavior:** +- Reply ทำได้ — Reference ถึง CANCELLED เอกสารได้ (เพื่อ acknowledge การยกเลิก) +- UI แสดง Warning: "กำลัง Reply ต่อเอกสารที่ถูกยกเลิกแล้ว" +- ไม่ Block การ Reply (เป็น Business Decision ไม่ใช่ Technical Constraint) + +--- + +### EC-CORR-003 — Correspondence to Self (Same Organization) +**Severity:** 🟡 Medium | **Type:** Business Rule + +**Scenario:** User พยายามสร้าง Correspondence ที่ Sender และ Receiver เป็นองค์กรเดียวกัน + +**Expected Behavior:** +- External Correspondence (Letter/RFI) → Block: "ไม่สามารถส่งหาตัวเองได้" +- Internal Communication → ใช้ Circulation Sheet แทน (ไม่ใช่ Correspondence) +- UI Validation + Backend Validation (Double Check) + +--- + +## Module 8: Circulation Edge Cases + +### EC-CIRC-001 — Assignee Deactivated Before Completing Task +**Severity:** 🟠 High | **Type:** Business Rule, UX + +**Scenario:** User ถูก Deactivate หลังจากถูก Assign ใน Circulation แต่ก่อน Respond + +**Expected Behavior:** +- Circulation ยัง Active อยู่ — ไม่หยุดอัตโนมัติ +- Document Control เห็น Warning: "Assignee [ชื่อ] ไม่ Active แล้ว" +- Document Control สามารถ Re-assign ไปยัง User อื่นได้ +- Audit Log บันทึก Re-assign Event + +--- + +### EC-CIRC-002 — Multi-Assignee: Partial Response +**Severity:** 🟡 Medium | **Type:** Business Rule, UX + +**Scenario:** Circulation มี Action Assignees 3 คน — 2 คน Respond แล้ว แต่ 1 คนยังไม่ Respond + +**Expected Behavior (MVP):** +- Document Control เห็นสถานะ "2/3 ตอบกลับแล้ว" +- Document Control สามารถ Force Close ได้ (พร้อมระบุเหตุผล) +- ถ้า Force Close → ทุก Partial Response ถูกบันทึก + หมายเหตุว่า Force Closed + +--- + +### EC-CIRC-003 — Circulation Deadline = Today (Edge of Day) +**Severity:** 🟡 Medium | **Type:** Business Rule, UX + +**Scenario:** Deadline ถูกกำหนด = "วันนี้" แต่ User ดูตอนบ่ายสอง + +**Expected Behavior:** +- ถ้า Deadline = วันที่ X → หมดเขตเมื่อ X เวลา 23:59:59 (ไม่ใช่ 00:00:00) +- Reminder: ส่ง Notification เวลา 08:00 ของวัน Deadline +- Overdue Badge ขึ้นเมื่อ `NOW() > deadline_date + 1 day` (วันถัดไป 00:00) + +--- + +## Module 9: Search & Elasticsearch Edge Cases + +### EC-SRCH-001 — Search Index Lag (Eventual Consistency) +**Severity:** 🟡 Medium | **Type:** Data Consistency, UX + +**Scenario:** Document ถูก Submit แล้ว → User ค้นหาทันที แต่ไม่เจอ + +**Expected Behavior:** +- Index อาจ Lag 5–30 วินาที (BullMQ Async Job) +- UI แสดง "เอกสารอาจใช้เวลาสักครู่ก่อนปรากฏในผลค้นหา" +- **ไม่ถือว่า Bug** — เป็น By Design (Eventual Consistency) +- User สามารถ Navigate ไปยังเอกสารได้ทันทีผ่าน Notification Link (ไม่ต้องรอ Search) + +--- + +### EC-SRCH-002 — Permission-filtered Search Results +**Severity:** 🔴 Critical | **Type:** Security + +**Scenario:** Contractor A ค้นหา Keyword ที่มีใน Document ของ Contractor B + +**Expected Behavior:** +- Elasticsearch Index ต้องมี `organization_id` / `contract_id` Field +- ทุก Search Query ต้อง Filter ด้วย `must: [{ term: { visible_to_org: userOrgId } }]` +- Contractor A **ไม่เห็น** Document ของ Contractor B ในผลค้นหา +- **ห้าม Filter ที่ Application Layer เท่านั้น** → ต้อง Filter ที่ Query Level + +--- + +### EC-SRCH-003 — Special Characters in Search Query +**Severity:** 🟡 Medium | **Type:** Security, UX + +**Scenario:** User ค้นหาด้วย `คคง. สค. - 2025` (มี `-`, `.`, ช่องว่าง) + +**Expected Behavior:** +- ไม่ Crash — Elasticsearch รองรับ Special Characters +- Sanitize Query ก่อนส่ง (กัน Elasticsearch Injection) +- ผล Search ยังคง Relevance สูง + +--- + +## Module 10: Notifications Edge Cases + +### EC-NOTIF-001 — Notification Flood Prevention +**Severity:** 🟠 High | **Type:** UX, Anti-Spam + +**Scenario:** Workflow มีหลาย Step ที่เปลี่ยนเร็ว → ส่ง Notification ทุก State Change → User ได้รับ Email 10 ฉบับในนาทีเดียว + +**Expected Behavior:** +- **Notification Debounce/Batch:** รวม Notifications ภายใน 5 นาทีเป็น Summary Email เดียว +- ถ้าเปลี่ยน State 5 ครั้งใน 5 นาที → Email เดียว: "เอกสาร X มี 5 การเปลี่ยนแปลง" +- In-App Notifications ยังแสดงทุกรายการ (ไม่ Batch) + +--- + +### EC-NOTIF-002 — User Unsubscribed from EMAIL but still needs In-App +**Severity:** 🟡 Medium | **Type:** UX, Business Rule + +**Scenario:** User ปิด Email Notification แต่ยังต้องการ In-App Notification + +**Expected Behavior:** +- Notification Settings: แยก Toggle สำหรับ Email / LINE / In-App +- Core Workflow Assignments (ที่ User ต้อง Action) → **ไม่สามารถ Disable** ทุก Channel ได้ +- ต้องมี In-App อย่างน้อย 1 Channel สำหรับ Action Required Notifications + +--- + +## 📊 Edge Case Summary by Module + +| Module | Critical | High | Medium | Total | +|--------|----------|------|--------|-------| +| Document Numbering | 2 | 2 | 1 | 5 | +| Workflow Engine | 2 | 1 | 2 | 5 | +| File Storage | 2 | 2 | 1 | 5 | +| RFA & Drawing | 1 | 2 | 1 | 4 | +| Auth & Session | 3 | 0 | 1 | 4 | +| Permission & RBAC | 2 | 0 | 1 | 3 | +| Correspondence | 1 | 0 | 2 | 3 | +| Circulation | 0 | 1 | 2 | 3 | +| Search | 1 | 0 | 2 | 3 | +| Notifications | 0 | 1 | 1 | 2 | +| **รวม** | **14** | **9** | **14** | **37** | + +--- + +## 🧪 Testing Strategy for Edge Cases + +### สำหรับ Unit Tests (Backend) +```typescript +// ตัวอย่าง: EC-DN-001 — Concurrent Number Generation +describe('DocumentNumberingService - Concurrency', () => { + it('should generate unique numbers for concurrent requests', async () => { + const promises = Array.from({ length: 50 }, () => + service.reserve({ projectId: 1, typeId: 2, orgId: 3 }) + ); + const results = await Promise.all(promises); + const numbers = results.map(r => r.documentNumber); + const unique = new Set(numbers); + expect(unique.size).toBe(50); // ไม่มีซ้ำ + }); +}); +``` + +### สำหรับ Integration Tests +- EC-DN-001: k6 Load Test Script (50 VUs, `/document-numbering/reserve`) +- EC-AUTH-001: Cypress Multi-tab Token Refresh Test +- EC-PERM-001: API Test Suite — Direct Object Reference สำหรับทุก Resource + +### สำหรับ Manual UAT +- EC-WF-001: Test Parallel Approval ด้วย 2 Browser Session พร้อมกัน +- EC-STOR-002: Upload EICAR Test File (ClamAV Test Virus) +- EC-RFA-001: สร้าง RFA สำหรับ Revision เดิมที่มี Active RFA → Assert Block + +--- + +## 📝 Document Control + +- **Version:** 1.0.0 | **Status:** DRAFT +- **Created:** 2026-03-11 | **Owner:** Nattanin Peancharoen +- **Next Review:** Pre-UAT (T-2 สัปดาห์ก่อน Go-Live) +- **Classification:** Internal Use Only — Developer & QA Reference diff --git a/specs/01-requirements/01-07-ui-wireframes.md b/specs/01-requirements/01-07-ui-wireframes.md new file mode 100644 index 0000000..7a4ab46 --- /dev/null +++ b/specs/01-requirements/01-07-ui-wireframes.md @@ -0,0 +1,627 @@ +# 🖼️ UI/UX Wireframes & Screen Inventory — LCBP3-DMS v1.8.0 + +--- +title: 'UI/UX Screen Inventory, Navigation Map, and Wireframes' +version: 1.0.0 +status: DRAFT +owner: Nattanin Peancharoen (Product Owner) +last_updated: 2026-03-11 +related: + - specs/01-Requirements/01-02-business-rules/01-02-03-ui-ux-rules.md + - specs/01-Requirements/01-04-user-stories.md + - specs/01-Requirements/01-05-acceptance-criteria.md +--- + +> [!NOTE] +> Wireframes ในเอกสารนี้เป็น **Low-fidelity ASCII/Text Wireframes** เพื่อสื่อสาร Layout และ Component Hierarchy +> สำหรับ High-fidelity Design ให้ใช้ Figma หรือ Shadcn/UI Components ตาม ADR-012 + +--- + +## 1. 🗺️ Navigation Map (Site Map) + +``` +[🔓 Public] +│ +└── /login → หน้า Login (Anonymous) + └── /login/forgot-password → ลืมรหัสผ่าน + └── /login/change-password → เปลี่ยนรหัสผ่านครั้งแรก (Force) + +[🔒 Authenticated — App Shell (Sidebar + Navbar)] +│ +├── /dashboard → หน้าหลัก (My Tasks + KPI) +│ +├── /correspondences → รายการ Correspondence +│ ├── /correspondences/new → สร้างใหม่ +│ └── /correspondences/:id → รายละเอียด + Workflow +│ +├── /rfas → รายการ RFA +│ ├── /rfas/new → สร้างใหม่ +│ └── /rfas/:id → รายละเอียด + Workflow +│ +├── /transmittals → รายการ Transmittal +│ ├── /transmittals/new → สร้างใหม่ (รวม RFAs) +│ └── /transmittals/:id → รายละเอียด +│ +├── /drawings → Drawing Management +│ ├── /drawings/contract → Contract Drawings +│ │ ├── /drawings/contract/new → Upload ใหม่ +│ │ └── /drawings/contract/:id → รายละเอียด +│ └── /drawings/shop → Shop Drawings +│ ├── /drawings/shop/new → Upload ใหม่ +│ └── /drawings/shop/:id → รายละเอียด + RFA History +│ +├── /circulations → Circulation Sheets (Internal) +│ ├── /circulations/new → สร้างใหม่ +│ └── /circulations/:id → รายละเอียด + Assignees +│ +├── /search → Full-text Search +│ +├── /notifications → รายการ Notifications +│ +├── /profile → ข้อมูลส่วนตัว + ตั้งค่า +│ +[🔒 Admin Routes] +│ +├── /admin/users → จัดการ Users (Org Admin+) +│ ├── /admin/users/new → เพิ่ม User +│ └── /admin/users/:id/edit → แก้ไข User + Role +│ +├── /admin/organizations → จัดการ Orgs (Superadmin) +│ └── /admin/organizations/new +│ +├── /admin/projects → จัดการ Projects (Superadmin) +│ └── /admin/projects/:id/contracts +│ +├── /admin/doc-numbering → Document Number Config (Superadmin) +│ +└── /admin/audit-logs → Audit Log Viewer (Superadmin + OrgAdmin) +``` + +--- + +## 2. 🧩 App Shell Layout + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ NAVBAR │ +│ [🏗️ LCBP3-DMS] [Project: LCBP3 ▼] [🔔 3] [👤 สมชาย ▼] │ +└─────────────────────────────────────────────────────────────────┘ +┌──────────────┬──────────────────────────────────────────────────┐ +│ SIDEBAR │ MAIN CONTENT AREA │ +│ │ │ +│ 📊 Dashboard │ │ +│ 📨 Corres. │ [Page Content Here] │ +│ 📋 RFA │ │ +│ 📦 Transmit │ │ +│ 📐 Drawings │ │ +│ 📄 Circulat. │ │ +│ 🔍 Search │ │ +│ │ │ +│ ─────────── │ │ +│ [Admin ▼] │ │ +│ 👥 Users │ │ +│ 🏢 Orgs │ │ +│ ⚙️ Config │ │ +└──────────────┴──────────────────────────────────────────────────┘ + +Mobile: Sidebar → Collapsible Hamburger Drawer (ตาม UI-Rule 5.11) +``` + +--- + +## 3. 📋 Screen Inventory + +| Screen ID | Route | ชื่อหน้า | Primary Role | Priority | +|-----------|-------|---------|-------------|---------| +| SCR-001 | `/login` | Login | ทุก Role | 🔴 Must | +| SCR-002 | `/login/change-password` | Force Password Change | ทุก Role | 🔴 Must | +| SCR-003 | `/dashboard` | Dashboard | ทุก Role | 🔴 Must | +| SCR-004 | `/correspondences` | Correspondence List | Doc Control | 🔴 Must | +| SCR-005 | `/correspondences/new` | Create Correspondence | Doc Control | 🔴 Must | +| SCR-006 | `/correspondences/:id` | Correspondence Detail + Workflow | ทุก Role | 🔴 Must | +| SCR-007 | `/rfas` | RFA List | Doc Control | 🔴 Must | +| SCR-008 | `/rfas/new` | Create RFA | Doc Control | 🔴 Must | +| SCR-009 | `/rfas/:id` | RFA Detail + Workflow | ทุก Role | 🔴 Must | +| SCR-010 | `/transmittals` | Transmittal List | Doc Control | 🟠 Should | +| SCR-011 | `/transmittals/new` | Create Transmittal | Doc Control | 🟠 Should | +| SCR-012 | `/transmittals/:id` | Transmittal Detail | ทุก Role | 🟠 Should | +| SCR-013 | `/drawings/contract` | Contract Drawing List | Doc Control | 🟠 Should | +| SCR-014 | `/drawings/shop` | Shop Drawing List | Doc Control | 🟠 Should | +| SCR-015 | `/drawings/shop/:id` | Shop Drawing Detail | ทุก Role | 🟠 Should | +| SCR-016 | `/circulations` | Circulation List | Doc Control | 🟠 Should | +| SCR-017 | `/circulations/new` | Create Circulation | Doc Control | 🟠 Should | +| SCR-018 | `/circulations/:id` | Circulation Detail | ทุก Role | 🟠 Should | +| SCR-019 | `/search` | Search Results | ทุก Role | 🟠 Should | +| SCR-020 | `/notifications` | Notification Center | ทุก Role | 🟡 Could | +| SCR-021 | `/profile` | Profile & Settings | ทุก Role | 🟠 Should | +| SCR-022 | `/admin/users` | User Management | Org Admin+ | 🔴 Must | +| SCR-023 | `/admin/organizations` | Organization Management | Superadmin | 🔴 Must | +| SCR-024 | `/admin/projects` | Project & Contract Mgmt | Superadmin | 🔴 Must | +| SCR-025 | `/admin/doc-numbering` | Document Number Config | Superadmin | 🟠 Should | +| SCR-026 | `/admin/audit-logs` | Audit Log Viewer | Org Admin+ | 🟠 Should | + +**รวม:** 26 หน้า (9 Must / 13 Should / 1 Could) + +--- + +## 4. 🖼️ Wireframes — Key Screens + +### SCR-001: Login Page + +``` +┌─────────────────────────────────────────────────────────┐ +│ │ +│ 🏗️ LCBP3-DMS │ +│ ท่าเรือแหลมฉบัง เฟส 3 │ +│ Document Management System │ +│ │ +│ ┌─────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ ชื่อผู้ใช้ (Username) │ │ +│ │ [________________________________] │ │ +│ │ │ │ +│ │ รหัสผ่าน (Password) │ │ +│ │ [________________________________] [👁️] │ │ +│ │ │ │ +│ │ [ เข้าสู่ระบบ (Login) ] ← Primary │ │ +│ │ │ │ +│ │ [ลืมรหัสผ่าน?] │ │ +│ │ │ │ +│ └─────────────────────────────────────────────────┘ │ +│ │ +│ ❌ Error Banner (แสดงเมื่อ Login ผิด): │ +│ [⚠️ ชื่อผู้ใช้หรือรหัสผ่านไม่ถูกต้อง] │ +│ │ +│ v1.8.0 | Internal Use Only │ +└─────────────────────────────────────────────────────────┘ + +Component Rules: +- Error Toast: แสดงทับ Form (ไม่บอกว่าอันไหนผิด — Security) +- Rate Limit: หลัง 5 ครั้ง → ปุ่ม Disabled 60 วินาที + Countdown +- Password: Toggle Show/Hide icon +- Auto-focus: Username field on load +- Enter key: Submit form +``` + +--- + +### SCR-003: Dashboard + +``` +┌─ Dashboard ─────────────────────────────────────────────────────────┐ +│ │ +│ 📊 ภาพรวม — [สมชาย จาก สค.] วันนี้ 11 มี.ค. 2569 │ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ 📨 Corres. │ │ 📋 RFA │ │ ⏰ Overdue │ │ 🔒 Security │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ Pending │ │ Pending │ │ Tasks │ │ Files │ │ +│ │ [12] │ │ [5] │ │ [3] │ │ Scanned │ │ +│ │ │ │ │ │ │ │ [847] │ │ +│ │ ← ↑3 จากเมื่อ │ │ ← ↓1 จากเมื่อ │ │ ⚠️ เกินกำหนด │ │ 0 Threats │ │ +│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ +│ │ +│ ═══ งานของฉัน (My Tasks) ════════════════════════════════════════ │ +│ │ +│ ┌──────────────────────────────────────────────────────────────┐ │ +│ │ [Filter: ทั้งหมด ▼] [Status: Active ▼] 🔍 [ค้นหา...] │ │ +│ ├────────┬──────────────────┬──────────┬──────────┬────────────┤ │ +│ │ ประเภท │ เลขที่/Subject │ หน้าที่ │ กำหนด │ การดำเนินการ│ │ +│ ├────────┼──────────────────┼──────────┼──────────┼────────────┤ │ +│ │ 📄 RFA │ LCBP3-RFA-STR.. │ Approve │⚠️12 มี.ค.│ [ดำเนินการ]│ │ +│ │ 📨 Cir │ สค.-กทท.-001... │ Review │ 15 มี.ค. │ [ดำเนินการ]│ │ +│ │ 📨 Cir │ สค.-กทท.-002... │ Info │ 20 มี.ค. │ [ดำเนินการ]│ │ +│ ├────────┴──────────────────┴──────────┴──────────┴────────────┤ │ +│ │ แสดง 3 จาก 12 รายการ [ดูทั้งหมด →] │ │ +│ └──────────────────────────────────────────────────────────────┘ │ +│ │ +└──────────────────────────────────────────────────────────────────────┘ + +Mobile (Card View): +┌───────────────────────┐ +│ 📄 RFA │ +│ LCBP3-RFA-STR-0042 │ +│ หน้าที่: Approve │ +│ ⚠️ กำหนด: 12 มี.ค. │ +│ [ดำเนินการ →] │ +└───────────────────────┘ +``` + +--- + +### SCR-004: Correspondence List + +``` +┌─ Correspondence ────────────────────────────────────────────────────┐ +│ │ +│ [+ สร้างใหม่] [📥 รับเข้า (12)] [📤 ส่งออก (8)] [ทั้งหมด (20)] │ +│ │ +│ [ Filter: ประเภท ▼ ] [ Filter: สถานะ ▼ ] [ Filter: วันที่ ▼ ] │ +│ 🔍 [ค้นหาเอกสาร... ] [ล้าง Filter] │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │☐ │ เลขที่เอกสาร │ Subject │ ผู้ส่ง │วันที่│สถานะ │ │ +│ ├──┼─────────────────────┼────────────┼────────┼──────┼───────┤ │ +│ │☐ │ LCBP3-สค-กทท-L-001 │ ขอแบบงาน. │ สค. │11มีค│✅ ปิด │ │ +│ │☐ │ LCBP3-กทท-สค-L-002 │ ตอบรับ... │ กทท. │10มีค│🔄 ดำเนิน│ │ +│ │☐⚠️│ LCBP3-สค-กทท-L-003 │ ขอข้อมูล.. │ สค. │08มีค│⏰ เกิน │ │ +│ │ │ ... │ │ │ │ │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ [< 1 2 3 >] แสดง 15/47 รายการ │ +│ │ +└──────────────────────────────────────────────────────────────────────┘ + +Status Badges: +🟡 Draft | 🔵 Submitted | 🔄 In Review | ✅ Closed | ❌ Cancelled | ⏰ Overdue +``` + +--- + +### SCR-005: Create Correspondence (Form) + +``` +┌─ สร้าง Correspondence ─────────────────────────────────────────────┐ +│ │ +│ Step 1: ข้อมูลทั่วไป ●─────── Step 2: แนบไฟล์ ○─── Step 3: ตรวจสอบ ○│ +│ │ +│ ┌───────────────────────────────────────────────────────────┐ │ +│ │ ประเภทเอกสาร* │ จาก (Originator)* │ │ +│ │ [Letter ▼] │ [สค. (กำหนดอัตโนมัติ)] │ │ +│ │ │ │ │ +│ │ ถึง (To)* │ สำเนา (CC) │ │ +│ │ [เลือกองค์กร ▼][+ เพิ่ม]│ [เลือกองค์กร ▼][+ เพิ่ม] │ │ +│ │ Tag: กทท. × │ │ │ +│ │ │ │ │ +│ │ Subject* │ │ +│ │ [_____________________________________________] │ │ +│ │ ○ ตัวอักษรที่เหลือ: 200 │ │ +│ │ │ │ +│ │ เอกสารอ้างอิง (References) │ │ +│ │ [🔍 ค้นหาเลขที่เอกสาร... ] [+ เพิ่ม] │ │ +│ │ หมวดหมู่ (Tags) │ │ +│ │ [🔍 ค้นหา Tag...] [construction] × [rfa] × │ │ +│ │ │ │ +│ │ หมายเหตุ (Remark) │ │ +│ │ [_____________________________________________] │ │ +│ │ [_____________________________________________] │ │ +│ └───────────────────────────────────────────────────────────┘ │ +│ │ +│ ⚠️ Auto-save: บันทึกล่าสุด 13:28:45 │ +│ │ +│ [← ยกเลิก] [บันทึก Draft] [ต่อไป: แนบไฟล์ →] │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +### SCR-005b: File Attachment Step + +``` +┌─ สร้าง Correspondence — แนบไฟล์ ───────────────────────────────────┐ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ 📎 ลากและวางไฟล์ที่นี่ หรือ [เลือกไฟล์] │ │ +│ │ │ │ +│ │ รองรับ: PDF, DWG, ZIP, DOCX, XLSX (สูงสุด 100MB/ไฟล์) │ │ +│ │ │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ไฟล์ที่แนบ: │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ ☑️ เอกสารหลัก │ 📄 drawing-v2.pdf │ 2.3MB │ ✅ Scan OK│[🗑️]│ +│ │ ☐ เอกสารหลัก │ 📐 detail.dwg │ 1.1MB │ 🔄 Scanning│[🗑️]│ +│ │ ☐ เอกสารหลัก │ 📦 supporting-docs.zip │ 5.8MB │ ✅ Scan OK│[🗑️]│ +│ └────────────────────────────────────────────────────────────┘ │ +│ │ +│ ℹ️ ☑️ = เอกสารหลัก (Main Document) — เลือกได้ 1 ไฟล์ │ +│ │ +│ ❌ Error File: │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ 🚨 malware-test.pdf │ ❌ VIRUS DETECTED — ไฟล์ถูกปฏิเสธ │ │ +│ └────────────────────────────────────────────────────────────┘ │ +│ │ +│ [← ย้อนกลับ] [บันทึก Draft] [ต่อไป: ตรวจสอบ →] │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +### SCR-006: Correspondence Detail + Workflow + +``` +┌─ LCBP3-สค.-กทท.-LETTER-0001-68 ────────────────────────────────────┐ +│ Subject: ขอข้อมูลแบบก่อสร้างเพิ่มเติม │ +│ ส่งโดย: สค. → ถึง: กทท. วันที่: 11 มี.ค. 2569 │ +│ Status: 🔄 IN REVIEW │ +│ │ +│ ┌──────────────────────────────────────────────────────────────┐ │ +│ │ TAB: [ข้อมูล] [📎 เอกสารแนบ (3)] [🔄 Workflow] [📋 Circulation]│ │ +│ └──────────────────────────────────────────────────────────────┘ │ +│ │ +│ ═══ Workflow Diagram ════════════════════════════════════════════ │ +│ │ +│ ✅ Submit ──→ 🔄 Review ──→ ○ ปิด │ +│ (สค.) (กทท.) (สค.) │ +│ 11 มี.ค. กำลังดำเนินการ รอ │ +│ [คลิกดู Log] [คลิกดูรายละเอียด] │ +│ │ +│ ═══ Action Panel (แสดงเฉพาะ Step ที่ Active) ══════════════════ │ +│ ┌──────────────────────────────────────────────────────────────┐ │ +│ │ 📋 งานของคุณ: Review เอกสารนี้และตอบกลับ │ │ +│ │ │ │ +│ │ Comment / หมายเหตุ: │ │ +│ │ [___________________________________________________] │ │ +│ │ [___________________________________________________] │ │ +│ │ │ │ +│ │ [❌ ปฏิเสธ] [✅ รับทราบ] [📩 ตอบกลับ] │ │ +│ └──────────────────────────────────────────────────────────────┘ │ +│ │ +│ Admin Only: [⚡ Force Proceed →] [↩️ Revert ←] │ +└──────────────────────────────────────────────────────────────────────┘ + +Workflow Step Popup (คลิก Step ที่ผ่านแล้ว): +┌─────────────────────────────────┐ +│ ✅ Submit — 11 มี.ค. 2569 │ +│ โดย: สมชาย ก. (สค.) │ +│ เวลา: 09:32 น. │ +│ IP: 192.168.1.10 │ +│ Comment: - │ +└─────────────────────────────────┘ +``` + +--- + +### SCR-008: Create RFA (Form) + +``` +┌─ สร้าง RFA ────────────────────────────────────────────────────────┐ +│ │ +│ Step 1: ข้อมูล RFA ●── Step 2: Shop Drawing ○── Step 3: Transmittal ○│ +│ │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ ประเภท RFA* │ สาขา (Discipline)* │ │ +│ │ [Shop Drawing ▼] │ [Structural (STR) ▼] │ │ +│ │ │ │ +│ │ ⚠️ เลขที่ RFA (Auto-generated) │ │ +│ │ Preview: LCBP3-RFA-STR-0043 (จะออกเมื่อ Submit) │ │ +│ │ │ │ +│ │ Contract Drawing ที่อ้างอิง │ │ +│ │ [🔍 ค้นหาแบบคู่สัญญา... ] [+ เลือก] │ │ +│ │ → CD-STR-001: Foundation Plan × │ │ +│ │ │ │ +│ │ หมายเหตุ (Remark) │ │ +│ │ [____________________________________________] │ │ +│ └────────────────────────────────────────────────────────────┘ │ +│ │ +│ [← ยกเลิก] [บันทึก Draft] [ต่อไป: แนบแบบ →] │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +### SCR-009: RFA Detail + Workflow + +``` +┌─ LCBP3-RFA-STR-0042 ───────────────────────────────────────────────┐ +│ ประเภท: Shop Drawing | สาขา: Structural | Revision: A │ +│ ยื่นโดย: ผรม.1 → ผ่าน Transmittal: LCBP3-TRM-0015 │ +│ Status: 🔄 UNDER REVIEW (คคง.) │ +│ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ TAB: [ข้อมูล] [📎 Shop Drawing] [🔄 Workflow] [📝 Revision] │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ═══ Shop Drawing Viewer ════════════════════════════════════════ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ [ 📄 PDF Viewer — Streaming ] │ │ +│ │ │ │ +│ │ ⬅️ หน้า 2/15 ➡️ 🔍 80% [⬇️ ดาวน์โหลด] ← (ถ้ามี)│ │ +│ │ │ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +│ ═══ Action Panel (เฉพาะ Reviewer) ════════════════════════════ │ +│ ┌─────────────────────────────────────────────────────────────┐ │ +│ │ ผลการพิจารณา: │ │ +│ │ ○ Approved ● Approved with Comments ○ Rejected │ │ +│ │ │ │ +│ │ Comment (บังคับเมื่อ AW/C หรือ Rejected): │ │ +│ │ [พบข้อผิดพลาดในรายละเอียด Connection Plate ...] │ │ +│ │ │ │ +│ │ [ยกเลิก] [✅ ยืนยันผลการพิจารณา]│ │ +│ └─────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ + +Workflow Diagram สำหรับ RFA: + ✅ Draft → ✅ Submitted → 🔄 TEAM Review → 🔄 คคง. Review → ○ APPROVED + (parallel) (sequential) +``` + +--- + +### SCR-017: Create Circulation Sheet + +``` +┌─ สร้างใบเวียน (Circulation Sheet) ─────────────────────────────────┐ +│ อ้างอิง: LCBP3-กทท-สค-LETTER-0012 — ขอข้อมูลงวดงานที่ 3 │ +│ │ +│ ┌────────────────────────────────────────────────────────────┐ │ +│ │ ผู้รับผิดชอบหลัก (Main — ต้องดำเนินการ)* │ │ +│ │ [🔍 ค้นหาชื่อผู้ใช้... ] [+ เพิ่ม] │ │ +│ │ → [👤 สมชาย ก. (หัวหน้า)] × [📅 กำหนด: 15 มี.ค.] │ │ +│ │ │ │ +│ │ ผู้ดำเนินการ (Action — ร่วมดำเนินการ) │ │ +│ │ [🔍 ค้นหาชื่อผู้ใช้... ] [+ เพิ่ม] │ │ +│ │ → [👤 วิชัย ส. (วิศวกร)] × [📅 กำหนด: 20 มี.ค.] │ │ +│ │ │ │ +│ │ รับทราบ (Information — เพื่อทราบเท่านั้น) │ │ +│ │ [🔍 ค้นหาชื่อผู้ใช้... ] [+ เพิ่ม] │ │ +│ │ → [👤 มานะ พ. (ผจก.)] × │ │ +│ │ │ │ +│ │ หมายเหตุ / คำสั่งการ │ │ +│ │ [โปรดตรวจสอบและเตรียมข้อมูลงวดงานที่ 3...] │ │ +│ └────────────────────────────────────────────────────────────┘ │ +│ │ +│ [← ยกเลิก] [✅ สร้างและส่ง Notify] │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +### SCR-022: User Management (Admin) + +``` +┌─ จัดการผู้ใช้งาน ───────────────────────────────────────────────────┐ +│ องค์กร: สค. (สำนักงานโครงการ) [+ เพิ่ม User ใหม่] │ +│ │ +│ 🔍 [ค้นหาชื่อ / อีเมล...] [Role: ทั้งหมด ▼] [สถานะ: Active ▼] │ +│ │ +│ ┌──────────────────────────────────────────────────────────────┐ │ +│ │ ชื่อ │ Username │ Role │ Status │ │ │ +│ ├───────────────────┼─────────────┼────────────────┼────────┼───┤ │ +│ │ สมชาย กิตติ │ somchai.k │ Document Ctrl │ ✅ │[⚙️]│ │ +│ │ วิชัย สมศรี │ wichai.s │ Editor │ ✅ │[⚙️]│ │ +│ │ มานะ พงษ์ดี │ mana.p │ Org Admin │ ✅ │[⚙️]│ │ +│ │ สมหญิง รักดี │ somying.r │ Viewer │ ⛔ │[⚙️]│ │ +│ └──────────────────────────────────────────────────────────────┘ │ +│ │ +└──────────────────────────────────────────────────────────────────────┘ + +User Edit Drawer (Slide in from right): +┌──────────────────────────┐ +│ แก้ไขผู้ใช้งาน │ +│ ──────────────────── │ +│ ชื่อ: [สมชาย กิตติ ] │ +│ Email: [somchai@... ] │ +│ Role: [Document Ctrl ▼] │ +│ Status: ✅ Active [Toggle]│ +│ │ +│ [รีเซ็ตรหัสผ่าน] │ +│ [❌ ยกเลิก] [✅ บันทึก] │ +└──────────────────────────┘ +``` + +--- + +### SCR-025: Document Number Config (Superadmin) + +``` +┌─ ตั้งค่าเลขที่เอกสาร ────────────────────────────────────────────────┐ +│ Project: LCBP3 [+ เพิ่ม Format ใหม่] │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────┐ │ +│ │ ประเภท │ Format Template │ Reset │ Actn │ │ +│ ├─────────────────┼────────────────────────────────┼────────┼──────┤ │ +│ │ Letter │ {PROJECT}-{ORIG}-{RECP}-L-{SEQ:4}-{YY}│ Yearly│[✏️]│ │ +│ │ RFI │ {PROJECT}-{ORIG}-{RECP}-I-{SEQ:4}-{YY}│ Yearly│[✏️]│ │ +│ │ RFA-Shop Dwg │ {PROJECT}-RFA-{DISC}-{SEQ:4} │ Never │[✏️]│ │ +│ │ Transmittal │ {PROJECT}-{ORIG}-{RECP}-T-{SEQ:4}-{YY}│ Yearly│[✏️]│ │ +│ └─────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Edit Format Inline: │ +│ ┌─────────────────────────────────────────────────────────────────┐ │ +│ │ Template: [{PROJECT}-{ORIG}-{RECP}-L-{SEQ:4}-{YY} ] │ │ +│ │ Preview: [LCBP3-สค.-กทท.-L-0001-68] │ │ +│ │ ✅ Format ถูกต้อง │ │ +│ │ [ยกเลิก] [✅ บันทึก] │ │ +│ └─────────────────────────────────────────────────────────────────┘ │ +└───────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 5. 🎨 Design System Reference + +### Color Tokens +```css +/* Primary — ใช้กับ Action Buttons, Links */ +--primary: hsl(221, 83%, 53%); /* Blue-600 */ +--primary-hover: hsl(221, 83%, 45%); + +/* Status Colors */ +--status-draft: hsl(48, 96%, 53%); /* Yellow */ +--status-submitted: hsl(217, 91%, 60%); /* Blue */ +--status-review: hsl(24, 95%, 53%); /* Orange */ +--status-approved: hsl(142, 71%, 45%); /* Green */ +--status-rejected: hsl(0, 84%, 60%); /* Red */ +--status-cancelled: hsl(215, 14%, 55%); /* Gray */ +--status-overdue: hsl(0, 84%, 60%); /* Red (same as rejected) */ + +/* Background */ +--bg-base: hsl(222, 47%, 11%); /* Dark Navy (dark mode base) */ +--bg-surface: hsl(222, 47%, 16%); /* Card surface */ +--bg-muted: hsl(215, 28%, 17%); /* Muted sections */ +``` + +### Typography +```css +font-family: 'Inter', 'Noto Sans Thai', sans-serif; + +/* Scale */ +--text-xs: 0.75rem; /* 12px — Badge, Caption */ +--text-sm: 0.875rem; /* 14px — Table cell, Label */ +--text-base:1rem; /* 16px — Body */ +--text-lg: 1.125rem; /* 18px — Subheading */ +--text-xl: 1.25rem; /* 20px — Page title */ +--text-2xl: 1.5rem; /* 24px — Dashboard KPI */ +``` + +### Component States +| Component | Default | Hover | Active | Disabled | Error | +|-----------|---------|-------|--------|----------|-------| +| Button Primary | bg-primary | bg-primary-hover | scale-95 | opacity-50 | — | +| Input | border-gray-300 | border-primary | border-primary ring | border-gray-200 | border-red-500 | +| Table Row | bg-surface | bg-muted | — | opacity-60 | bg-red-50 | +| Badge | per status color | — | — | — | — | + +--- + +## 6. 📱 Responsive Breakpoints + +| Breakpoint | Width | Behavior | +|-----------|-------|---------| +| `sm` | < 640px | Mobile: Sidebar → Drawer, Table → Cards | +| `md` | 640-1024px | Tablet: Collapsed Sidebar | +| `lg` | > 1024px | Desktop: Full Sidebar | + +**Mobile-specific Rules (UI-Rule 5.11):** +- ตาราง → Card View อัตโนมัติ +- Sidebar → Collapsible Hamburger Drawer +- Action Panel → Bottom Sheet แทน Inline Panel + +--- + +## 7. ⚡ Interaction Patterns + +### Optimistic Updates (UI-Rule 5.10) +``` +User กด "Approve" → UI เปลี่ยนสถานะทันที (ไม่รอ API) + ↓ +API ตอบกลับ Success → ยืนยัน UI ที่เปลี่ยนแล้ว + ↓ (ถ้า API ล้มเหลว) +Rollback UI → แสดง Toast Error: "เกิดข้อผิดพลาด กรุณาลองใหม่" +``` + +### Auto-save Draft (UI-Rule 5.12) +``` +User พิมพ์ใน Form → debounce 2 วินาที → บันทึกลง localStorage +ปิด Browser → เปิดใหม่ → แสดง Banner: "พบ Draft ที่บันทึกไว้ [กู้คืน] [ทิ้ง]" +``` + +### File Upload Progress +``` +เลือกไฟล์ → แสดง Progress Bar → ClamAV Scan → ✅/❌ +``` + +--- + +## 📝 Document Control + +- **Version:** 1.0.0 | **Status:** DRAFT +- **Created:** 2026-03-11 | **Owner:** Nattanin Peancharoen +- **Next Step:** สร้าง High-fidelity Mockup ใน Figma ตามโครงสร้างนี้ +- **Figma Link:** [TBD — สร้างใน Figma Community หรือ Self-hosted Penpot] +- **Classification:** Internal Use Only diff --git a/specs/01-requirements/README.md b/specs/01-requirements/README.md index f210b61..6fc0c1c 100644 --- a/specs/01-requirements/README.md +++ b/specs/01-requirements/README.md @@ -19,6 +19,9 @@ This directory contains the functional and non-functional requirements for the L 1. [Objectives & Goals](./01-01-objectives.md) - Project objectives and success criteria 2. [System Architecture & Technology](../02-Architecture/README.md) - High-level architecture requirements 3. [Functional Requirements](./01-02-modules/01-02-00-index.md) - Detailed feature specifications +4. **[📖 User Stories](./01-04-user-stories.md)** - 27 User Stories (8 Epics, MoSCoW priority, AC links) +5. **[🛡️ Edge Cases & Business Rules](./01-06-edge-cases-and-rules.md)** - 37 Edge Cases ป้องกัน Bug +6. **[🖼️ UI/UX Wireframes](./01-07-ui-wireframes.md)** - 26 Screens, Navigation Map, Design System ### Functional Areas @@ -55,10 +58,12 @@ This directory contains the functional and non-functional requirements for the L ### Cross-Cutting Concerns -4. [Access Control & RBAC](./01-01-business-rules/01-01-01-rbac-matrix.md) - 4-level hierarchical RBAC -5. [UI/UX Requirements](./01-01-business-rules/01-01-03-ui-ux-rules.md) - User interface specifications -6. [Non-Functional Requirements](./01-01-business-rules/01-01-04-non-functional-rules.md) - Performance, security, scalability -7. [Testing Requirements](./01-01-business-rules/01-01-05-testing-rules.md) - Test strategy and coverage +4. [Access Control & RBAC](./01-01-business-rules/01-02-01-rbac-matrix.md) - 4-level hierarchical RBAC +5. [UI/UX Requirements](./01-02-business-rules/01-02-03-ui-ux-rules.md) - User interface specifications +6. [Non-Functional Requirements](./01-02-business-rules/01-02-04-non-functional-rules.md) - Performance, security, scalability +7. [Testing Requirements](./01-02-business-rules/01-02-05-testing-rules.md) - Test strategy and coverage +8. **[✅ Acceptance Criteria (UAT)](./01-05-acceptance-criteria.md)** - MVP Go-Live criteria, UAT Scenarios, Sign-off checklist +9. **[🎓 Training Plan](../00-Overview/00-06-training-plan.md)** - Training Curriculum, Change Management (see also `00-Overview/`) --- diff --git a/specs/03-Data-and-Storage/03-06-migration-business-scope.md b/specs/03-Data-and-Storage/03-06-migration-business-scope.md new file mode 100644 index 0000000..9cc9170 --- /dev/null +++ b/specs/03-Data-and-Storage/03-06-migration-business-scope.md @@ -0,0 +1,309 @@ +# 📦 Legacy Data Migration — Business Scope & Governance + +--- +title: 'Migration Business Scope, Data Governance, and Go/No-Go Gates' +version: 1.0.0 +status: DRAFT — Awaiting Stakeholder Confirmation +owner: Nattanin Peancharoen (PO + Migration Lead) +last_updated: 2026-03-11 +related: + - specs/03-Data-and-Storage/03-04-legacy-data-migration.md ← Technical Implementation + - specs/03-Data-and-Storage/03-05-n8n-migration-setup-guide.md + - specs/06-Decision-Records/ADR-017-ollama-data-migration.md + - specs/06-Decision-Records/ADR-018-ai-boundary.md + - specs/00-Overview/00-04-stakeholder-signoff-and-risk.md ← Risk Register (RISK-002) +--- + +> [!IMPORTANT] +> เอกสารนี้กำหนด **ขอบเขตทางธุรกิจ** ของการ Migration เท่านั้น +> รายละเอียดทางเทคนิค (n8n Workflow, Ollama Prompt, API Spec) อยู่ใน `03-04-legacy-data-migration.md` + +> [!NOTE] +> "เอกสารเก่า" คือเอกสารที่บริหารจัดการผ่าน Email + File Share ก่อนระบบ LCBP3-DMS +> จำนวน: ประมาณ **20,000 ไฟล์ PDF** พร้อม Metadata ใน Excel + +--- + +## 1. 🎯 Migration Objective + +| วัตถุประสงค์ | รายละเอียด | +|------------|-----------| +| **Continuity** | ผู้ใช้สามารถค้นหาและอ้างอิงเอกสารเก่าในระบบใหม่ได้ทันที | +| **Traceability** | Workflow ใหม่สามารถ Link กลับไปยัง Correspondence เก่าได้ | +| **Searchability** | เอกสารเก่าถูก Index ใน Elasticsearch — ค้นหาได้ด้วย Full-text | +| **Compliance** | Audit Trail ครบ: รู้ว่าใครนำเข้า เมื่อไหร่ จาก Batch ไหน | + +--- + +## 2. 📋 Data Scope Definition + +### 2.1 ✅ IN SCOPE — นำเข้าระบบใหม่ + +| ประเภทเอกสาร | Subdirectory | Volume (ประมาณ) | Priority | +|-------------|-------------|----------------|---------| +| **Correspondence** (Letters, RFI) | `CORR/` | ~8,000 ไฟล์ | 🔴 High | +| **RFA + Shop Drawings** | `RFA/` | ~5,000 ไฟล์ | 🔴 High | +| **Contract Drawings** | `CD/` | ~3,000 ไฟล์ | 🟠 Medium | +| **Transmittals** | `TRM/` | ~2,000 ไฟล์ | 🟠 Medium | +| **Reports & Minutes** | `RPT/` | ~2,000 ไฟล์ | 🟡 Low | + +**ช่วงเวลาที่ Include:** +- **เริ่มต้น:** 1 มกราคม 2564 (โครงการเริ่ม) +- **สิ้นสุด:** วันก่อน Go-Live — 1 วัน (เอกสารหลังจากนั้นใช้ระบบใหม่) + +**เงื่อนไข Include:** +- ไฟล์ต้องเป็น PDF (หรือ DWG สำหรับ Drawing) +- ไฟล์ต้อง Readable โดย Tika/Ollama (ไม่ Corrupted) +- มี Row ใน Excel Metadata ที่ตรงกัน (document_number ไม่ว่าง) + +--- + +### 2.2 ❌ OUT OF SCOPE — ไม่นำเข้า + +| รายการ | เหตุผล | +|--------|-------| +| **เอกสารก่อนปี 2564** | ก่อนเริ่มโครงการ LCBP3 Phase 3 | +| **Email Body / Attachments ที่ไม่ใช่ PDF** | Format ไม่รองรับ | +| **Draft ที่ไม่เคย Submit** | ไม่มีเลขเอกสารทางการ | +| **ไฟล์ที่ Corrupted หรืออ่านไม่ได้** | ไปที่ Reject Log | +| **ข้อมูล Financial / Cost Records** | ไม่อยู่ใน DMS Scope | +| **Personal Communication (ไม่มีเลขทางการ)** | ไม่ใช่เอกสารทางการ | +| **วิดีโอ / รูปภาพ Standalone** | ไม่ใช่ Document | +| **ไฟล์ DWG ที่ไม่มี PDF คู่** | ออก PDF ก่อนนำเข้า (Admin Task) | + +--- + +### 2.3 📊 Migration Tiers (ลำดับความสำคัญ) + +``` +Tier 1 — ต้องนำเข้าก่อน Go-Live (บล็อก Go-Live ถ้าไม่เสร็จ): +┌─────────────────────────────────────────────────────────┐ +│ Correspondence สำคัญ (marked as "CRITICAL" ใน Excel) │ +│ RFA ที่ยัง Active อยู่ (status != FINAL_APPROVED) │ +│ จำนวนประมาณ: 2,000 เอกสาร │ +│ Deadline: T-3 วันก่อน Go-Live │ +└─────────────────────────────────────────────────────────┘ + +Tier 2 — นำเข้าภายใน 2 สัปดาห์หลัง Go-Live: +┌─────────────────────────────────────────────────────────┐ +│ Correspondence ทั่วไป + RFA FINAL ที่เสร็จแล้ว │ +│ Contract Drawings │ +│ จำนวนประมาณ: 10,000 เอกสาร │ +│ Deadline: Go-Live + 14 วัน │ +└─────────────────────────────────────────────────────────┘ + +Tier 3 — นำเข้าภายใน 1 เดือนหลัง Go-Live: +┌─────────────────────────────────────────────────────────┐ +│ Reports, Minutes, Archives │ +│ เอกสารที่ AI Confidence ต่ำ (ต้องผ่าน Manual Review) │ +│ จำนวนประมาณ: 8,000 เอกสาร │ +│ Deadline: Go-Live + 30 วัน │ +└─────────────────────────────────────────────────────────┘ +``` + +--- + +## 3. 🗃️ Source Data Assessment + +### 3.1 Excel Metadata Schema (Legacy) + +| Column | Field ใหม่ | บังคับ | หมายเหตุ | +|--------|----------|-------|---------| +| `DOC_NO` | `document_number` | ✅ | ใช้เป็น Idempotency Key | +| `TITLE` | `title` | ✅ | AI จะ Suggest แก้ไขถ้าผิด Format | +| `DATE` | `reference_date` | ✅ | วันที่เอกสาร (ไม่ใช่วันนำเข้า) | +| `FROM_ORG` | `sender_org_id` | ✅ | Map ด้วย org_code lookup table | +| `TO_ORG` | `receiver_org_id` | ✅ | Map ด้วย org_code lookup table | +| `TYPE` | `category` | ✅ | AI ตรวจสอบ Enum ที่ถูกต้อง | +| `DISCIPLINE` | `discipline` | ❌ | Optional — AI Extract จาก Title | +| `CONTRACT_NO` | `contract_id` | ❌ | Map ด้วย contract lookup table | +| `PROJECT_NO` | `project_id` | ✅ | ต้องมี (ทุกเอกสาร) | +| `FILE_PATH` | `source_file_path` | ✅ | Path ใน NAS staging folder | +| `REVISION` | `revision` | ❌ | Detect จากเลขเอกสาร | + +### 3.2 Organization Code Mapping + +> ต้องสร้าง Lookup Table ก่อนเริ่ม Migration — Superadmin ทำใน Pre-migration Setup + +| Legacy Code (Excel) | Organization ใหม่ | org_id (System) | +|--------------------|-----------------|----------------| +| กทท. | การท่าเรือแห่งประเทศไทย | TBD (ดูจาก DB) | +| สค. | สำนักงานโครงการ | TBD | +| TEAM | TEAM | TBD | +| คคง. | คณะกรรมการตรวจงาน | TBD | +| ผรม. | ผู้รับจ้างหลัก | TBD | + +> **Action Item:** Superadmin ต้อง Fill in `org_id` ก่อน Migration เริ่ม + +--- + +## 4. 📅 Migration Timeline + +``` +T-6 สัปดาห์ก่อน Go-Live: +├── Data Audit: นับไฟล์, ตรวจ Excel Quality +├── สร้าง Organization Lookup Table +├── ติดตั้ง n8n + Ollama บน Staging Environment +└── สร้าง Migration Bot User + Token (7 วัน, IP Whitelist) + +T-5 สัปดาห์: +├── DRY RUN 1: Batch 50 เอกสาร — ตรวจ Error Rate +├── แก้ไข Mapping / Prompt ตามผล Dry Run 1 +└── Tier 1 List ยืนยันกับ Document Control แต่ละ Org + +T-4 สัปดาห์: +├── DRY RUN 2: Batch 500 เอกสาร — ตรวจ Scale Issue +├── Admin Review Queue Round 1 +└── Performance Check: Runtime ≈ ตามประมาณการ? + +T-3 สัปดาห์: +├── **Production Migration START — Tier 1 (2,000 เอกสาร)** +├── ตรวจ Integrity ทุกวัน (SQL Verification Queries) +└── Token Expire? → Renew (ไม่เกิน 7 วัน/ครั้ง) + +T-2 สัปดาห์: +├── Verify Tier 1 Complete → Migration Go/No-Go Gate #1 +├── Start Tier 2 Migration (10,000 เอกสาร) +└── Admin Review Queue Round 2 + +Go-Live Day: +├── Migration Bot Token: REVOKE ทันที +├── Staging Folder: Read-only (ยังไม่ลบ — 30 วัน) +└── Tier 1 + Tier 2 ต้องเสร็จ✅ ก่อน Go-Live + +T+1 เดือน: +├── Tier 3 Migration (8,000 เอกสาร) +├── Final Integrity Check +└── Legacy System → Read-only (ไม่ลบ — เก็บ 6 เดือน) +``` + +--- + +## 5. ✅ Migration Go/No-Go Gates + +### Gate #1: Before Production Migration Starts (T-3 สัปดาห์) + +| เกณฑ์ | ต้องผ่าน | วิธีวัด | +|-------|---------|--------| +| Dry Run 2 JSON Parse Success | ≥ 95% | n8n Execution Log | +| Dry Run 2 AI Category Accuracy | ≥ 90% (Manual Spot-check 50 docs) | Human Review | +| Idempotency Test: รัน Batch ซ้ำ | 0 Duplicate Records | SQL Count | +| Organization Mapping ครบ | 100% | Lookup Table review | +| Migration Bot Token Active + Whitelisted | ✅ | API Test | +| Staging NAS Space: ≥ 500GB free | ✅ | QNAP Dashboard | + +**Owner:** Nattanin P. | **Approver:** Org Admin ทุกองค์กร + +--- + +### Gate #2: Before Go-Live (T-1 วัน) + +| เกณฑ์ | ต้องผ่าน | +|-------|---------| +| Tier 1 Migration: 100% เสร็จ + Verified | ✅ | +| Tier 2 Migration: ≥ 90% เสร็จ + Verified | ✅ | +| Review Queue: ≤ 5% ค้างอยู่ (Critical Tier 1 = 0%) | ✅ | +| Migration Bot Token: REVOKED | ✅ | +| Integrity Queries ผ่านทั้งหมด | ✅ | +| Legacy System ยังเข้าถึงได้ (Read-only Fallback) | ✅ | + +--- + +### Gate #3: Post Go-Live (T+30 วัน) + +| เกณฑ์ | ต้องผ่าน | +|-------|---------| +| Tier 3 Migration: 100% เสร็จ | ✅ | +| User Search Test: สามารถค้นหา Legacy Doc ใน ES | ✅ | +| Zero Orphan Files ใน Staging | ✅ | +| Legacy System Archive เสร็จ (Compress + Store) | ✅ | + +--- + +## 6. 🧑‍💼 Data Ownership & Responsibility + +| Responsibility | Owner | Action | +|---------------|-------|--------| +| **Excel Metadata Quality** | Document Control (สค.) | ทำความสะอาดก่อน T-6 | +| **File Organization บน NAS** | Nattanin P. + IT | จัด Folder structure | +| **Organization Lookup Table** | Superadmin (NAP) | สร้างก่อน T-6 | +| **Tier 1 Document List** | Document Control ทุก Org | ยืนยัน T-5 | +| **Daily Monitoring (n8n Runs)** | Nattanin P. | T-3 ถึง Go-Live | +| **Admin Review Queue** | Document Control (สค.) | ทุกเช้าวันทำงาน | +| **Post-migration Verification** | Nattanin P. | After each Gate | +| **Legacy System Archival** | กทท. IT + NAP | T+30 | + +--- + +## 7. 🔒 Data Privacy & Security + +### ข้อกำหนดการ Migrate + +1. **Files ต้อง Scan ClamAV ก่อน** ก่อนเข้า Staging Folder + - Migration Bot มี Bypass Virus Scan Permission เฉพาะกรณีนี้ + - หมายความว่า Pre-scan ต้องทำโดย Admin ก่อน (ไม่ใช่ Skip) + +2. **Migration Token Restrictions** (ดู `03-04-legacy-data-migration.md` Section 2): + - IP Whitelist: NAS IP เท่านั้น + - Expiry: 7 วัน (ต้อง Renew ทุกสัปดาห์) + - Revoke ทันที หลัง Migration เสร็จ + +3. **AI Isolation** (ตาม ADR-018): + - Ollama ไม่มี Direct DB Access + - Ollama เห็นแค่ Text Content จากไฟล์ PDF — ไม่เห็น System Data + - Output ของ AI ต้องผ่าน Backend Validation ก่อน Write + +4. **Audit Log**: ทุก Record ที่ Import มี: + ```json + { "created_by": "SYSTEM_IMPORT", "batch_id": "migration_YYYYMMDD", "action": "IMPORT" } + ``` + +5. **Data Retention ของ Legacy Files**: + - Staging Folder: เก็บ 30 วันหลัง Migration เสร็จ → แล้วลบ + - ต้นฉบับ (ใน Old System): เก็บ 6 เดือน Read-only → Archive + +--- + +## 8. 🔄 Rollback & Contingency + +### กรณี Migration ล้มเหลว (Error Rate > 20%) + +``` +1. หยุด n8n Workflow ทันที +2. Disable Migration Bot Token (SQL) +3. Run Rollback SQL (ดู 03-04-legacy-data-migration.md Section 4) +4. แจ้ง PO + Org Admin: "Migration หยุด — เหตุผล: ___" +5. Post-mortem: วิเคราะห์ Root Cause +6. Fix → Dry Run ใหม่ → Gate #1 ใหม่ +``` + +### กรณี Go-Live โดย Tier 2 ไม่เสร็จ (Emergency) + +**เปิดใช้ Parallel Operation:** +- ระบบใหม่: เอกสาร Tier 1 + เอกสารใหม่หลัง Go-Live +- Legacy System: เปิด Read-only สำหรับเอกสาร Tier 2/3 ยังไม่ Migrate +- Timeline Extension: Tier 2 ต้องเสร็จภายใน T+7 (ไม่เกิน 1 สัปดาห์หลัง Go-Live) + +--- + +## 9. 📊 Migration Success Metrics + +| Metric | Target | วิธีวัด | +|--------|--------|--------| +| Total Records Imported | ≥ 95% ของ In-Scope | SQL COUNT vs Excel Row Count | +| Auto-import Rate (confidence ≥ 0.85) | ≥ 70% | n8n Execution Report | +| Review Queue Clearance | ≥ 95% ก่อน Go-Live | Review Queue Table | +| Reject Rate (Corrupted/Unreadable) | < 5% | Reject Log | +| Duplicate Records | 0 | SQL HAVING COUNT > 1 | +| Tag Extraction Rate | ≥ 80% ของ Auto-imported docs มี ≥ 1 Tag | SQL | +| Post-migration Search Hit Rate | ≥ 90% ของ Legacy doc numbers ค้นหาเจอ | Manual Test 100 samples | + +--- + +## 📝 Document Control + +- **Version:** 1.0.0 | **Status:** DRAFT +- **Created:** 2026-03-11 | **Owner:** Nattanin Peancharoen +- **Stakeholder Review:** T-6 สัปดาห์ก่อน Go-Live +- **Technical Detail:** ดู [`03-04-legacy-data-migration.md`](../03-Data-and-Storage/03-04-legacy-data-migration.md) +- **Classification:** Internal Use Only diff --git a/specs/03-Data-and-Storage/n8n.workflow.json b/specs/03-Data-and-Storage/n8n.workflow.json index 66b797a..389a3f6 100644 --- a/specs/03-Data-and-Storage/n8n.workflow.json +++ b/specs/03-Data-and-Storage/n8n.workflow.json @@ -1,4 +1,4 @@ -{ +{ "name": "LCBP3 Migration Workflow v1.8.0", "nodes": [ { @@ -701,7 +701,7 @@ "name": "Build Import Payload", "typeVersion": 2, "parameters": { - "jsCode": "const item = $input.first();\nconst config = $('Set Configuration').first().json.config;\nconst ai = item.json.ai_result || {};\n\nreturn [{\n json: {\n ...item.json,\n import_payload: {\n document_number: String(item.json.document_number || ''),\n title: String(ai.subject || item.json.title || 'ไม่มีชื่อเรื่อง'),\n category: ai.type_code || 'LETTER',\n source_file_path: item.json.file_path || '/dev/null',\n ai_confidence: ai.confidence || 0.8,\n migrated_by: 'SYSTEM_IMPORT',\n batch_id: config.BATCH_ID,\n project_id: Number(ai.project_id || config.PROJECT_ID),\n issued_date: ai.issued_date || '',\n received_date: ai.received_date || '',\n body: ai.body || '',\n details: {\n legacy_number: item.json.legacy_number || '',\n remark: ai.remark || '',\n key_points: ai.key_points || [],\n tags: ai.tags || []\n }\n }\n }\n}];" + "jsCode": "const item = $input.first();\nconst config = $('Set Configuration').first().json.config;\nconst ai = item.json.ai_result || {};\n\nreturn [{\n json: {\n ...item.json,\n import_payload: {\n document_number: String(item.json.document_number || ''),\n title: String(ai.subject || item.json.title || 'ไม่มีชื่อเรื่อง'),\n category: ai.type_code || 'LETTER',\n source_file_path: item.json.file_path || '/dev/null',\n ai_confidence: ai.confidence || 0.8,\n migrated_by: 'SYSTEM_IMPORT',\n batch_id: config.BATCH_ID,\n project_id: Number(ai.project_id || config.PROJECT_ID),\n discipline_id: ai.discipline_id || null,\n sender_id: ai.sender_id || null,\n receiver_id: ai.receiver_id || null,\n document_date: ai.issued_date || '',\n issued_date: ai.issued_date || '',\n received_date: ai.received_date || '',\n body: ai.body || '',\n details: {\n legacy_number: item.json.legacy_number || '',\n remark: ai.remark || '',\n key_points: ai.key_points || [],\n tags: ai.tags || []\n }\n }\n }\n}];" }, "type": "n8n-nodes-base.code", "position": [ @@ -738,6 +738,12 @@ 17000, 6592 ], + "credentials": { + "mySql": { + "id": "CHHfbKhMacNo03V4", + "name": "MySQL account" + } + }, "notes": "Insert into correspondence_tags" } ], diff --git a/specs/04-Infrastructure-OPS/04-08-release-management-policy.md b/specs/04-Infrastructure-OPS/04-08-release-management-policy.md new file mode 100644 index 0000000..1e3e727 --- /dev/null +++ b/specs/04-Infrastructure-OPS/04-08-release-management-policy.md @@ -0,0 +1,487 @@ +# 🚀 Release Management Policy — LCBP3-DMS v1.8.0 + +--- +title: 'Release Management Policy, Versioning Strategy, and Deployment Gates' +version: 1.0.0 +status: DRAFT +owner: Nattanin Peancharoen (System Architect / Release Manager) +last_updated: 2026-03-11 +related: + - specs/04-Infrastructure-OPS/04-04-deployment-guide.md ← Blue-Green Deployment Detail + - specs/04-Infrastructure-OPS/04-07-incident-response.md + - specs/06-Decision-Records/ADR-015-deployment.md + - specs/00-Overview/00-04-stakeholder-signoff-and-risk.md +--- + +> [!IMPORTANT] +> ทุก Release สู่ Production **ต้องผ่าน Release Gate** — ไม่มีข้อยกเว้น +> เอกสารนี้กำหนด Policy ที่ทุกคนในทีมต้องปฏิบัติตาม + +--- + +## 1. 🏷️ Versioning Strategy + +### Semantic Versioning (SemVer) — `MAJOR.MINOR.PATCH` + +``` +v1.8.1 +│ │ └── PATCH: Bug Fixes, Security Patches (Hotfix) +│ └──── MINOR: New Features, Enhancement (Sprint Release) +└────── MAJOR: Breaking Changes, Architectural Shift (กำหนดโดย PO) +``` + +| Type | ตัวอย่าง | เมื่อไหร่ | +|------|---------|---------| +| **MAJOR** | v1.0.0 → v2.0.0 | Breaking Change, Major Architecture Change | +| **MINOR** | v1.8.0 → v1.9.0 | New Feature หลังจาก Sprint สำเร็จ | +| **PATCH** | v1.8.0 → v1.8.1 | Bug Fix, Security Patch | + +### Branch Strategy (Git Flow) + +``` +main ─────────────────────────────────────── Production (Protected) + │ + ├── release/v1.9.0 ─────────────────────── Release Candidate + │ └── bugfix/xxx ──────────────────── Bug Fixes บน RC + │ + ├── develop ──────────────────────────── Integration Branch + │ ├── feature/corr-export ──────────── Feature Branch + │ ├── feature/notification-v2 ──────── Feature Branch + │ └── ... + │ + └── hotfix/v1.8.1-security-patch ──────── Hotfix (from main, back to main+develop) +``` + +### Tag Naming Convention + +```bash +# Release Tags +git tag -a v1.8.0 -m "Release v1.8.0: MVP Go-Live" +git tag -a v1.8.1 -m "Hotfix v1.8.1: Security patch CVE-XXXX" + +# Docker Image Tags +lcbp3-backend:v1.8.0 +lcbp3-backend:latest ← ชี้ไปยัง Version ล่าสุดที่ Production +lcbp3-backend:v1.8.0-rc.1 ← Release Candidate +``` + +--- + +## 2. 📋 Release Types & Cadence + +| Release Type | Cadence | Who Approves | Notes | +|-------------|---------|-------------|-------| +| **Sprint Release** (Minor) | ทุก 2 สัปดาห์ | PO + Lead Dev | ตามแผน Sprint | +| **Hotfix** (Patch) | ตามเหตุการณ์ | Lead Dev (P0/P1) → PO Notify | ไม่รอ Sprint | +| **Emergency Hotfix** | ทันที (P0) | Lead Dev → แจ้ง PO พร้อมกัน | Security, System Down | +| **Major Release** | กำหนดโดย PO | PO + กทท. Sign-off | Phase Change | + +### Sprint Release Calendar (ตัวอย่าง) + +``` +Sprint 1: 01–14 มี.ค. 2569 → Release v1.9.0 (28 มี.ค.) +Sprint 2: 15–28 มี.ค. 2569 → Release v1.10.0 (11 เม.ย.) +... +``` + +--- + +## 3. 🚦 Release Gate Process + +### Gate 1: Code Complete (วันสุดท้ายของ Sprint) +``` +✅ Feature Freeze — ไม่รับ Feature ใหม่เข้า Release Branch +✅ All PRs Merged to release/vX.Y.Z +✅ Version number อัปเดตใน package.json + CHANGELOG.md +``` + +### Gate 2: Quality Gate (T-3 วันก่อน Release) + +| Checkpoint | Tool | Threshold | +|-----------|------|----------| +| **TypeScript Compile** | `tsc --noEmit` | 0 Errors | +| **Unit Tests Pass** | Jest | ≥ 80% Pass Rate | +| **E2E Tests (Core Flows)** | Playwright/Cypress | 100% Core Flows ผ่าน | +| **Security Scan** | `npm audit` | 0 Critical/High Vulnerabilities | +| **Lint** | ESLint | 0 Errors (Warnings ยอมรับได้) | +| **Build Success** | Docker Build | Exit 0 | +| **Image Size** | Docker inspect | < 2GB (Backend), < 1.5GB (Frontend) | + +**Owner:** Lead Dev +**Tool:** Gitea CI/CD Pipeline (ADR-015) + +--- + +### Gate 3: Staging Validation (T-2 วันก่อน Release) + +| Checkpoint | ผ่านเมื่อ | Owner | +|-----------|---------|-------| +| Deploy to Staging Environment | สำเร็จ, ไม่มี Error | DevOps | +| Health Check `/health` → 200 | ✅ | Automated | +| Smoke Test (Manual): Login → Create Correspondence → Submit | ผ่าน | Dev หรือ QA | +| Migration Script (ถ้ามี Schema Change) | รันสำเร็จบน Staging Schema | DBA / Dev | +| Rollback Test: Deploy → Rollback → Verify | ระบบ Rollback ได้ใน < 5 นาที | DevOps | + +**Owner:** Nattanin P. + +--- + +### Gate 4: Release Approval (T-1 วันก่อน Release) + +``` +PO Review: ✅ Feature ครบตาม Sprint Goal? +PO Review: ✅ ไม่มี Known Blocker Issues? +PO Sign-off: ✅ อนุมัติ Release + +ถ้ามี Schema Change: + DBA Confirm: ✅ Schema SQL พร้อม Apply บน Production + DBA Confirm: ✅ Rollback SQL พร้อม (ถ้าจำเป็น) +``` + +**Owner:** Nattanin P. (PO + Release Manager) + +--- + +### Gate 5: Production Deployment & Verification + +``` +1. Deploy ตาม Blue-Green Process (deploy.sh) + → Full script: specs/04-Infrastructure-OPS/04-04-deployment-guide.md + +2. Post-Deploy Verification (15 นาที): + ✅ Health Check: All containers healthy + ✅ Smoke Test: Login + Core Feature + ✅ Error Rate: < 1% (Grafana) ใน 15 นาทีแรก + ✅ Response Time: P90 < 500ms (Grafana) + +3. ถ้าผ่าน → RELEASE COMPLETE ✅ +4. ถ้าไม่ผ่าน → ROLLBACK ทันที (rollback.sh) +``` + +--- + +## 4. 🔥 Hotfix Process + +### เมื่อไหร่ต้อง Hotfix + +| Priority | ตัวอย่าง | SLA Start Hotfix | Deploy Target | +|---------|---------|-----------------|--------------| +| **P0 — Critical** | ระบบล่ม, Data Corruption, Security Breach | ทันที (< 30 นาที) | < 4 ชั่วโมง | +| **P1 — High** | Feature หลักทำงานผิด, Login Fail | < 2 ชั่วโมง | < 24 ชั่วโมง | +| **P2 — Medium** | Feature รองทำงานผิด | ใน Sprint ถัดไป | Sprint Release | +| **P3 — Low** | UI Cosmetic, Minor UX | Backlog | Sprint Release | + +### Hotfix Workflow + +``` +1. Identify Bug (P0 หรือ P1) + ↓ +2. Create Branch: hotfix/v1.8.1-brief-description from main + ↓ +3. Fix + Unit Test + Security Check (< 2 ชั่วโมง สำหรับ P1) + ↓ +4. PR → Code Review (อย่างน้อย 1 คน) + ↓ +5. กรณี P0: Skip Staging → Deploy ตรง Production + กรณี P1: Quick Staging Smoke Test → Deploy Production + ↓ +6. Merge back: main ← hotfix + develop ← hotfix + ↓ +7. Tag: v1.8.1 + Update CHANGELOG.md + ↓ +8. Notify PO + Stakeholders (LINE Group) +``` + +### P0 Emergency Deploy Script + +```bash +# ใช้เฉพาะกรณี P0 เท่านั้น — ข้าม Staging +# ต้องได้รับ Lead Dev Approval ก่อน + +cd /volume1/lcbp3/scripts +./deploy.sh --hotfix --skip-staging --version v1.8.1 + +# Log ทุก Step อัตโนมัติ +# Auto-rollback ถ้า Health Check Fail +``` + +--- + +## 5. 🔄 Rollback Policy + +### เมื่อไหร่ต้อง Rollback + +| Trigger | Threshold | Action | +|---------|----------|--------| +| Health Check Fail หลัง Deploy | 3 consecutive failures | Auto-rollback | +| Error Rate สูง | > 5% ใน 15 นาทีแรก | Manual Rollback (DevOps trigger) | +| P90 Response Time สูงมาก | > 2000ms ต่อเนื่อง 5 นาที | Manual Rollback | +| Critical Bug พบใน Production | P0 Bug | Manual Rollback ทันที | +| Migration Fail | Error Rate > 20% | Manual Rollback + Notify | + +### Rollback SLA + +| Scenario | Target Rollback Time | +|----------|---------------------| +| Blue-Green Switch (nginx reload) | < 30 วินาที | +| Full Container Restart | < 5 นาที | +| Database Rollback (SQL Revert) | < 30 นาที | +| Full System Restore (Backup) | < 4 ชั่วโมง (RTO) | + +### Rollback Decision Tree + +``` +ตรวจพบปัญหาหลัง Deploy + ↓ + P0 Bug? ──→ YES → Rollback ทันที (ไม่ต้องรอ Approval) + ↓ NO + Error Rate > 5%? ──→ YES → Consult Developer → Rollback ถ้าแก้ไม่ได้ใน 30 นาที + ↓ NO + Response Time > 2s? ──→ YES → Monitor 15 นาที → ถ้าไม่ดีขึ้น → Rollback + ↓ NO + Continue Monitoring (1 ชั่วโมง Hypercare) +``` + +--- + +## 6. 🧪 Testing Requirements per Release Type + +### Sprint Release (Full Testing) + +``` +Unit Tests: ≥ 80% coverage จาก Code Changed +Integration Tests: ทุก API Endpoint ที่เปลี่ยน +E2E Tests: Core Flows (Login, Submit Doc, Approve) +Security Scan: npm audit + OWASP ZAP Passive Scan +Performance Test: ถ้า Feature ใหม่กระทบ DB หรือ API +``` + +### Hotfix (Fast Testing) + +``` +Unit Tests: เฉพาะ Code ที่ Fix +Regression Tests: Test ที่ตรงกับ Bug ที่แก้ +Smoke Test: Login + Feature ที่ Fix +Security Check: npm audit (ถ้าเป็น Security Bug) +``` + +### Schema Change Requirements + +> ทุกครั้งที่มี DB Schema Change ต้องปฏิบัติตาม ADR-009 (No TypeORM Migrations) + +``` +1. แก้ไข: specs/03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql +2. Update: specs/03-Data-and-Storage/03-01-data-dictionary.md +3. เตรียม: Delta SQL file ใน specs/03-Data-and-Storage/deltas/ + → ชื่อ: XX-description.sql (เรียงตามลำดับ) +4. Test บน Staging ก่อน Apply Production +5. แจ้ง User: ต้องมี Maintenance Window ถ้า ALTER TABLE กระทบ Performance +``` + +--- + +## 7. 📢 Release Communication + +### Release Note Template + +```markdown +# Release Notes — LCBP3-DMS v[X.Y.Z] +**Date:** YYYY-MM-DD | **Type:** Sprint Release / Hotfix + +## 🆕 New Features +- [Feature Name]: [Brief description] + +## 🐛 Bug Fixes +- **[BUG-ID]** [Screen/Module]: [What was wrong → What's fixed] + +## 🔒 Security Updates +- [CVE/Issue]: [Description] + +## ⚠️ Breaking Changes +- [If any — ระบุชัดเจน] + +## 📋 Schema Changes +- [Table]: [Column added/modified/removed] +- **Action Required:** Admin ต้อง Apply SQL ใน `deltas/XX-description.sql` + +## 🔧 Configuration Changes +- [Env Var]: [Change description] + +## 📊 Performance Impact +- [Module]: [Expected improvement/change] +``` + +### Communication Channels + +| Release Type | Channel | ผู้รับ | Timing | +|-------------|---------|-------|--------| +| **Sprint Release** | LINE Group (Support) | Org Admin ทุกองค์กร | T-1 วัน (แจ้งล่วงหน้า) | +| **Sprint Release** | Email | ผู้บริหาร + PO | หลัง Deploy เสร็จ | +| **Hotfix (P1)** | LINE Group | Org Admin | พร้อมกับ Deploy | +| **Hotfix (P0)** | LINE Direct | กทท. IT + NAP On-call | ก่อน Deploy (แจ้งว่ากำลังแก้) | +| **Maintenance Window** | Email + LINE | ทุก User | T-24 ชั่วโมง | + +### Maintenance Window Policy + +``` +ทำได้เฉพาะ: +- วันอังคารหรือพฤหัสบดี (ลด Impact) +- เวลา 20:00–23:00 (นอกเวลางาน) +- ต้องแจ้ง 24 ชั่วโมงล่วงหน้า +- ระยะเวลา Maintenance: ไม่เกิน 2 ชั่วโมง + +ยกเว้น P0 Emergency: ทำได้ทันที ไม่ต้องรอ Window +``` + +--- + +## 8. 📊 Release Metrics & Tracking + +| Metric | Target | วิธีวัด | +|--------|--------|--------| +| **Deployment Frequency** | 1 ครั้ง/สองสัปดาห์ | Gitea Release History | +| **Lead Time for Change** | < 3 วัน (code → production) | Commit Date → Deploy Date | +| **Change Failure Rate** | < 5% (% Release ที่ต้อง Rollback) | Rollback Log | +| **Mean Time to Restore (MTTR)** | < 4 ชั่วโมง (P0) / < 8 ชั่วโมง (P1) | Incident Log | +| **Time to Rollback** | < 5 นาที (Blue-Green Switch) | Deploy Log | + +> **หมายเหตุ:** Metrics เหล่านี้คือ **DORA Metrics** (DevOps Research and Assessment) +> ติดตามใน Monthly Engineering Review + +--- + +## 9. 🗂️ CI/CD Pipeline (Gitea Actions) + +### Pipeline Stages (ทุก PR เข้า `develop` หรือ `release/*`) + +```yaml +# .gitea/workflows/ci.yml (ตัวอย่าง Structure) + +stages: + - name: "1. Code Quality" + jobs: + - typecheck # tsc --noEmit + - lint # ESLint + - unit-test # Jest (coverage report) + + - name: "2. Security" + jobs: + - dependency-audit # npm audit + - secret-scan # gitleaks (ตรวจ Secret ใน Code) + + - name: "3. Build" + jobs: + - build-backend # docker build lcbp3-backend:${BRANCH_SHA} + - build-frontend # docker build lcbp3-frontend:${BRANCH_SHA} + + - name: "4. Integration Test" (เฉพาะ release/* branch) + jobs: + - deploy-staging # Deploy to Staging Environment + - smoke-test # Playwright Smoke Test + - api-test # Postman/Newman Core API Tests + + - name: "5. Release" (เฉพาะ main branch, Manual Trigger) + jobs: + - tag-version # git tag vX.Y.Z + - push-registry # Push image ไปยัง Internal Registry + - deploy-prod # deploy.sh (Blue-Green) + - notify # LINE Notification +``` + +### Environment Variables ที่ CI/CD ใช้ + +```bash +# Gitea Secrets (ตั้งค่าใน Gitea Settings → Secrets) +REGISTRY_URL=registry.internal.example.com +REGISTRY_USERNAME=ci-bot +REGISTRY_PASSWORD= +QNAP_SSH_KEY= +QNAP_HOST=192.168.1.x +LINE_NOTIFY_TOKEN= +STAGING_URL=https://staging.lcbp3-dms.internal +``` + +--- + +## 10. 🔐 Release Security Requirements + +### Pre-Release Security Checklist + +``` +✅ npm audit: 0 Critical, 0 High vulnerabilities +✅ ไม่มี Secret/Credential hardcoded ใน Code (Gitleaks) +✅ .env ไม่ถูก Commit (gitignore check) +✅ JWT_SECRET และ DB_PASSWORD ไม่ใช่ Default Values +✅ Docker Image ไม่มี Root User (USER node) +✅ Helmet.js Security Headers ยังทำงาน (Smoke Test) +✅ Rate Limiting ยังทำงาน (Login endpoint test) +``` + +### ข้อห้ามเด็ดขาด (Forbidden in Release) + +``` +❌ ห้าม Deploy โดยไม่มี Code Review (อย่างน้อย 1 คน) +❌ ห้าม Merge feature/* ตรงไปยัง main (ต้องผ่าน develop + release/*) +❌ ห้าม Deploy ช่วง 08:00–18:00 วันทำงาน (ยกเว้น Hotfix P0) +❌ ห้าม Skip Quality Gate (Unit Test, Security Scan) สำหรับ Sprint Release +❌ ห้าม Deploy โดยไม่มี Rollback Plan ที่ทดสอบแล้ว +❌ ห้าม Apply Schema Change บน Production โดยไม่มี Backup +``` + +--- + +## 11. 📁 Release Artifacts + +### สิ่งที่ต้องสร้างทุก Release + +| Artifact | Location | Owner | Retention | +|----------|---------|-------|----------| +| Release Notes | `specs/99-archives/releases/v{X.Y.Z}.md` | PO | ตลอดไป | +| Docker Images | Internal Registry (Gitea) | DevOps | ล่าสุด 5 Versions | +| DB Backup (Pre-deploy) | QNAP `/volume1/lcbp3/shared/backups/` | DevOps | 30 วัน | +| Delta SQL File | `specs/03-Data-and-Storage/deltas/` | Dev | ตลอดไป (Git) | +| CHANGELOG.md Update | Root of Repo | Dev | ตลอดไป | +| Deploy Log | `/volume1/lcbp3/shared/logs/deploy.log` | DevOps (Auto) | 90 วัน | + +--- + +## 12. 📋 Release Checklist + +### Sprint Release Checklist + +**T-3 วัน (Quality Gate)** +- [ ] All Unit Tests pass ≥ 80% coverage +- [ ] TypeScript 0 Errors +- [ ] ESLint 0 Errors +- [ ] `npm audit` 0 Critical/High +- [ ] Docker Build Success +- [ ] CHANGELOG.md Updated +- [ ] Delta SQL file ready (ถ้ามี Schema Change) + +**T-1 วัน (Staging + Approval)** +- [ ] Deploy to Staging สำเร็จ +- [ ] Smoke Test on Staging ผ่าน +- [ ] Schema Migration Test on Staging ผ่าน (ถ้ามี) +- [ ] PO Review Complete +- [ ] PO Sign-off: "___ วันที่ ___" +- [ ] Org Admin Notification ส่งแล้ว (LINE) + +**Release Day** +- [ ] DB Backup created + verified +- [ ] Schema Delta Applied (ถ้ามี) — แจ้ง Admin ทำ Manual +- [ ] `./deploy.sh` รัน (Blue-Green) +- [ ] Health Check ✅ All containers +- [ ] Smoke Test ✅ Login + Core Feature +- [ ] Grafana: Error Rate < 1%, P90 < 500ms (15 นาที) +- [ ] `git tag vX.Y.Z` + Push +- [ ] Release Notes Published +- [ ] Notify Org Admins: "Release vX.Y.Z เสร็จสมบูรณ์" + +--- + +## 📝 Document Control + +- **Version:** 1.0.0 | **Status:** DRAFT +- **Created:** 2026-03-11 | **Owner:** Nattanin Peancharoen +- **Next Review:** Pre Sprint 1 (T-2 สัปดาห์ก่อน Go-Live) +- **Classification:** Internal — Developer + DevOps + PO Only diff --git a/specs/04-Infrastructure-OPS/README.md b/specs/04-Infrastructure-OPS/README.md index 4481039..d7ecf4b 100644 --- a/specs/04-Infrastructure-OPS/README.md +++ b/specs/04-Infrastructure-OPS/README.md @@ -25,6 +25,7 @@ It consolidates what was previously split across multiple operations and specifi | **[04-05-maintenance-procedures.md](./04-05-maintenance-procedures.md)** | Routine Care | Log rotation, dependency updates, scheduled DB optimizations | | **[04-06-security-operations.md](./04-06-security-operations.md)** | Hardening & Audit | User access review, SSL renewals, vulnerability scanning, **Appendix A: SSH Setup**, **Appendix B: Secrets Management** | | **[04-07-incident-response.md](./04-07-incident-response.md)** | Escalation | P0-P3 classifications, incident commander roles, Post-Incident Review | +| **[🚀 04-08-release-management-policy.md](./04-08-release-management-policy.md)** | Release Policy | SemVer, Git Flow, 5 Release Gates, Hotfix Process, Rollback Policy, CI/CD Pipeline | ### 🐳 Live Docker Compose Files (QNAP) diff --git a/specs/06-Decision-Records/Patch 1.8.1.md b/specs/06-Decision-Records/Patch 1.8.1.md index c874072..91c9625 100644 --- a/specs/06-Decision-Records/Patch 1.8.1.md +++ b/specs/06-Decision-Records/Patch 1.8.1.md @@ -26,20 +26,33 @@ Spec 1.8.1 แก้ความไม่สอดคล้องระหว่ ### 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 | +| 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) | -**Constraint:** +**Constraints:** -* Ollama MUST NOT run on QNAP +* Ollama MUST NOT run on QNAP (production server) * AI containers MUST NOT access production DB directly +* n8n calls Ollama via internal VLAN HTTP only --- @@ -173,7 +186,7 @@ Production DMS must remain authoritative. Ollama must: -* Run on ASUSTOR only +* Run on **Admin Desktop only** (NOT on QNAP) * Have NO DB credentials * Have NO write access to uploads * Access only `/staging_ai` diff --git a/specs/99-archives/prompt.md b/specs/99-archives/prompt.md new file mode 100644 index 0000000..227c0ad --- /dev/null +++ b/specs/99-archives/prompt.md @@ -0,0 +1,927 @@ +# 🚀 Ultimate Prompt Library for Software Engineering +AI Prompt Library สำหรับการพัฒนา Software แบบครบวงจร ตั้งแต่การวางแผนโปรเจกต์ การออกแบบ UX/UI การพัฒนาระบบ ไปจนถึงการ Deploy และ Optimize ใน Production +[ชื่อโปรเจกต์] = LCBP3-DMS (Laem Chabang Port Phase 3 - Document Management System) +--- + +## 🧭 1. Strategy & Product Planning + +### 🟡 Product Owner 🟢 Basic +วิเคราะห์เป้าหมายธุรกิจและกำหนด MVP + +**Prompt** + +ให้คุณรับบทเป็น Product Owner สำหรับโปรเจกต์ **[ชื่อโปรเจกต์]** + +ช่วยวิเคราะห์: +- เป้าหมายธุรกิจ +- กลุ่มผู้ใช้งานหลัก +- ปัญหาที่ผู้ใช้เจอ +- โอกาสทางตลาด + +Output format (ตอบเป็น Markdown): +1. System goals +2. Target users +3. User pain points +4. Feature list (แบ่ง Must-have / Nice-to-have / Out of scope) +5. MVP scope +6. Future roadmap (3 phases) +7. Success metrics (KPIs) + +--- + +### 🔵 Business Analyst 🟡 Intermediate +แตก Requirement อย่างละเอียด + +**Prompt** + +ให้คุณรับบทเป็น Business Analyst +ช่วยวิเคราะห์ requirement ของระบบ **[ชื่อระบบ]** + +Context จาก Product Owner: +[วาง Output จาก Product Owner Prompt ที่นี่] + +วิเคราะห์: +- Functional requirements +- Non-functional requirements (Performance / Security / Scalability) +- User roles และ permission matrix +- Use cases (Happy path + Alternative path) +- Business rules +- Edge cases +- Assumptions / Open questions + +Constraints: +- ตอบเป็น Markdown +- ใช้ภาษาที่ Developer เข้าใจได้ทันที +- ระบุ priority (P0/P1/P2) ทุก requirement + +Output: +- Feature list พร้อม priority +- MVP scope +- Roadmap +- Requirement document (Markdown) + +--- + +### ⚪ AI Project Manager 🟡 Intermediate + +วางแผนการพัฒนาเป็น Phase + +**Prompt** +ให้คุณรับบทเป็น AI Project Manager + +Context: +- โปรเจกต์: [ชื่อโปรเจกต์] +- ทีม: [Frontend / Backend / DevOps / QA จำนวนคนแต่ละฝ่าย] +- Timeline รวม: [กี่สัปดาห์/เดือน] +- Methodology: [Agile / Scrum / Kanban] + +Requirements จาก Business Analyst: +[วาง Output จาก BA Prompt ที่นี่] + +Output (ตอบเป็น Markdown table): + +| Phase | Description | Deliverables | Dependency | Duration | Definition of Done | + +พร้อมสร้าง: +- Risk register (Top 5 risks + mitigation) +- Sprint breakdown (ถ้าใช้ Scrum) +- Milestone checklist +--- + +## 🎨 2. UX / UI & Information Architecture + +### 🟣 UX Researcher 🟡 Intermediate + +วิเคราะห์ประสบการณ์ผู้ใช้ + +**Prompt** + +ให้คุณรับบทเป็น UX Researcher +วิเคราะห์ UX สำหรับ [ประเภทเว็บ/แอป] + +กลุ่มเป้าหมาย: +[ระบุผู้ใช้: อายุ / อาชีพ / tech-savviness / device ที่ใช้] + +Context โปรเจกต์: +[วาง Product Owner Output ที่นี่] + +Output (ตอบเป็น Markdown): +- User personas (3 แบบ พร้อม quote จำลอง) +- User journey map (ตาม persona หลัก) +- Pain points แยกตาม journey stage +- UX opportunities พร้อม priority +- Accessibility considerations (WCAG 2.1) +--- + +### 🟢 Information Architect 🟢 Basic + +ออกแบบโครงสร้างเว็บไซต์ + +**Prompt** +ให้คุณรับบทเป็น Information Architect + +ช่วยออกแบบ Sitemap สำหรับเว็บ [ประเภทเว็บ] + +User personas: +[วาง UX Researcher Output ที่นี่] + +Output (ตอบเป็น Markdown): +- Primary navigation (max 7 items) +- Secondary navigation +- Sitemap (แบบ tree structure) +- Content grouping พร้อมเหตุผล +- URL structure recommendation +- Breadcrumb strategy + +--- + +### 🔴 UX/UI Designer 🟡 Intermediate +ออกแบบหน้าเว็บ + +**Prompt** + +ให้คุณรับบทเป็น UX/UI Designer + +ออกแบบหน้า [ชื่อหน้า] + +เป้าหมาย: [เช่น เพิ่ม conversion / ลด bounce rate] +Platform: [Web / Mobile / Both] +Brand tone: [เช่น Professional / Friendly / Minimal] + +Sitemap context: +[วาง IA Output ที่นี่] + +Output (ตอบเป็น Markdown): +- Page structure และ section order พร้อมเหตุผล +- UI components list (แต่ละ section) +- Color palette (Hex code) + Typography guideline +- Wireframe แบบ text layout (ASCII หรือ structured text) +- CTA strategy +- Mobile-first considerations +- Accessibility notes (contrast ratio / touch target size) + +--- + +## 🏛️ 3. System Architecture + +### 🛠️ Solution Architect 🔴 Advanced + +ออกแบบ Architecture ระดับสูง + +**Prompt** + +ให้คุณรับบทเป็น Solution Architect ออกแบบ Architecture สำหรับระบบ **[ประเภทระบบ]** + +Context: +[วาง Product Owner Output ที่นี่] + +Constraints: + +รองรับผู้ใช้ [จำนวน] concurrent users + +Team skill: [Tech stack ที่ทีมถนัด] +Requirements: +- รองรับผู้ใช้ [จำนวน] concurrent users +- Expected growth: [x เท่าใน y ปี] +- Budget: [Cloud budget/month] +- Compliance: [PDPA / GDPR / HIPAA ถ้ามี] +- Team skill: [Tech stack ที่ทีมถนัด] + +Thought Process Requirement: +ก่อนสรุปผล ให้คุณทำ Trade-off Analysis โดยเปรียบเทียบแนวทางที่เป็นไปได้ 2-3 แนวทาง (เช่น Monolith vs Microservices หรือ RDBMS vs NoSQL) วิเคราะห์ข้อดี-ข้อเสียในมุมของ Latency, Cost และ Maintenance พร้อมระบุเหตุผลที่คุณเลือกแนวทางสุดท้าย + +Output (ตอบเป็น Markdown): +- System architecture overview +- Component diagram (text-based) +- Decision Log: เหตุผลเบื้องหลังการเลือก Tech stack +- Data flow diagram +- Recommended tech stack พร้อมเหตุผล +- Trade-offs ของ architecture ที่เลือก +- Estimated infrastructure cost +- Scaling strategy (Horizontal / Vertical) + +--- + +### 🔗 Integration Architect 🔴 Advanced + +ออกแบบการเชื่อมต่อระบบ + +**Prompt** + +ให้คุณรับบทเป็น Integration Architect + +ออกแบบ Integration สำหรับระบบ [ชื่อระบบ] + +ระบบที่ต้องเชื่อมต่อ: +- [ระบบ A: เช่น Payment Gateway] +- [ระบบ B: เช่น CRM] +- [ระบบ C: เช่น ERP] + +Solution Architecture: +[วาง Architect Output ที่นี่] + +Output (ตอบเป็น Markdown): +- Integration pattern ที่เลือก (Sync / Async / Event-driven) พร้อมเหตุผล +- API strategy (REST / GraphQL / gRPC) +- Webhook design +- Message queue strategy (ถ้าใช้) +- Retry strategy และ circuit breaker pattern +- Error handling และ dead letter queue +- Data consistency strategy + +--- + +### 🌐 API Architect 🟡 Intermediate + +ออกแบบ API + +**Prompt** + +ให้คุณรับบทเป็น API Architect + +ออกแบบ REST API สำหรับ [ระบบ] + +Integration context: +[วาง Integration Architect Output ที่นี่] + +Output (ตอบเป็น Markdown): +- Endpoint list (Method / Path / Description / Auth required) +- Request/Response schema (JSON format พร้อม example) +- Authentication strategy (JWT / OAuth2 / API Key) +- Authorization model (RBAC / ABAC) +- Rate limiting strategy +- Versioning strategy (URI / Header based) +- Error response standard (RFC 7807) +- Pagination strategy + +--- + +## 💻 4. Development + +### 🚀 Senior Full Stack Developer 🟡 Intermediate + +ออกแบบและพัฒนาระบบพร้อม Error Handling + +**Prompt** + +ให้คุณรับบทเป็น Senior Full Stack Developerสร้างระบบ [ชื่อระบบ] + +Tech stack: [ระบุ เช่น Next.js / Node.js / PostgreSQL / Redis] +Architecture context: [วาง Solution Architect Output] + +Constraints: +- ใช้ TypeScript เท่านั้น +- ต้องมี error handling ทุก layer +- Reasoning: อธิบายเหตุผลในการวาง Folder Structure และการเลือก Library เสริม +- ต้องมี unit test coverage > 80% +- ห้าม hardcode credentials ทุกกรณี + +Output (ตอบเป็น Markdown): +- System architecture +- Folder structure (monorepo / polyrepo) +- Database schema & Migration guide +- Development steps (เรียงตาม dependency) +- API design overview +- Development steps (เรียงตาม dependency) +- Environment variables list +- Getting started guide +--- + +### ♻️ Refactoring & Modernization 🔴 Advanced (New!) +ปรับปรุงคุณภาพโค้ดเก่าให้เป็น Modern Code + +**Prompt** +ให้คุณรับบทเป็น Senior Refactoring Engineer + +Task: ปรับปรุงคุณภาพโค้ด (Refactor) โดยยังคง Logic เดิม (Functional Equivalence) + +Context: +โค้ดต้นฉบับ: [วางโค้ด] + +เป้าหมาย: [เช่น เปลี่ยนจาก JS เป็น TS / ลด Complexity / เพิ่ม Performance] + +Output: +- Code Smells Identification: ระบุจุดที่เป็นปัญหาและ Technical Debt +- Refactoring Strategy: อธิบายขั้นตอนการแก้ไขทีละ Step +- Refactored Code: โค้ดเวอร์ชันใหม่ที่ Clean, Readable และมี Type Safety +- Verification Plan: วิธีการ Test เพื่อยืนยันว่าระบบยังทำงานได้ถูกต้อง 100% +--- + +### 🔹 Frontend Developer 🟡 Intermediate + +**Prompt** + +ให้คุณรับบทเป็น Senior Frontend Developer + +สร้างหน้า [ชื่อหน้า] โดยใช้ [React / Vue / Next.js] + Tailwind CSS + +Design context: +[วาง UX/UI Designer Output ที่นี่] + +API context: +[วาง API Architect Output ที่นี่] + +Constraints: +- Responsive: mobile-first (breakpoint: sm/md/lg/xl) +- Accessibility: WCAG 2.1 AA (aria-label, keyboard nav, color contrast) +- State management: [Zustand / Redux / Context API] +- ต้องมี loading skeleton ทุก async call +- ต้องมี error boundary และ fallback UI +- ห้าม inline style ใช้ Tailwind utility class เท่านั้น +- ใช้ TypeScript พร้อม strict mode + +Output (ตอบเป็น Markdown + Code): +- Component tree diagram +- Props interface (TypeScript) +- โค้ดทุก component พร้อม comment อธิบาย logic +- Custom hooks ที่ใช้ +- Unit test เบื้องต้น (React Testing Library) +--- + +### 🔸 Backend Developer 🟡 Intermediate + +**Prompt** + +ให้คุณรับบทเป็น Senior Backend Developer + +ออกแบบ Backend สำหรับระบบ [ชื่อระบบ] + +Tech: [Node.js+Express / FastAPI / Laravel] +Database: [PostgreSQL / MySQL / MongoDB] + +API & Schema context: +[วาง API Architect + Database Designer Output ที่นี่] + +Constraints: +- ใช้ TypeScript / typed language +- Input validation ทุก endpoint (Zod / Joi / Pydantic) +- Error handling แบบ centralized +- Logging ทุก request (structured JSON log) +- ห้าม SQL injection (ใช้ ORM หรือ parameterized query) + +Output (ตอบเป็น Markdown + Code): +- API design (Method / Path / Auth / Validation rules) +- Middleware list +- Auth system (JWT flow diagram) +- Database schema (SQL หรือ ORM model) +- โค้ด service layer พร้อม error handling +--- + +### 🔍 Code Reviewer 🟡 Intermediate +ตรวจสอบคุณภาพโค้ด +**Prompt** +ให้คุณรับบทเป็น Senior Code Reviewer + +Review โค้ดด้านล่างนี้อย่างละเอียด: + +[วางโค้ดที่ต้องการ review] + +วิเคราะห์ตาม: +- Clean Code (naming / function size / complexity) +- SOLID Principles +- Security vulnerabilities (OWASP Top 10) +- Performance issues +- Error handling +- Test coverage gaps + +Output format (ตอบเป็น Markdown table): + +| # | Issue | Severity (Critical/High/Medium/Low) | Location | Suggested Fix | + +พร้อม: +- Overall score (1-10) +- Top 3 สิ่งที่ต้องแก้ทันที +- Refactored code snippet (เฉพาะส่วนที่มีปัญหาหนัก) +--- + +## 🧠 5. AI & Automation + +### 🤖 AI Solution Architect 🔴 Advanced + +ออกแบบการใช้ AI ในระบบ + +**Prompt** + +ให้คุณรับบทเป็น AI Solution Architect + +ออกแบบ AI integration สำหรับระบบ [ชื่อระบบ] + +Business context: +[วาง Product Owner / BA Output ที่นี่] + +Budget: [$/month สำหรับ AI API] +Latency requirement: [เช่น < 2 วินาที] +Data sensitivity: [มี PII หรือไม่] + +Output (ตอบเป็น Markdown): +- AI use cases พร้อม ROI estimation +- Model selection (OpenAI / Claude / Gemini / Open-source) พร้อมเหตุผล +- Build vs Buy analysis +- Data pipeline design +- Inference architecture (Real-time / Batch) +- Prompt strategy overview +- Cost estimation (token/request/month) +- Fallback strategy เมื่อ AI ล้มเหลว +- Privacy & compliance considerations + +--- + +### 🧩 Prompt Engineer 🟡 Intermediate + +ออกแบบ Prompt สำหรับ LLM + +**Prompt** + +ให้คุณรับบทเป็น Prompt Engineer + +ช่วยออกแบบ Prompt สำหรับ AI ที่ใช้กับ [task] + +Context: +[วาง AI Solution Architect Output หรือ Business Context ที่นี่] + +Model: [เช่น GPT-4o / Claude 3.5 / Gemini 2.0] + +Output (ตอบเป็น Markdown): +- Prompt template (พร้อม placeholder) +- Few-shot examples (3-5 ตัวอย่าง) +- System instruction +- Input/Output format specification +- Guardrails และ safety instructions +- Testing strategy สำหรับ prompt +- Version history และ optimization notes +--- + +##🧪 RAG System Designer 🔴 Advanced +ออกแบบระบบ Retrieval-Augmented Generation +**Prompt** +ให้คุณรับบทเป็น RAG System Designer + +ออกแบบ RAG pipeline สำหรับ [use case เช่น Document QA / Customer Support Bot] + +Data sources: +- [เช่น PDF documents / Database / Web pages] +- ปริมาณ: [จำนวน documents / ขนาด] +- Update frequency: [Real-time / Daily / Static] + +Requirements: +- ภาษา: [Thai / English / Both] +- Latency: [< x วินาที] +- Accuracy requirement: [เช่น ห้าม hallucinate fact สำคัญ] + +Output (ตอบเป็น Markdown): +- RAG architecture diagram (text-based) +- Chunking strategy (size / overlap / method) +- Embedding model selection พร้อมเหตุผล +- Vector database selection (Pinecone / Weaviate / pgvector) +- Retrieval strategy (Semantic / Keyword / Hybrid) +- Re-ranking approach +- Prompt template สำหรับ generation +- Evaluation metrics (Faithfulness / Relevance / Groundedness) +- Cost estimation +--- + +### 🎯 AI Evaluation Engineer 🔴 Advanced +วัดและปรับปรุงคุณภาพ AI +**Prompt** +ให้คุณรับบทเป็น AI Evaluation Engineer + +ออกแบบ Evaluation framework สำหรับ AI feature [ชื่อ feature] + +AI ทำหน้าที่: [อธิบาย task] +Model ที่ใช้: [GPT-4 / Claude / etc.] +Output format: [Text / JSON / Classification] + +Output (ตอบเป็น Markdown): +- Evaluation metrics ที่เหมาะสม (Accuracy / F1 / BLEU / custom) +- Test dataset design (จำนวน / distribution / edge cases) +- Hallucination detection strategy +- Bias testing checklist +- A/B testing plan (เปรียบเทียบ model หรือ prompt) +- Monitoring dashboard metrics +- Threshold สำหรับ alert เมื่อ quality ตก +- Human-in-the-loop strategy +--- + +### 🔄 Automation Engineer 🟡 Intermediate +ออกแบบ Workflow Automation +**Prompt** +ให้คุณรับบทเป็น Automation Engineer + +ออกแบบ Automation workflow สำหรับระบบ [ชื่อระบบ] + +Tools: [n8n / Node-RED / Zapier / Make] +Trigger events: [อธิบาย] +Integration context: [วาง Integration Architect Output] + +Output (ตอบเป็น Markdown): +- Workflow diagram (text-based step flow) +- Trigger events และ conditions +- Data transformation logic +- Error handling และ retry strategy +- Dead letter queue strategy +- Monitoring และ alerting +- Estimated execution time per workflow +--- + +### 🧪 RAG System Designer 🔴 Advanced +ออกแบบระบบ Retrieval-Augmented Generation อย่างแม่นยำ + +**Prompt** +ให้คุณรับบทเป็น RAG System Designer ออกแบบ RAG pipeline สำหรับ [use case] + +Data sources: [ระบุแหล่งข้อมูล] + +Zero-Hallucination Guardrails: +- ออกแบบกลไกการตรวจสอบ Source Citation +- กำหนดเกณฑ์ Confidence Score สำหรับคำตอบ + +Output: +- Chunking strategy (size / overlap) +- Embedding & Vector DB selection +- Retrieval strategy (Semantic / Hybrid / Re-ranking) +- Hallucination Mitigation Plan: วิธีการลดการมโนของ AI +--- + +## 🗄️ 6. Data & Database + +### 🗃️ Database Designer 🟡 Intermediate + +ออกแบบ Database + +**Prompt** +ให้คุณรับบทเป็น Database Designer + +ออกแบบฐานข้อมูลสำหรับระบบ [ชื่อระบบ] + +Requirements: +- Database type: [Relational / NoSQL / Both] +- Expected data volume: [rows/documents] +- Query patterns: [อธิบาย query ที่ใช้บ่อย] +- Read/Write ratio: [เช่น 80/20] + +Business requirements: +[วาง BA Output ที่นี่] + +Output (ตอบเป็น Markdown): +- Entity Relationship Diagram (text-based) +- Tables / Collections พร้อม fields ครบ +- Primary key / Foreign key / Indexes +- Relationships (1:1 / 1:N / M:N) +- Normalization strategy (1NF-3NF หรือ denormalize เมื่อไหร่) +- Example SQL schema (CREATE TABLE statements) +- Migration strategy +- Soft delete vs Hard delete strategy + +--- + +### 📊 Data Architect 🔴 Advanced + +ออกแบบระบบข้อมูล + +**Prompt** +ให้คุณรับบทเป็น Data Architect + +ออกแบบ Data Architecture สำหรับระบบ [ชื่อระบบ] + +Business goals: +[วาง Product Owner Output ที่นี่] + +Data sources: [ระบุทุกแหล่ง] +Analytics needs: [Real-time / Batch / Both] +Team: [Data Engineer / Analyst มีหรือไม่] + +Output (ตอบเป็น Markdown): +- Data architecture diagram (Lambda / Kappa / Data Lakehouse) +- Data pipeline design +- Data warehouse / Data lake design +- ETL/ELT process +- Analytics schema (Star / Snowflake schema) +- Data governance basics (ownership / lineage) +- Tool recommendations พร้อมเหตุผล +- Cost estimation +--- + +## ☁️ 7. DevOps & Infrastructure + +### 🐳 DevOps Engineer 🟡 Intermediate + +วางระบบ Deployment + +**Prompt** +ให้คุณรับบทเป็น Senior DevOps Engineer + +ออกแบบ Deployment สำหรับ [ชื่อระบบ] + +Cloud provider: [AWS / GCP / Azure / On-premise] +Environment: [Dev / Staging / Production] +Architecture context: [วาง Solution Architect Output] +Team size: [จำนวน developer] + +Output (ตอบเป็น Markdown + Config): +- Infrastructure as Code (Terraform / Pulumi outline) +- Docker setup (Dockerfile + docker-compose.yml) +- CI/CD pipeline (GitHub Actions / GitLab CI) + - Stages: Lint → Test → Build → Deploy + - Branch strategy (main / develop / feature) +- Nginx / Reverse proxy config +- Environment variable management (Vault / AWS Secrets Manager) +- Backup strategy (frequency / retention / restore procedure) +- Zero-downtime deployment strategy +--- + +### ⚙️ Site Reliability Engineer 🔴 Advanced + +ตรวจสอบ Production readiness + +**Prompt** +ให้คุณรับบทเป็น SRE (Site Reliability Engineer) + +ประเมิน Production readiness ของระบบ [ชื่อระบบ] + +Architecture context: +[วาง Solution Architect + DevOps Output ที่นี่] + +SLA requirement: [เช่น 99.9% uptime] + +วิเคราะห์: +- Scalability (Load test scenarios) +- Single points of failure +- Monitoring & Observability (Metrics / Logs / Traces) +- Alerting strategy (P1/P2/P3 severity) +- Incident response runbook +- Disaster recovery plan (RTO / RPO targets) +- Chaos engineering recommendations +- On-call rotation suggestion +Output: Production Readiness Checklist (ตอบเป็น Markdown checkbox) +--- + +## 🛡️ 8. Security & QA + +### 🔍 QA Engineer 🟡 Intermediate + +สร้าง Test cases + +**Prompt** + +ให้คุณรับบทเป็น Senior QA Engineer + +สร้าง Test plan สำหรับฟีเจอร์ [ชื่อฟีเจอร์] + +Requirements: +[วาง BA Output ที่นี่] + +Output (ตอบเป็น Markdown): + +Test Cases Table: +| # | Test Case | Scenario | Steps | Expected Result | Priority | + +พร้อม: +- Boundary value test cases +- Negative test cases +- Edge cases +- API test cases (ถ้ามี) +- Performance test scenarios +- Test data requirements +- Regression test checklist + +--- + +### 🔐 Security Engineer 🔴 Advanced + +ตรวจสอบความปลอดภัย + +**Prompt** +ให้คุณรับบทเป็น Security Engineer + +วิเคราะห์ความเสี่ยงของระบบ [ชื่อระบบ] + +Architecture context: +[วาง Solution Architect Output ที่นี่] + +Compliance requirement: [PDPA / GDPR / PCI-DSS ถ้ามี] + +ตรวจสอบตาม: +- OWASP Top 10 (2021) +- Authentication & Authorization flaws +- Input validation & Injection attacks +- Data encryption (at rest / in transit) +- API security +- Dependency vulnerabilities +- Secret management +- Logging & Audit trail + +Output (ตอบเป็น Markdown): + +| Risk | OWASP Category | Severity | Likelihood | Mitigation | + +พร้อม: +- Security checklist ก่อน go-live +- Penetration testing scope +- Security monitoring recommendations +--- + +## 🚨 9. Incident Response + +### 🆘 Incident Commander 🔴 Advanced + +จัดการ Incident และทำ Post-mortem + +**Prompt** +ให้คุณรับบทเป็น Incident Commander + +จัดการ Incident สำหรับระบบ [ชื่อระบบ] + +Incident description: +- อาการ: [อธิบายอาการที่พบ] +- เวลาเริ่มต้น: [timestamp] +- Impact: [กี่ user ได้รับผลกระทบ] +- Severity: [P1/P2/P3] + +System context: +[วาง Architecture + Monitoring context] + +Output (ตอบเป็น Markdown): + +**Immediate Actions (0-15 นาที):** +- [ ] ... + +**Investigation Steps:** +- Root cause analysis checklist +- Log queries ที่ควร run +- Metrics ที่ควรดู + +**Post-mortem Template:** +- Timeline of events +- Root cause +- Contributing factors +- Impact summary +- Action items (What / Who / When) +- Prevention measures +--- + + + +## 📈 10. Optimization +### ⚡ Performance Engineer 🟡 Intermediate +เพิ่มประสิทธิภาพระบบ +**Prompt** +ให้คุณรับบทเป็น Performance Engineer + +วิเคราะห์และปรับปรุง Performance ของระบบ [ชื่อระบบ] + +Current metrics: +- Response time: [ms] +- Throughput: [req/s] +- Error rate: [%] +- Infrastructure: [specs] + +Architecture context: +[วาง Solution Architect Output] + +Output (ตอบเป็น Markdown): +- Bottleneck analysis (Frontend / Backend / Database / Network) +- Caching strategy (Redis / CDN / Browser cache) +- Database query optimization +- Asset optimization (Bundle size / Image / Lazy loading) +- Horizontal vs Vertical scaling recommendation +- Load testing plan (k6 / JMeter scenarios) +- Performance budget targets +- Quick wins vs Long-term improvements +--- + +### 💰 Cloud Cost Optimizer 🟡 Intermediate +ลด Cloud Cost +**Prompt** +ให้คุณรับบทเป็น Cloud Cost Optimization Specialist + +วิเคราะห์และลด Cloud cost สำหรับระบบ [ชื่อระบบ] + +Current setup: +- Cloud provider: [AWS / GCP / Azure] +- Current monthly cost: [$x] +- Services ที่ใช้: [List] +- Traffic pattern: [เช่น Peak hours / 24/7] + +Output (ตอบเป็น Markdown): +- Cost breakdown analysis (service by service) +- Right-sizing recommendations +- Reserved vs On-demand vs Spot instance strategy +- Auto-scaling configuration +- Unused resource identification checklist +- Data transfer cost optimization +- Storage tier strategy (Hot / Warm / Cold) +- Estimated savings หลังปรับปรุง +- Implementation priority (Quick wins ก่อน) +--- + +### 🔎 SEO Specialist 🟢 Basic + +วางกลยุทธ์ SEO + +**Prompt** +ให้คุณรับบทเป็น SEO Specialist + +สร้าง SEO strategy สำหรับเว็บ [ประเภทเว็บ] + +Business context: +[วาง Product Owner Output ที่นี่] + +Target audience: [ระบุ] +Primary market: [ประเทศ / ภาษา] +Competitors: [ระบุถ้ามี] + +Output (ตอบเป็น Markdown): +- Keyword clusters (Primary / Secondary / Long-tail) +- Content structure recommendations +- Technical SEO checklist + - Meta tags template + - Heading hierarchy strategy + - Schema markup recommendations + - Core Web Vitals targets +- Internal linking strategy +- Content calendar outline (3 เดือนแรก) +--- + +## 📖 11. Documentation +### 📝 Technical Writer 🟢 Basic +สร้างเอกสารที่อ่านง่ายและใช้งานได้จริง + +**Prompt** +ให้คุณรับบทเป็น Technical Writer เขียนเอกสารสำหรับโปรเจกต์ [ชื่อโปรเจกต์] + +Context ทั้งหมด: +[วาง output ที่เกี่ยวข้องทั้งหมด] + +Target audience: [Developer / End User / Both] +Format: [Markdown / Confluence / Notion] + +Output (ตอบเป็น Markdown): +- Project overview : อธิบายคุณค่าของโปรเจกต์ใน 1 ย่อหน้า +- Architecture summary +- Prerequisites +- Installation Guide: Step-by-step พร้อมโค้ดประกอบที่มือใหม่ทำตามได้จริง +- API Reference: รายละเอียด Endpoints และ Example Request/Response +- Edge Case Documentation: ระบุข้อจำกัดของระบบที่ควรรู้- Environment variables reference (ตาราง: Variable / Description / Required / Default) +- API summary (endpoints หลัก) +- Troubleshooting Guide: รวบรวม Top 5 common issues และวิธีแก้ไข +- Contributing guide +- Changelog template +--- + +## ⭐ Master Prompt (AI Dev Team) + +ใช้ AI เป็นทั้งทีม Dev + +**Prompt** +ให้คุณรับบทเป็นทีม Software Development (PO, Architect, Developer, SRE, Security) ทำงานแบบ Chain of Thought โดยแต่ละ Role จะต้องส่งต่อ Decision Log (เหตุผลการตัดสินใจ) ให้ Role ถัดไป +ประกอบด้วย: +- Product Owner (วิเคราะห์ Business) +- Solution Architect (ออกแบบระบบ) +- Senior Developer (พัฒนา Frontend + Backend) +- QA Engineer (วางแผน Testing) +- DevOps Engineer (วางแผน Deployment) +- Security Engineer (ตรวจสอบความปลอดภัย) + +**โปรเจกต์:** [ชื่อระบบ] + +**Context:** +- อุตสาหกรรม: [ระบุ] +- ขนาดทีมจริง: [จำนวนคน] +- Timeline: [ระบุ] +- Tech stack ที่ต้องการ: [ระบุหรือให้ AI แนะนำ] +- Budget constraint: [มี/ไม่มี] + +**กระบวนการทำงาน:** +แต่ละ Role จะทำงานตามลำดับ และส่งต่อ Output ให้ Role ถัดไปเป็น Input +ระบุชัดเจนว่าแต่ละ Role กำลัง "รับ" อะไรและ "ส่งต่อ" อะไร + +**Output ที่ต้องการ (ตอบเป็น Markdown พร้อม section header ชัดเจน):** +- ทุก Role ต้องวิเคราะห์ Trade-offs ก่อนสรุปผล +- ห้าม Hallucinate หากข้อมูลไม่พอให้ถามกลับ +- เน้นความปลอดภัย (Security-first) และการบำรุงรักษา (Maintainability) +### 1. [Product Owner] System Overview +- Goals / Users / Pain points / MVP scope + +### 2. [Architect] Architecture Design +- Tech stack / Component diagram / Data flow + +### 3. [Architect] Database Design +- Schema / Relationships / Indexes + +### 4. [Architect] API Design +- Endpoints / Auth / Error handling + +### 5. [Developer] Development Roadmap +- Phase / Sprint breakdown / Definition of Done + +### 6. [QA] Testing Plan +- Test strategy / Test cases สำคัญ / Automation plan + +### 7. [DevOps] Deployment Plan +- CI/CD / Infrastructure / Monitoring + +### 8. [Security] Security Review +- Top risks / Mitigation / Pre-launch checklist +``` + +--- diff --git a/specs/README.md b/specs/README.md index 7f9bec9..bd6321a 100644 --- a/specs/README.md +++ b/specs/README.md @@ -1,32 +1,43 @@ # 📚 LCBP3-DMS Specifications Directory -**Version:** 1.8.0 -**Last Updated:** 2026-02-24 +**Version:** 1.8.1 (Patch) +**Last Updated:** 2026-03-11 **Project:** LCBP3-DMS (Laem Chabang Port Phase 3 - Document Management System) +**Status:** ✅ UAT Ready — 10/10 Documentation Gaps Closed --- เอกสารในโฟลเดอร์ `specs/` ทั้งหมดเป็น **Source of Truth** หรือคัมภีร์หลักสำหรับการพัฒนาระบบ LCBP3-DMS ข้อมูลทั้งหมดถูกอัปเดตและปรับให้มีความสอดคล้องกัน (Modular) ตามมาตรฐานของโปรเจกต์ โครงสร้างด้านล่างคือสารบัญ (Index) ของเอกสารทั้งหมดในระบบ -## 📂 Directory Structure +--- + +## 📂 Directory Structure (v1.8.1) ```text specs/ -├── 00-Overview/ # ภาพรวมระบบ +├── 00-Overview/ # ภาพรวมระบบ + Product Vision + KPI + Training │ ├── 00-01-quick-start.md # คู่มือเริ่มต้นสำหรับนักพัฒนา │ ├── 00-02-glossary.md # คำศัพท์และตัวย่อในระบบ DMS +│ ├── 00-03-product-vision.md # ★ Gap 1: Product Vision, Strategic Pillars, Guardrails +│ ├── 00-04-stakeholder-signoff-and-risk.md # ★ Gap 5: Sign-off, Risk Register, Change Control +│ ├── 00-05-kpi-baseline.md # ★ Gap 6: 14 KPIs, SQL Queries, Grafana Specs +│ ├── 00-06-training-plan.md # ★ Gap 9: Training Curriculum per Role (4 Phases) │ └── README.md # แนะนำโครงสร้างธุรกิจและบริบทระบบ │ ├── 01-Requirements/ # Business Requirements & Modularity (Core) │ ├── 01-01-objectives.md # วัตถุประสงค์และการประเมินความสำเร็จของระบบ │ ├── 01-02-business-rules/ # กฎเหล็กของ DMS (ห้ามละเมิด) │ ├── 01-03-modules/ # สเปคของแต่ละระบบย่อย (Correspondences, Drawings, RFAs) +│ ├── 01-04-user-stories.md # ★ Gap 2: 27 User Stories, 8 Epics, MoSCoW Priority +│ ├── 01-05-acceptance-criteria.md # ★ Gap 3: UAT Acceptance Criteria, Sign-off Process +│ ├── 01-06-edge-cases-and-rules.md # ★ Gap 10: 37 Edge Cases, Business Logic Guards +│ ├── 01-07-ui-wireframes.md # ★ Gap 4: 26 Screens, Navigation Map, Design System │ └── README.md # สารบัญและรายละเอียดขอบเขตแต่ละ Module │ ├── 02-Architecture/ # สถาปัตยกรรมระบบ (System & Network) │ ├── 02-01-system-context.md # System overview │ ├── 02-02-software-architecture.md # โครงสร้างซอฟต์แวร์ฝั่ง Frontend & Backend -│ ├── 02-03-network-design.md # Network Segmentation (VLAN, VPN, QNAP/ASUSTOR) +│ ├── 02-03-network-design.md # Network Segmentation (VLAN, QNAP Production / ASUSTOR Monitoring) │ ├── 02-04-api-design.md # API specifications & Error Handling │ └── README.md # สรุปรูปแบบโครงสร้างของ Architecture │ @@ -34,7 +45,14 @@ specs/ │ ├── 03-01-data-dictionary.md # รวมและอธิบายทุก Field ในฐานข้อมูล │ ├── 03-02-db-indexing.md # Index recommendations, Soft-delete strategy │ ├── 03-03-file-storage.md # Secure File Handling (Outside webroot, QNAP Mounts) -│ ├── lcbp3-v1.7.0-schema.sql # Database SQL Schema +│ ├── 03-04-legacy-data-migration.md # Legacy Data Migration จาก Excel (ADR-017) +│ ├── 03-05-n8n-migration-setup-guide.md # n8n Workflow Setup + Ollama Integration +│ ├── 03-06-migration-business-scope.md # ★ Gap 7: Migration Scope, 3 Tiers, Go/No-Go Gates +│ ├── lcbp3-v1.8.0-schema-01-drop.sql # Schema: DROP statements +│ ├── lcbp3-v1.8.0-schema-02-tables.sql # Schema: CREATE TABLE (Source of Truth) +│ ├── lcbp3-v1.8.0-schema-03-views-indexes.sql # Schema: Views + Indexes +│ ├── lcbp3-v1.8.0-seed-basic.sql # Seed: Master Data +│ ├── lcbp3-v1.8.0-seed-permissions.sql # Seed: CASL Permission Matrix │ └── README.md # ภาพรวม Data Strategy │ ├── 04-Infrastructure-OPS/ # โครงสร้างพื้นฐานและการปฏิบัติการ @@ -45,7 +63,8 @@ specs/ │ ├── 04-04-deployment-guide.md# ขั้นตอน Deploy ด้วย Blue-Green (Gitea Actions) │ ├── 04-05-maintenance-procedures.md # วิธีดูแลรักษาระบบเบื้องต้น │ ├── 04-06-security-operations.md # การจัดการความปลอดภัยและใบรับรอง -│ ├── 04-07-incident-response.md # วิธีรับมือเหตุฉุกเฉิน +│ ├── 04-07-incident-response.md # วิธีรับมือเหตุฉุกเฉิน +│ ├── 04-08-release-management-policy.md # ★ Gap 8: SemVer, 5 Gates, Hotfix, Rollback │ └── README.md # Infrastructure & Operations Guide │ ├── 05-Engineering-Guidelines/ # มาตรฐานการพัฒนาและการเขียนโค้ด @@ -56,8 +75,9 @@ specs/ │ ├── 05-05-git-cheatsheet.md # การใช้ Git สำหรับทีมงาน │ └── README.md # ภาพรวมเป้าหมายงาน Engineering │ -├── 06-Decision-Records/ # Architecture Decision Records (เหตุผลการติดสินใจ) -│ ├── ADR-XXX... # ไฟล์อธิบายสถาปัตยกรรม (ADR) +├── 06-Decision-Records/ # Architecture Decision Records (17 + 1 Patch) +│ ├── ADR-001 to ADR-017... # ไฟล์อธิบายสถาปัตยกรรม (ADR) +│ ├── ADR-018-ai-boundary.md # ★ Patch 1.8.1: AI/Ollama Isolation Policy │ └── README.md # รายชื่อ ADR ทั้งหมดพร้อมสถานะและวันที่ │ └── 99-archives/ # ประวัติการทำงานและ Tasks เก่า @@ -66,12 +86,83 @@ specs/ └── obsolete-specs/ # เอกสารสเปคเวอร์ชันเก่า (V1.4.2 ฯลฯ) ``` +> **★** = เอกสารใหม่จาก v1.8.1 Patch (Product Owner Documentation — 10/10 Gaps Closed) + +--- + +## 📋 Document Index: 10 Documentation Gaps (v1.8.1) + +| Gap | เอกสาร | ไฟล์ | สถานะ | +|-----|--------|------|-------| +| **1** | Product Vision Statement | `00-Overview/00-03-product-vision.md` | ✅ | +| **2** | User Stories (27 Stories, 8 Epics) | `01-Requirements/01-04-user-stories.md` | ✅ | +| **3** | Acceptance Criteria & UAT Plan | `01-Requirements/01-05-acceptance-criteria.md` | ✅ | +| **4** | UI/UX Wireframes (26 Screens) | `01-Requirements/01-07-ui-wireframes.md` | ✅ | +| **5** | Stakeholder Sign-off & Risk Register | `00-Overview/00-04-stakeholder-signoff-and-risk.md` | ✅ | +| **6** | KPI Baseline Data (14 KPIs) | `00-Overview/00-05-kpi-baseline.md` | ✅ | +| **7** | Migration Business Scope (~20K Docs) | `03-Data-and-Storage/03-06-migration-business-scope.md` | ✅ | +| **8** | Release Management Policy | `04-Infrastructure-OPS/04-08-release-management-policy.md` | ✅ | +| **9** | Training Plan (per Role, 4 Phases) | `00-Overview/00-06-training-plan.md` | ✅ | +| **10** | Edge Cases & Business Rules (37 rules) | `01-Requirements/01-06-edge-cases-and-rules.md` | ✅ | + +--- + +## 🔑 Quick Reference: Critical Files + +> Before writing ANY code, verify these files first. + +| เอกสาร | Path | ใช้เมื่อ | +|--------|------|---------| +| **Schema Tables** | `03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql` | ก่อนเขียน Query ทุกครั้ง | +| **Data Dictionary** | `03-Data-and-Storage/03-01-data-dictionary.md` | ตรวจ Field Meaning + Business Rules | +| **Seed Permissions** | `03-Data-and-Storage/lcbp3-v1.8.0-seed-permissions.sql` | ตรวจ CASL Permission Matrix | +| **Edge Cases** | `01-Requirements/01-06-edge-cases-and-rules.md` | 37 Rules ป้องกัน Bug | +| **Migration Scope** | `03-Data-and-Storage/03-06-migration-business-scope.md` | งาน Migration Bot | +| **Release Policy** | `04-Infrastructure-OPS/04-08-release-management-policy.md` | ก่อน Deploy / Hotfix | +| **UAT Criteria** | `01-Requirements/01-05-acceptance-criteria.md` | ตรวจความสมบูรณ์ Feature | +| **ADR-009** | `06-Decision-Records/ADR-009-db-strategy.md` | Schema Change Process | +| **ADR-018** | `06-Decision-Records/ADR-018-ai-boundary.md` | AI/Ollama Integration Rules | + --- ## 🎯 Important Rules สำหรับนักพัฒนา (Must Follow) 1. **The Specs are the Source of Truth:** ก่อนเริ่มงานเสมอ ให้อ่าน Requirement, Architecture และ ADR ถ้าเจอประโยคไหนที่คุณคิดไว้แล้วขัดแย้งกับ Specs ให้ยึดจากใน `specs/` เป็นคำตอบสุดท้าย -2. **Never Invent Tables / Columns:** ห้ามสร้างคอลัมน์ใหม่ในหัวเอง ให้ดู File Database schema ใน `03-Data-and-Storage` สำหรับโครงสร้าง Table ทั้งตัวหลักและ Reference -3. **Double-Lock Numbering:** ระบบออกเลขเอกสารของโปรเจกต์มีความอ่อนไหวสูงมาก เนื่องจากมีหลาย User พร้อมกัน ต้องใช้ "Redis Redlock" ควบคู่กับ "DB Optimistic Lock" เพื่อแก้ Race Condition -4. **Follow Blue-Green Deployment:** โปรเจกต์พึ่งพาการทำ Blue-Green Environment เพื่อ Downtime ขั้นต่ำ ฉะนั้นห้ามแก้ Config โดยไม่เข้าใจผลกระทบต่อ Environment ของ Container Station + +2. **Never Invent Tables / Columns:** ห้ามสร้างคอลัมน์ใหม่ในหัวเอง ให้ดู Schema ใน `03-Data-and-Storage/lcbp3-v1.8.0-schema-02-tables.sql` สำหรับโครงสร้าง Table ทั้งหลัก และ Reference — Schema แบ่งเป็น 3 ไฟล์ (01-drop / 02-tables / 03-views-indexes) + +3. **Double-Lock Numbering:** ระบบออกเลขเอกสารมีความอ่อนไหวสูง เนื่องจากมีหลาย User พร้อมกัน ต้องใช้ **Redis Redlock** ควบคู่กับ **DB Optimistic Lock** เพื่อแก้ Race Condition (ADR-002) + +4. **Follow Blue-Green Deployment:** โปรเจกต์พึ่งพาการทำ Blue-Green Environment เพื่อ Downtime ขั้นต่ำ ต้องผ่าน **5 Release Gates** ก่อน Deploy ทุกครั้ง — ดู `04-08-release-management-policy.md` + 5. **No `any` Types:** ไม่อนุญาตให้ใช้ `any` ในโค้ด พยายามใช้ Validation ผ่าน DTO / Zod แบบ Strongly-typed เสมอ + +6. **AI Isolation (ADR-018):** Ollama ต้องรันบน **Admin Desktop** (i9-9900K, RTX 2060 SUPER 8GB) เท่านั้น — ห้ามรันบน QNAP/Production Server ห้ามมี Direct DB Access โดยเด็ดขาด AI Output ต้องผ่าน Backend Validation ก่อน Write ทุกครั้ง + +7. **UAT Sign-off Required:** ห้าม Close UAT โดยไม่มี Acceptance Criteria ✅ ครบทุกข้อ — ดู `01-05-acceptance-criteria.md` + +8. **Migration Gate Required:** ห้ามเริ่ม Legacy Migration โดยไม่ผ่าน Go/No-Go Gate #1 — ดู `03-06-migration-business-scope.md` + +--- + +## 🏛️ ADR Reference (All 17 + 1 Patch) + +| ADR | Topic | Key Decision | +|-----|-------|-------------| +| ADR-001 | Workflow Engine | Unified state machine for document workflows | +| ADR-002 | Doc Numbering | Redis Redlock + DB optimistic locking | +| ADR-005 | Technology Stack | NestJS + Next.js + MariaDB + Redis | +| ADR-006 | Redis Caching | Cache strategy and invalidation patterns | +| ADR-008 | Email Notification | BullMQ queue-based email/LINE/in-app | +| ADR-009 | DB Strategy | No TypeORM migrations — modify schema SQL directly | +| ADR-010 | Logging/Monitoring | Prometheus + Loki + Grafana stack | +| ADR-011 | App Router | Next.js App Router with RSC patterns | +| ADR-012 | UI Components | Shadcn/UI component library | +| ADR-013 | Form Handling | React Hook Form + Zod validation | +| ADR-014 | State Management | TanStack Query (server) + Zustand (client) | +| ADR-015 | Deployment | Docker Compose + Gitea CI/CD | +| ADR-016 | Security | JWT + CASL RBAC + Helmet.js + ClamAV | +| ADR-017 | Ollama Migration | Local AI + n8n for legacy data import | +| ADR-018 ★ | AI Boundary (Patch 1.8.1) | AI isolation — no direct DB/storage access | + +> **Priority:** `06-Decision-Records` > `05-Engineering-Guidelines` > others