Prepare to version 1.5 use spec-kit

specs/01-requirements/03.11-document-numbering.md

@@ -0,0 +1,60 @@
+# 3.11 Document Numbering Management (การจัดการเลขที่เอกสาร)
+
+---
+
+title: 'Functional Requirements: Document Numbering Management'
+version: 1.5.0
+status: first-draft
+owner: Nattanin Peancharoen
+last_updated: 2025-11-30
+related:
+
+- specs/01-requirements/01-objectives.md
+- specs/01-requirements/02-architecture.md
+- specs/01-requirements/03-functional-requirements.md
+
+---
+
+## 3.11.1. วัตถุประสงค์:
+
+- ระบบต้องสามารถสร้างเลขที่เอกสาร (Running Number) ได้โดยอัตโนมัติและยืดหยุ่นสูง
+
+## 3.11.2. Logic การนับเลข (Counter Logic):
+
+- การนับเลขจะต้องรองรับการแยกตาม Key ที่ซับซ้อนขึ้น:
+- Project + Originator + Type + Discipline (ถ้ามี) + Sub-Type (ถ้ามี) + Year
+
+## 3.11.3. Format Template:
+
+- รองรับการกำหนดรูปแบบด้วย Token Replacement เช่น:
+  - รองรับ Token: `{ORG}-{TYPE}-{DISCIPLINE}-{SEQ:4}-{REV}` -> `TEAM-RFA-STR-0001-A`
+  - รองรับ Token: `{PROJECT}`, `{ORG}`, `{TYPE}`, `{DISCIPLINE}`, `{SUBTYPE}`, `{SUBTYPE_NUM}`, `{YEAR}`, `{YEAR_SHORT}`, `{SEQ:n}`
+
+## 3.11.4. Transmittal Logic:
+
+- รองรับเงื่อนไขพิเศษสำหรับ Transmittal ที่เลขอาจเปลี่ยนตามผู้รับ (To Owner vs To Contractor)
+
+## 3.11.5. กลไกความปลอดภัย:
+
+- ยังคงใช้ Redis Distributed Lock และ Optimistic Locking เพื่อป้องกันเลขซ้ำหรือข้าม
+
+## 3.11.6. ต้องมี retry mechanism และ fallback strategy เมื่อการ generate เลขที่เอกสารล้มเหลว
+
+## 3.11.7. Fallback Logic (เพิ่ม):
+
+- กรณีที่เอกสารประเภทนั้นไม่มี discipline_id หรือ sub_type_id (เป็นค่า NULL หรือไม่ระบุ) ให้ระบบใช้ค่า Default (เช่น 0) ในการจัดกลุ่ม Counter เพื่อป้องกัน Error และรับประกันความถูกต้องของ Running Number (Uniqueness Guarantee)
+- Scenario 1: Redis Unavailable
+  - Fallback เป็น database-only locking (pessimistic lock)
+  - Log warning และแจ้ง ops team
+  - ระบบยังใช้งานได้แต่ performance ลดลง
+- Scenario 2: Lock Acquisition Timeout
+  - Retry 5 ครั้งด้วย exponential backoff (1s, 2s, 4s, 8s, 16s)
+  - หลัง 5 ครั้ง: Return error 503 "Service Temporarily Unavailable"
+  - Frontend แสดง user-friendly message: "ระบบกำลังยุ่ง กรุณาลองใหม่ภายหลัง"
+- Scenario 3: Version Conflict After Lock
+  - Retry transaction อีก 2 ครั้ง
+  - หากยังล้มเหลว: Log error พร้อม context และ return 409 Conflict
+  - Frontend แสดง user-friendly message: "เลขที่เอกสารถูกเปลี่ยน กรุณาลองใหม่"
+- Monitoring:
+  - Alert ถ้า lock acquisition failures > 5% ใน 5 นาที
+  - Dashboard แสดง lock wait time percentiles