1853 lines
62 KiB
Markdown
1853 lines
62 KiB
Markdown
# 3.11 Document Numbering Management (การจัดการเลขที่เอกสาร)
|
||
|
||
---
|
||
title: 'Functional Requirements: Document Numbering Management'
|
||
version: 1.5.1
|
||
status: draft
|
||
owner: Nattanin Peancharoen
|
||
last_updated: 2025-12-02
|
||
related:
|
||
|
||
- specs/01-requirements/01-objectives.md
|
||
- specs/01-requirements/02-architecture.md
|
||
- specs/01-requirements/03-functional-requirements.md
|
||
- specs/03-implementation/document-numbering.md
|
||
- specs/04-operations/document-numbering-operations.md
|
||
- specs/04-data-dictionary/4_Data_Dictionary_V1_4_4.md
|
||
|
||
---
|
||
|
||
> **📖 เอกสารที่เกี่ยวข้อง**
|
||
>
|
||
> - **Implementation Guide**: [document-numbering.md](file:///e:/np-dms/lcbp3/specs/03-implementation/document-numbering.md) - รายละเอียดการ implement ด้วย NestJS, TypeORM, Redis
|
||
> - **Operations Guide**: [document-numbering-operations.md](file:///e:/np-dms/lcbp3/specs/04-operations/document-numbering-operations.md) - Monitoring, Troubleshooting, Maintenance Procedures
|
||
|
||
## 3.11.1. วัตถุประสงค์
|
||
|
||
- ระบบต้องสามารถสร้างเลขที่เอกสาร (Running Number) ได้โดยอัตโนมัติและยืดหยุ่นสูง
|
||
- ระบบต้องสามารถกำหนดรูปแบบ (template) เลขที่เอกสารได้ สำหรับแต่ละโครงการ, ชนิดเอกสาร, ประเภทเอกสาร
|
||
- ระบบต้องรับประกัน Uniqueness ของเลขที่เอกสารในทุกสถานการณ์
|
||
- ระบบต้องรองรับการทำงานแบบ concurrent ได้อย่างปลอดภัย
|
||
|
||
## 3.11.2. Logic การนับเลข (Counter Logic)
|
||
|
||
การนับเลขจะแยกตาม **Counter Key** ที่ประกอบด้วยหลายส่วน ขึ้นกับประเภทเอกสาร
|
||
|
||
### Counter Key Components
|
||
|
||
| Component | Required? | Description | Database Source | Default if NULL |
|
||
| ---------------------------- | ---------------- | ------------------- | --------------------------------------------------------- | --------------- |
|
||
| `project_id` | ✅ Yes | ID โครงการ | Derived from user context or organization | - |
|
||
| `originator_organization_id` | ✅ Yes | ID องค์กรผู้ส่ง | `correspondences.originator_id` | - |
|
||
| `recipient_organization_id` | Depends on type | ID องค์กรผู้รับหลัก (TO) | `correspondence_recipients` where `recipient_type = 'TO'` | NULL for RFA |
|
||
| `correspondence_type_id` | ✅ Yes | ID ประเภทเอกสาร | `correspondence_types.id` | - |
|
||
| `sub_type_id` | TRANSMITTAL only | ID ประเภทย่อย | `correspondence_sub_types.id` | 0 |
|
||
| `rfa_type_id` | RFA only | ID ประเภท RFA | `rfa_types.id` | 0 |
|
||
| `discipline_id` | RFA only | ID สาขางาน | `disciplines.id` | 0 |
|
||
| `current_year` | ✅ Yes | ปี ค.ศ. | System year (ปัจจุบัน) | - |
|
||
|
||
### Counter Key แยกตามประเภทเอกสาร
|
||
|
||
**LETTER / RFI / MEMO / EMAIL / MOM / INSTRUCTION / NOTICE / OTHER**:
|
||
|
||
```
|
||
(project_id, originator_organization_id, recipient_organization_id,
|
||
correspondence_type_id, 0, 0, 0, current_year)
|
||
```
|
||
|
||
*หมายเหตุ*: ไม่ใช้ `discipline_id`, `sub_type_id`, `rfa_type_id`
|
||
|
||
**TRANSMITTAL**:
|
||
|
||
```
|
||
(project_id, originator_organization_id, recipient_organization_id,
|
||
correspondence_type_id, sub_type_id, 0, 0, current_year)
|
||
```
|
||
|
||
*หมายเหตุ*: ใช้ `sub_type_id` เพิ่มเติม
|
||
|
||
**RFA**:
|
||
|
||
```
|
||
(project_id, originator_organization_id, NULL,
|
||
correspondence_type_id, 0, rfa_type_id, discipline_id, current_year)
|
||
```
|
||
|
||
*หมายเหตุ*: RFA ไม่ใช้ `recipient_organization_id` เพราะเป็นเอกสารโครงการ (CONTRACTOR → CONSULTANT → OWNER)
|
||
|
||
### วิธีการหา project_id
|
||
|
||
เนื่องจาก Template ของ LETTER/TRANSMITTAL ไม่มี `{PROJECT}` token ระบบจะหา `project_id` จาก:
|
||
|
||
1. **User Context** (แนะนำ):
|
||
- เมื่อ User สร้างเอกสาร UI จะให้เลือก Project/Contract ก่อน
|
||
- ใช้ `project_id` จาก Context ที่เลือก
|
||
|
||
2. **จาก Organization**:
|
||
- Query `project_organizations` หรือ `contract_organizations`
|
||
- ใช้ `originator_organization_id` หา project ที่เกี่ยวข้อง
|
||
- ถ้ามีหลาย project ให้ User เลือก
|
||
|
||
3. **Validation**:
|
||
- ตรวจสอบว่า organization มีสิทธิ์ใน project นั้น
|
||
- ตรวจสอบว่า project/contract เป็น active
|
||
|
||
### Fallback สำหรับค่า NULL
|
||
|
||
- `discipline_id`: ใช้ `0` (ไม่ระบุสาขางาน)
|
||
- `sub_type_id`: ใช้ `0` (ไม่มีประเภทย่อย)
|
||
- `rfa_type_id`: ใช้ `0` (ไม่ระบุประเภท RFA)
|
||
- `recipient_organization_id`: ใช้ `NULL` สำหรับ RFA, Required สำหรับ LETTER/TRANSMITTAL
|
||
|
||
## 3.11.3. Format Templates by Correspondence Type
|
||
|
||
> **📝 หมายเหตุสำคัญ**
|
||
>
|
||
> - Templates ด้านล่างเป็น **ตัวอย่าง** สำหรับประเภทเอกสารหลัก
|
||
> - ระบบรองรับ **ทุกประเภทเอกสาร** ที่อยู่ใน `correspondence_types` table
|
||
> - หากมีการเพิ่มประเภทใหม่ในอนาคต สามารถใช้งานได้โดยอัตโนมัติ
|
||
> - Admin สามารถกำหนด Template เฉพาะสำหรับแต่ละประเภทผ่าน Admin Panel
|
||
|
||
### 3.11.3.1. Letter (TYPE = LETTER)
|
||
|
||
**Template**:
|
||
|
||
```
|
||
{ORIGINATOR}-{RECIPIENT}-{SEQ:4}-{YEAR:B.E.}
|
||
```
|
||
|
||
**Example**: `คคง.-สคฉ.3-0001-2568`
|
||
|
||
**Token Breakdown**:
|
||
|
||
- `คคง.` = {ORIGINATOR} = รหัสองค์กรผู้ส่ง
|
||
- `สคฉ.3` = {RECIPIENT} = รหัสองค์กรผู้รับหลัก (TO)
|
||
- `0001` = {SEQ:4} = Running number (เริ่ม 0001, 0002, ...)
|
||
- `2568` = {YEAR:B.E.} = ปี พ.ศ.
|
||
|
||
> **⚠️ Template vs Counter Separation**
|
||
>
|
||
> - {CORR_TYPE} **ไม่แสดง**ใน template เพื่อความกระชับ
|
||
> - แต่ระบบ**ยังใช้ correspondence_type_id ใน Counter Key** เพื่อแยก counter
|
||
> - LETTER, MEMO, RFI **มี counter แยกกัน** แม้ template format เหมือนกัน
|
||
|
||
**Counter Key**: `(project_id, originator_org_id, recipient_org_id, corr_type_id, 0, 0, 0, year)`
|
||
|
||
---
|
||
|
||
### 3.11.3.2. Transmittal (TYPE = TRANSMITTAL)
|
||
|
||
**Template**:
|
||
|
||
```
|
||
{ORIGINATOR}-{RECIPIENT}-{SUB_TYPE}-{SEQ:4}-{YEAR:B.E.}
|
||
```
|
||
|
||
**Example**: `คคง.-สคฉ.3-21-0117-2568`
|
||
|
||
**Token Breakdown**:
|
||
|
||
- `คคง.` = {ORIGINATOR}
|
||
- `สคฉ.3` = {RECIPIENT}
|
||
- `21` = {SUB_TYPE} = หมายเลขประเภทย่อย (11=MAT, 12=SHP, 13=DWG, 14=MET, ...)
|
||
- `0117` = {SEQ:4}
|
||
- `2568` = {YEAR:B.E.}
|
||
|
||
> **⚠️ Template vs Counter Separation**
|
||
>
|
||
> - {CORR_TYPE} **ไม่แสดง**ใน template (เหมือน LETTER)
|
||
> - TRANSMITTAL มี counter แยกจาก LETTER
|
||
|
||
**Counter Key**: `(project_id, originator_org_id, recipient_org_id, corr_type_id, sub_type_id, 0, 0, year)`
|
||
|
||
---
|
||
|
||
### 3.11.3.3. RFA (Request for Approval)
|
||
|
||
**Template**:
|
||
|
||
```
|
||
{PROJECT}-{CORR_TYPE}-{DISCIPLINE}-{RFA_TYPE}-{SEQ:4}-{REV}
|
||
```
|
||
|
||
**Example**: `LCBP3-C2-RFA-TER-RPT-0001-A`
|
||
|
||
**Token Breakdown**:
|
||
|
||
- `LCBP3-C2` = {PROJECT} = รหัสโครงการ
|
||
- `RFA` = {CORR_TYPE} = ประเภทเอกสาร (**แสดง**ใน RFA template)
|
||
- `TER` = {DISCIPLINE} = รหัสสาขางาน (TER=Terminal, STR=Structure, ...)
|
||
- `RPT` = {RFA_TYPE} = ประเภท RFA (RPT=Report, SDW=Shop Drawing, ...)
|
||
- `0001` = {SEQ:4}
|
||
- `A` = {REV} = Revision code
|
||
|
||
> **📋 RFA Workflow**
|
||
>
|
||
> - RFA เป็น **เอกสารโครงการ** (Project-level document)
|
||
> - Workflow: **CONTRACTOR → CONSULTANT → OWNER**
|
||
> - ไม่มี specific `recipient_id` เพราะเป็น workflow ที่กำหนดไว้แล้ว
|
||
|
||
**Counter Key**: `(project_id, originator_org_id, NULL, corr_type_id, 0, rfa_type_id, discipline_id, year)`
|
||
|
||
---
|
||
|
||
### 3.11.3.4. Drawing
|
||
|
||
**Status**: 🚧 **To Be Determined**
|
||
|
||
Drawing Numbering ยังไม่ได้กำหนด Template เนื่องจาก:
|
||
|
||
- มีความซับซ้อนสูง (Contract Drawing และ Shop Drawing มีกฎต่างกัน)
|
||
- อาจต้องใช้ระบบ Numbering แยกต่างหาก
|
||
- ต้องพิจารณาร่วมกับ RFA ที่เกี่ยวข้อง
|
||
|
||
---
|
||
|
||
### 3.11.3.5. Other Correspondence Types
|
||
|
||
**Applicable to**: RFI, MEMO, EMAIL, MOM, INSTRUCTION, NOTICE, OTHER
|
||
|
||
**Template**:
|
||
|
||
```
|
||
{ORIGINATOR}-{RECIPIENT}-{SEQ:4}-{YEAR:B.E.}
|
||
```
|
||
|
||
**Example (RFI)**: `คคง.-สคฉ.3-0042-2568`
|
||
**Example (MEMO)**: `คคง.-ผรม.1-0001-2568`
|
||
|
||
> **🔑 Counter Separation**
|
||
>
|
||
> - แม้ template format **เหมือนกับ LETTER**
|
||
> - แต่แต่ละ type มี **counter แยกกัน** ผ่าน `correspondence_type_id`
|
||
> - RFI counter ≠ MEMO counter ≠ LETTER counter
|
||
|
||
**Counter Key**: `(project_id, originator_org_id, recipient_org_id, corr_type_id, 0, 0, 0, year)`
|
||
|
||
**หมายเหตุ**: ทุกประเภทที่ไม่ได้ระบุเฉพาะจะใช้ Template นี้ ถ้ามีการเพิ่ม correspondence type ใหม่ใน `correspondence_types` table จะใช้ Template นี้โดยอัตโนมัติ
|
||
|
||
## 3.11.4. Supported Token Types
|
||
|
||
| Token | Description | Example | Database Source |
|
||
| -------------- | ---------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------- |
|
||
| `{PROJECT}` | รหัสโครงการ | `LCBP3`, `LCBP3-C2` | `projects.project_code` |
|
||
| `{ORIGINATOR}` | รหัสองค์กรผู้ส่ง | `คคง.`, `ผรม.1` | `organizations.organization_code` via `correspondences.originator_id` |
|
||
| `{RECIPIENT}` | รหัสองค์กรผู้รับหลัก (TO) | `สคฉ.3`, `กทท.` | `organizations.organization_code` via `correspondence_recipients` where `recipient_type = 'TO'` |
|
||
| `{CORR_TYPE}` | รหัสประเภทเอกสาร | `RFA`, `TRANSMITTAL`, `LETTER` | `correspondence_types.type_code` |
|
||
| `{SUB_TYPE}` | หมายเลขประเภทย่อย | `11`, `12`, `21` | `correspondence_sub_types.sub_type_number` |
|
||
| `{RFA_TYPE}` | รหัสประเภท RFA | `SDW`, `RPT`, `MAT` | `rfa_types.type_code` |
|
||
| `{DISCIPLINE}` | รหัสสาขาวิชา | `STR`, `TER`, `GEO` | `disciplines.discipline_code` |
|
||
| `{SEQ:n}` | Running number (n = จำนวนหลัก) | `0001`, `0029`, `0985` | Based on `document_number_counters.last_number + 1` |
|
||
| `{YEAR:B.E.}` | ปี พ.ศ. | `2568` | `document_number_counters.current_year + 543` |
|
||
| `{YEAR:A.D.}` | ปี ค.ศ. | `2025` | `document_number_counters.current_year` |
|
||
| `{REV}` | Revision Code | `A`, `B`, `AA` | `correspondence_revisions.revision_label` |
|
||
|
||
### Token Usage Notes
|
||
|
||
**{SEQ:n}**:
|
||
|
||
- `n` = จำนวนหลักที่ต้องการ (typically 4)
|
||
- Counter **เริ่มจาก 0001** และเพิ่มทีละ 1 (0001, 0002, 0003, ...)
|
||
- Padding ด้วย 0 ทางซ้าย
|
||
- Reset ทุกปี (ตาม `current_year` ใน Counter Key)
|
||
|
||
**{RECIPIENT}**:
|
||
|
||
- ใช้เฉพาะผู้รับที่มี `recipient_type = 'TO'` เท่านั้น
|
||
- ถ้ามีหลาย TO ให้ใช้คนแรก (ตาม sort order)
|
||
- **ไม่ใช้สำหรับ RFA** (RFA ไม่มี {RECIPIENT} ใน template)
|
||
|
||
**{CORR_TYPE}**:
|
||
|
||
- รองรับทุกค่าจาก `correspondence_types.type_code`
|
||
- ถ้าม<E0B8B2>การเพิ่มประเภทใหม่ จะใช้งานได้ทันที
|
||
- **แสดงใน template**: RFA only
|
||
- **ไม่แสดงแต่ใช้ใน counter**: LETTER, TRANSMITTAL, และ Other types
|
||
|
||
**Deprecated Tokens** (ไม่ควรใช้):
|
||
|
||
- ~~`{ORG}`~~ → ใช้ `{ORIGINATOR}` หรือ `{RECIPIENT}` แทน
|
||
- ~~`{TYPE}`~~ → ใช้ `{CORR_TYPE}`, `{SUB_TYPE}`, หรือ `{RFA_TYPE}` แทน (ตามบริบท)
|
||
- ~~`{CATEGORY}`~~ → ไม่ได้ใช้งานในระบบปัจจุบัน
|
||
|
||
## 3.11.5. Security & Data Integrity Requirements
|
||
|
||
### 3.11.5.1. Concurrency Control
|
||
|
||
**Requirements:**
|
||
|
||
- ระบบ**ต้อง**ป้องกัน race condition เมื่อมีการสร้างเลขที่เอกสารพร้อมกัน
|
||
- ระบบ**ต้อง**รับประกัน uniqueness ของเลขที่เอกสารในทุกสถานการณ์
|
||
- ระบบ**ควร**ใช้ Distributed Lock (Redis) เป็นกลไก primary
|
||
- ระบบ**ต้อง**มี fallback mechanism เมื่อ Redis ไม่พร้อมใช้งาน
|
||
|
||
**Implementation Details:** ดู [Implementation Guide - Section 2.3](file:///e:/np-dms/lcbp3/specs/03-implementation/document-numbering.md#23-redis-lock-service)
|
||
|
||
### 3.11.5.2. Data Integrity
|
||
|
||
**Requirements:**
|
||
|
||
- ระบบ**ต้อง**ใช้ Optimistic Locking เพื่อตรวจจับ concurrent updates
|
||
- ระบบ**ต้อง**มี database constraints เพื่อป้องกันข้อมูลผิดพลาด:
|
||
- Unique constraint บน `document_number`
|
||
- Foreign key constraints ทุก relationship
|
||
- Check constraints สำหรับ business rules
|
||
|
||
### 3.11.5.3. Authorization
|
||
|
||
**Requirements:**
|
||
|
||
- เฉพาะ **authenticated users** เท่านั้นที่สามารถ request document number
|
||
- เฉพาะ **Project Admin** เท่านั้นที่แก้ไข template ได้
|
||
- เฉพาะ **Super Admin** เท่านั้นที่ reset counter ได้ (requires approval)
|
||
|
||
## 3.11.6. Error Handling Requirements
|
||
|
||
### 3.11.6.1. Retry Mechanism
|
||
|
||
**Requirements:**
|
||
|
||
ระบบ**ต้อง**จัดการ error scenarios ต่อไปนี้:
|
||
|
||
| Scenario | Strategy | Max Retries | Expected Response |
|
||
| ------------------- | ------------------- | ----------- | ------------------------------- |
|
||
| Redis Unavailable | Fallback to DB Lock | 0 | Continue (degraded performance) |
|
||
| Lock Timeout | Exponential Backoff | 5 | HTTP 503 after final retry |
|
||
| Version Conflict | Immediate Retry | 2 | HTTP 409 after final retry |
|
||
| DB Connection Error | Exponential Backoff | 3 | HTTP 500 after final retry |
|
||
|
||
**Implementation Details:** ดู [Implementation Guide - Section 2.5](file:///e:/np-dms/lcbp3/specs/03-implementation/document-numbering.md#25-main-service-with-retry-logic)
|
||
|
||
### 3.11.6.2. User Experience
|
||
|
||
**Requirements:**
|
||
|
||
- Error messages **ต้อง**เป็นภาษาไทย และเข้าใจง่าย
|
||
- HTTP status codes **ต้อง**สื่อความหมายที่ถูกต้อง
|
||
- Frontend **ควร**แสดง retry option สำหรับ transient errors
|
||
|
||
## 3.11.7. Configuration Management Requirements
|
||
|
||
### 3.11.7.1. Template Management
|
||
|
||
**Requirements:**
|
||
|
||
- Project Admin **ต้อง**สามารถกำหนด/แก้ไข template ผ่าน Admin Panel
|
||
- ระบบ**ต้อง**validate template ก่อนบันทึก
|
||
- การเปลี่ยนแปลง template **ต้องไม่**ส่งผลต่อเอกสารที่สร้างไว้แล้ว
|
||
|
||
### 3.11.7.2. Template Versioning
|
||
|
||
**Requirements:**
|
||
|
||
- ระบบ**ต้อง**เก็บ history ของ template changes
|
||
- ระบบ**ต้อง**บันทึก user, timestamp, และเหตุผลในการเปลี่ยนแปลง
|
||
- ระบบ**ควร**สามารถ rollback ไปเวอร์ชันก่อนหน้าได้
|
||
|
||
### 3.11.7.3. Counter Reset Policy
|
||
|
||
**Requirements:**
|
||
|
||
- Counter **ต้อง**reset ตามปี (อัตโนมัติ)
|
||
- Admin **ต้อง**สามารถ manual reset counter ได้ (require approval + audit log)
|
||
|
||
**Implementation Details:** ดู [Implementation Guide - Section 4](file:///e:/np-dms/lcbp3/specs/03-implementation/document-numbering.md#4-bullmq-job-for-counter-reset)
|
||
|
||
## 3.11.8. Audit Trail Requirements
|
||
|
||
### 3.11.8.1. Audit Logging
|
||
|
||
**Requirements:**
|
||
|
||
ระบบ**ต้อง**บันทึกข้อมูลต่อไปนี้สำหรับทุก document number generation:
|
||
|
||
- `document_id` - เอกสารที่ถูกสร้าง
|
||
- `generated_number` - เลขที่ถูกสร้าง
|
||
- `counter_key` - key ที่ใช้ในการนับ (JSON format)
|
||
- `template_used` - template ที่ใช้
|
||
- `user_id` - ผู้ที่ request
|
||
- `ip_address` - IP address ของผู้ request
|
||
- `timestamp` - เวลาที่สร้าง
|
||
- `retry_count` - จำนวนครั้งที่ retry
|
||
- `performance_metrics` - Lock wait time, total duration
|
||
|
||
### 3.11.8.2. Error Logging
|
||
|
||
**Requirements:**
|
||
|
||
- ระบบ**ต้อง**บันทึก error แยกต่างหาก พร้อม error type classification
|
||
- ระบบ**ควร**alert ops team สำหรับ critical errors
|
||
|
||
### 3.11.8.3. Retention Policy
|
||
|
||
**Requirements:**
|
||
|
||
- Audit log **ต้อง**เก็บอย่างน้อย **7 ปี** (ตาม พ.ร.บ. ข้อมูลอิเล็กทรอนิกส์)
|
||
|
||
## 3.11.9. Performance Requirements
|
||
|
||
### 3.11.9.1. Response Time
|
||
|
||
**SLA Targets:**
|
||
|
||
| Metric | Target | Notes |
|
||
| ---------------- | -------- | ------------------------ |
|
||
| 95th percentile | ≤ 2 วินาที | ตั้งแต่ request ถึง response |
|
||
| 99th percentile | ≤ 5 วินาที | รวม retry attempts |
|
||
| Normal operation | ≤ 500ms | ไม่มี retry |
|
||
|
||
### 3.11.9.2. Throughput
|
||
|
||
**Capacity Targets:**
|
||
|
||
| Load Level | Target | Notes |
|
||
| ----------- | ----------- | --------- |
|
||
| Normal load | ≥ 50 req/s | ใช้งานปกติ |
|
||
| Peak load | ≥ 100 req/s | ช่วงเร่งงาน |
|
||
|
||
### 3.11.9.3. Availability
|
||
|
||
**SLA Targets:**
|
||
|
||
- **Uptime**: ≥ 99.5% (excluding planned maintenance)
|
||
- **Maximum downtime**: ≤ 3.6 ชั่วโมง/เดือน
|
||
- **RTO**: ≤ 30 นาที
|
||
- **RPO**: ≤ 5 นาที
|
||
|
||
**Operations Details:** ดู [Operations Guide - Section 1](file:///e:/np-dms/lcbp3/specs/04-operations/document-numbering-operations.md#1-performance-requirements)
|
||
|
||
## 3.11.10. Monitoring & Alerting Requirements
|
||
|
||
### 3.11.10.1. Metrics
|
||
|
||
**Requirements:**
|
||
|
||
ระบบ**ต้อง**collect metrics ต่อไปนี้:
|
||
|
||
- Lock acquisition time (p50, p95, p99)
|
||
- Lock acquisition success/failure rate
|
||
- Counter generation latency
|
||
- Retry count distribution
|
||
- Redis connection status
|
||
- Database connection pool usage
|
||
|
||
### 3.11.10.2. Alerts
|
||
|
||
**Requirements:**
|
||
|
||
ระบบ**ต้อง**alert สำหรับ conditions ต่อไปนี้:
|
||
|
||
| Severity | Condition | Action |
|
||
| ---------- | ---------------------------- | ----------------- |
|
||
| 🔴 Critical | Redis unavailable > 1 minute | PagerDuty + Slack |
|
||
| 🔴 Critical | Lock failures > 10% in 5 min | PagerDuty + Slack |
|
||
| 🟡 Warning | Lock failures > 5% in 5 min | Slack |
|
||
| 🟡 Warning | Avg lock wait time > 1 sec | Slack |
|
||
| 🟡 Warning | Retry count > 100/hour | Slack |
|
||
|
||
### 3.11.10.3. Dashboard
|
||
|
||
**Requirements:**
|
||
|
||
- Ops team **ต้อง**มี real-time dashboard แสดง:
|
||
- Lock acquisition success rate
|
||
- Lock wait time percentiles
|
||
- Generation rate (per minute)
|
||
- Error rate by type
|
||
- Connection health status
|
||
|
||
**Operations Details:** ดู [Operations Guide - Section 3](file:///e:/np-dms/lcbp3/specs/04-operations/document-numbering-operations.md#3-monitoring--metrics)
|
||
|
||
|
||
## 3.11.11. API Reference
|
||
|
||
เอกสารนี้อ้างอิงถึง API endpoints ต่อไปนี้:
|
||
|
||
### Document Number Generation
|
||
|
||
```http
|
||
POST /api/v1/documents/{documentId}/generate-number
|
||
```
|
||
|
||
สร้างเลขที่เอกสารสำหรับ document ที่ระบุ
|
||
|
||
**Request Body:**
|
||
|
||
```json
|
||
{
|
||
"counterKey": {
|
||
"projectId": 2,
|
||
"originatorOrgId": 22,
|
||
"recipientOrgId": 10,
|
||
"correspondenceTypeId": 6,
|
||
"subTypeId": 0,
|
||
"rfaTypeId": 0,
|
||
"disciplineId": 0,
|
||
"year": 2025
|
||
}
|
||
}
|
||
```
|
||
|
||
**Response:**
|
||
|
||
```json
|
||
{
|
||
"documentNumber": "คคง.-สคฉ.3-0001-2568",
|
||
"generatedAt": "2025-12-02T15:30:00Z"
|
||
}
|
||
```
|
||
|
||
### Template Management
|
||
|
||
```http
|
||
GET /api/v1/document-numbering/configs
|
||
```
|
||
|
||
ดูรายการ template configuration ทั้งหมด
|
||
|
||
```http
|
||
PUT /api/v1/document-numbering/configs/{configId}
|
||
```
|
||
|
||
แก้ไข template (Project Admin only)
|
||
|
||
```http
|
||
POST /api/v1/document-numbering/configs/{configId}/reset-counter
|
||
```
|
||
|
||
Reset counter (Super Admin only, requires approval)
|
||
|
||
**รายละเอียดเพิ่มเติม:** ดู [API Design](file:///e:/np-dms/lcbp3/specs/02-architecture/api-design.md)
|
||
|
||
## 3.11.12. Database Schema Reference
|
||
|
||
เอกสารนี้อ้างอิงถึง database tables ต่อไปนี้:
|
||
|
||
### Core Tables
|
||
|
||
- `document_number_counters` - เก็บ counter values และ template configuration
|
||
- `document_number_audit` - เก็บ audit trail ของการ generate เลขที่
|
||
- `document_number_errors` - เก็บ error logs
|
||
|
||
### Related Tables
|
||
|
||
- `documents` - เก็บ document number ที่ถูกสร้าง (column: `document_number` UNIQUE)
|
||
- `correspondence_types` - ประเภทเอกสาร (LETTER, RFA, TRANSMITTAL, etc.)
|
||
- `correspondence_sub_types` - ประเภทย่อย (สำหรับ TRANSMITTAL)
|
||
- `rfa_types` - ประเภท RFA (SHD, RPT, MAT, etc.)
|
||
- `disciplines` - สาขาวิชา (TER, STR, GEO, etc.)
|
||
- `projects` - โครงการ
|
||
- `organizations` - องค์กร
|
||
|
||
**Schema Details:** ดู [Implementation Guide - Section 1](file:///e:/np-dms/lcbp3/specs/03-implementation/document-numbering.md#1-database-implementation)
|
||
|
||
## 3.11.13. Database Schema Requirements
|
||
|
||
### 3.11.13.1. Counter Table Schema Requirements
|
||
|
||
**Primary Table**: `document_number_counters`
|
||
|
||
**Required Columns:**
|
||
- Composite primary key: `(project_id, originator_organization_id, recipient_organization_id, correspondence_type_id, sub_type_id, rfa_type_id, discipline_id, current_year)`
|
||
- `version` - สำหรับ optimistic locking
|
||
- `last_number` - counter value (เริ่มจาก 0)
|
||
|
||
**Important Notes:**
|
||
- ใช้ `COALESCE(recipient_organization_id, 0)` ใน Primary Key เพื่อรองรับ NULL
|
||
- Counter reset ทุกปี (เมื่อ `current_year` เปลี่ยน)
|
||
- ต้องมี seed data สำหรับ `correspondence_types`, `rfa_types`, `disciplines` ก่อน
|
||
|
||
**Schema Details:** ดู [Implementation Guide - Section 1.1](file:///e:/np-dms/lcbp3/specs/03-implementation/document-numbering.md#11-counter-table-schema)
|
||
|
||
### 3.11.13.2. Audit Table Requirements
|
||
|
||
**Primary Table**: `document_number_audit`
|
||
|
||
**Required Columns:**
|
||
- `document_id`, `generated_number`, `counter_key` (JSON)
|
||
- `template_used`, `user_id`, `ip_address`
|
||
- Performance metrics: `retry_count`, `lock_wait_ms`, `total_duration_ms`
|
||
- `fallback_used` - tracking fallback scenarios
|
||
|
||
**Retention:** ≥ 7 ปี
|
||
|
||
### 3.11.13.3. Error Log Requirements
|
||
|
||
**Primary Table**: `document_number_errors`
|
||
|
||
**Required Columns:**
|
||
- `error_type` - ENUM classification
|
||
- `error_message`, `stack_trace`, `context_data` (JSON)
|
||
- `user_id`, `ip_address`, `created_at`, `resolved_at`
|
||
|
||
## 3.11.14. Security Considerations
|
||
|
||
### 3.11.14.1. Authorization
|
||
|
||
- เฉพาะ **authenticated users** เท่านั้นที่สามารถ request document number
|
||
- เฉพาะ **Project Admin** เท่านั้นที่แก้ไข template ได้
|
||
- เฉพาะ **Super Admin** เท่านั้นที่ reset counter ได้
|
||
|
||
### 3.11.14.2. Rate Limiting
|
||
|
||
**Requirements:**
|
||
- Limit ต่อ user: **10 requests/minute** (prevent abuse)
|
||
- Limit ต่อ IP: **50 requests/minute**
|
||
|
||
**Implementation Details:** ดู [Implementation Guide - Section 5](file:///e:/np-dms/lcbp3/specs/03-implementation/document-numbering.md#5-api-controller)
|
||
|
||
### 3.11.14.3. Audit & Compliance
|
||
|
||
**Requirements:**
|
||
- บันทึกทุก API call ที่เกี่ยวข้องกับ document numbering
|
||
- เก็บ audit log อย่างน้อย **7 ปี** (ตาม พ.ร.บ. ข้อมูลอิเล็กทรอนิกส์)
|
||
- Audit log **ต้องไม่**สามารถแก้ไขได้ (immutable)
|
||
|
||
---
|
||
|
||
## References
|
||
|
||
- [Implementation Guide](file:///e:/np-dms/lcbp3/specs/03-implementation/document-numbering.md)
|
||
- [Operations Guide](file:///e:/np-dms/lcbp3/specs/04-operations/document-numbering-operations.md)
|
||
- [API Design](file:///e:/np-dms/lcbp3/specs/02-architecture/api-design.md)
|
||
- [Data Dictionary](file:///e:/np-dms/lcbp3/specs/04-data-dictionary/4_Data_Dictionary_V1_4_4.md)
|
||
|
||
|
||
```
|
||
lock:docnum:{project_id}:{org_id}:{recip_id}:{type_id}:{sub}:{rfa}:{disc}:{year}
|
||
```
|
||
|
||
**Lock Configuration**:
|
||
|
||
- **TTL**: 5 วินาที (auto-release เมื่อ timeout)
|
||
- **Acquisition Timeout**: 10 วินาที
|
||
- **Retry Delay**: 100ms (exponential backoff)
|
||
- **Drift Factor**: 0.01 (Redlock algorithm)
|
||
|
||
**Implementation (NestJS)**:
|
||
|
||
```typescript
|
||
// src/document-numbering/services/document-numbering-lock.service.ts
|
||
import Redlock from 'redlock';
|
||
import { Injectable } from '@nestjs/common';
|
||
|
||
@Injectable()
|
||
export class DocumentNumberingLockService {
|
||
private redlock: Redlock;
|
||
|
||
async acquireLock(counterKey: CounterKey): Promise<Lock> {
|
||
const lockKey = this.buildLockKey(counterKey);
|
||
return await this.redlock.acquire([lockKey], 5000); // 5s TTL
|
||
}
|
||
|
||
private buildLockKey(key: CounterKey): string {
|
||
return `lock:docnum:${key.projectId}:${key.originatorOrgId}:` +
|
||
`${key.recipientOrgId ?? 0}:${key.correspondenceTypeId}:` +
|
||
`${key.subTypeId}:${key.rfaTypeId}:${key.disciplineId}:${key.year}`;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.11.5.2. Optimistic Locking
|
||
|
||
ใช้ **TypeORM Optimistic Lock** ร่วมกับ `@Version()` decorator:
|
||
|
||
**Entity Definition**:
|
||
|
||
```typescript
|
||
// src/document-numbering/entities/document-number-counter.entity.ts
|
||
import { Entity, Column, PrimaryColumn, VersionColumn } from 'typeorm';
|
||
|
||
@Entity('document_number_counters')
|
||
export class DocumentNumberCounter {
|
||
@PrimaryColumn({ name: 'project_id' })
|
||
projectId: number;
|
||
|
||
@PrimaryColumn({ name: 'originator_organization_id' })
|
||
originatorOrganizationId: number;
|
||
|
||
@PrimaryColumn({ name: 'recipient_organization_id', nullable: true })
|
||
recipientOrganizationId: number | null;
|
||
|
||
@PrimaryColumn({ name: 'correspondence_type_id' })
|
||
correspondenceTypeId: number;
|
||
|
||
@PrimaryColumn({ name: 'sub_type_id', default: 0 })
|
||
subTypeId: number;
|
||
|
||
@PrimaryColumn({ name: 'rfa_type_id', default: 0 })
|
||
rfaTypeId: number;
|
||
|
||
@PrimaryColumn({ name: 'discipline_id', default: 0 })
|
||
disciplineId: number;
|
||
|
||
@PrimaryColumn({ name: 'current_year' })
|
||
currentYear: number;
|
||
|
||
@VersionColumn({ name: 'version' })
|
||
version: number;
|
||
|
||
@Column({ name: 'last_number', default: 0 })
|
||
lastNumber: number;
|
||
}
|
||
```
|
||
|
||
**Transaction Handling**:
|
||
|
||
```typescript
|
||
// ใช้ TypeORM Transaction + Optimistic Lock
|
||
await this.connection.transaction(async (manager) => {
|
||
const counter = await manager.findOne(DocumentNumberCounter, {
|
||
where: counterKey
|
||
});
|
||
|
||
counter.lastNumber += 1;
|
||
await manager.save(counter); // auto-check version
|
||
});
|
||
```
|
||
|
||
หาก version conflict → TypeORM throw `OptimisticLockVersionMismatchError` → retry
|
||
|
||
### 3.11.5.3. Database Constraints
|
||
|
||
**Unique Constraints**:
|
||
|
||
```sql
|
||
-- บน documents table
|
||
ALTER TABLE documents
|
||
ADD CONSTRAINT uq_document_number UNIQUE (document_number);
|
||
```
|
||
|
||
**Foreign Key Constraints**:
|
||
|
||
- `project_id` → `projects(id)` ON DELETE CASCADE
|
||
- `originator_organization_id` → `organizations(id)` ON DELETE CASCADE
|
||
- `recipient_organization_id` → `organizations(id)` ON DELETE CASCADE
|
||
- `correspondence_type_id` → `correspondence_types(id)` ON DELETE CASCADE
|
||
|
||
**Check Constraints**:
|
||
|
||
```sql
|
||
-- ตรวจสอบว่า last_number ≥ 0
|
||
ALTER TABLE document_number_counters
|
||
ADD CONSTRAINT chk_last_number_positive CHECK (last_number >= 0);
|
||
|
||
-- ตรวจสอบว่า current_year เป็นปี ค.ศ. ที่สมเหตุสมผล
|
||
ALTER TABLE document_number_counters
|
||
ADD CONSTRAINT chk_current_year_valid
|
||
CHECK (current_year BETWEEN 2020 AND 2100);
|
||
```
|
||
|
||
## 3.11.6. Retry Mechanism & Error Handling
|
||
|
||
### 3.11.6.1. Scenario 1: Redis Unavailable
|
||
|
||
**Fallback Strategy**: Database-only Pessimistic Locking
|
||
|
||
**Implementation**:
|
||
|
||
```typescript
|
||
// src/document-numbering/services/document-numbering.service.ts
|
||
@Injectable()
|
||
export class DocumentNumberingService {
|
||
async generateDocumentNumber(dto: GenerateNumberDto): Promise<string> {
|
||
try {
|
||
// พยายามใช้ Redis lock ก่อน
|
||
return await this.generateWithRedisLock(dto);
|
||
} catch (error) {
|
||
if (error instanceof RedisConnectionError) {
|
||
// Fallback: ใช้ database lock
|
||
this.logger.warn('Redis unavailable, falling back to DB lock');
|
||
await this.alertOpsTeam('redis_unavailable');
|
||
return await this.generateWithDbLock(dto);
|
||
}
|
||
throw error;
|
||
}
|
||
}
|
||
|
||
private async generateWithDbLock(dto: GenerateNumberDto): Promise<string> {
|
||
return await this.connection.transaction(async (manager) => {
|
||
// SELECT ... FOR UPDATE = Pessimistic Lock
|
||
const counter = await manager
|
||
.createQueryBuilder(DocumentNumberCounter, 'c')
|
||
.where(counterKeyCondition)
|
||
.setLock('pessimistic_write')
|
||
.getOne();
|
||
|
||
counter.lastNumber += 1;
|
||
await manager.save(counter);
|
||
return this.formatNumber(counter);
|
||
});
|
||
}
|
||
}
|
||
```
|
||
|
||
**Monitoring**:
|
||
|
||
- Log warning พร้อม context (project_id, user_id, timestamp)
|
||
- Alert Ops Team ผ่าน Slack/Email
|
||
- ระบบยังใช้งานได้แต่ performance อาจลดลง 30-50%
|
||
|
||
### 3.11.6.2. Scenario 2: Lock Acquisition Timeout
|
||
|
||
**Retry Strategy**: Exponential Backoff with Jitter
|
||
|
||
```typescript
|
||
// ใช้ @nestjs/common Retry Decorator หรือ custom retry logic
|
||
import { retry } from 'rxjs/operators';
|
||
|
||
const RETRY_CONFIG = {
|
||
maxRetries: 5,
|
||
delays: [1000, 2000, 4000, 8000, 16000], // exponential backoff
|
||
jitter: 0.1 // เพิ่ม randomness ป้องกัน thundering herd
|
||
};
|
||
|
||
async acquireLockWithRetry(key: CounterKey): Promise<Lock> {
|
||
for (let i = 0; i < RETRY_CONFIG.maxRetries; i++) {
|
||
try {
|
||
return await this.lockService.acquireLock(key);
|
||
} catch (error) {
|
||
if (i === RETRY_CONFIG.maxRetries - 1) {
|
||
throw new ServiceUnavailableException(
|
||
'ระบบกำลังยุ่ง กรุณาลองใหม่ภายหลัง'
|
||
);
|
||
}
|
||
const delay = RETRY_CONFIG.delays[i];
|
||
const jitter = delay * RETRY_CONFIG.jitter * Math.random();
|
||
await this.sleep(delay + jitter);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**Response**:
|
||
|
||
- HTTP Status: `503 Service Temporarily Unavailable`
|
||
- Response Body:
|
||
|
||
```json
|
||
{
|
||
"statusCode": 503,
|
||
"message": "ระบบกำลังยุ่ง กรุณาลองใหม่ภายหลัง",
|
||
"error": "Service Unavailable",
|
||
"retryAfter": 30
|
||
}
|
||
```
|
||
|
||
### 3.11.6.3. Scenario 3: Version Conflict (Optimistic Lock)
|
||
|
||
**Retry Strategy**: Immediate Retry (2 attempts)
|
||
|
||
```typescript
|
||
async incrementCounter(counterKey: CounterKey): Promise<number> {
|
||
const MAX_RETRIES = 2;
|
||
|
||
for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
|
||
try {
|
||
return await this.connection.transaction(async (manager) => {
|
||
const counter = await manager.findOne(
|
||
DocumentNumberCounter,
|
||
{ where: counterKey }
|
||
);
|
||
|
||
counter.lastNumber += 1;
|
||
await manager.save(counter); // Version check ที่นี่
|
||
return counter.lastNumber;
|
||
});
|
||
} catch (error) {
|
||
if (error instanceof OptimisticLockVersionMismatchError) {
|
||
this.logger.warn(`Version conflict, retry ${attempt + 1}/${MAX_RETRIES}`);
|
||
if (attempt === MAX_RETRIES - 1) {
|
||
throw new ConflictException('เลขที่เอกสารถูกเปลี่ยน กรุณาลองใหม่');
|
||
}
|
||
// Retry ทันที (ไม่มี delay)
|
||
continue;
|
||
}
|
||
throw error;
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**Response**:
|
||
|
||
- HTTP Status: `409 Conflict`
|
||
- Frontend Action: Auto-retry หรือแสดง toast notification
|
||
|
||
### 3.11.6.4. Scenario 4: Database Connection Error
|
||
|
||
**Retry Strategy**: Exponential Backoff (3 attempts)
|
||
|
||
```typescript
|
||
const DB_RETRY_CONFIG = {
|
||
maxRetries: 3,
|
||
delays: [1000, 2000, 4000]
|
||
};
|
||
|
||
// TypeORM connection retry (กำหนดใน ormconfig)
|
||
{
|
||
type: 'mysql',
|
||
extra: {
|
||
connectionLimit: 10,
|
||
acquireTimeout: 10000,
|
||
// Retry connection 3 ครั้ง
|
||
retryAttempts: 3,
|
||
retryDelay: 1000
|
||
}
|
||
}
|
||
```
|
||
|
||
**Response**:
|
||
|
||
- HTTP Status: `500 Internal Server Error`
|
||
- Response Body:
|
||
|
||
```json
|
||
{
|
||
"statusCode": 500,
|
||
"message": "เกิดข้อผิดพลาดในระบบ กรุณาติดต่อผู้ดูแลระบบ",
|
||
"error": "Internal Server Error",
|
||
"ref": "ERR-20250102-1234-ABCD"
|
||
}
|
||
```
|
||
|
||
- Alerting: ส่ง PagerDuty/Slack alert ทันที (severity: CRITICAL)
|
||
|
||
## 3.11.7. Configuration Management
|
||
|
||
### 3.11.7.1. Admin Panel Configuration
|
||
|
||
**Features**:
|
||
|
||
- Project Admin สามารถกำหนด/แก้ไข template ผ่าน Web UI
|
||
- Preview document number ก่อนบันทึก
|
||
- Template validation แบบ real-time
|
||
|
||
**Template Validation Logic**:
|
||
|
||
```typescript
|
||
// src/document-numbering/validators/template.validator.ts
|
||
import { Injectable } from '@nestjs/common';
|
||
|
||
@Injectable()
|
||
export class TemplateValidator {
|
||
private readonly ALLOWED_TOKENS = [
|
||
'PROJECT', 'ORIGINATOR', 'RECIPIENT', 'CORR_TYPE',
|
||
'SUB_TYPE', 'RFA_TYPE', 'DISCIPLINE', 'SEQ', 'YEAR', 'REV'
|
||
];
|
||
|
||
validate(template: string, correspondenceType: string): ValidationResult {
|
||
const tokens = this.extractTokens(template);
|
||
const errors: string[] = [];
|
||
|
||
// ตรวจสอบ Token ที่ไม่รู้จัก
|
||
for (const token of tokens) {
|
||
if (!this.ALLOWED_TOKENS.includes(token.name)) {
|
||
errors.push(`Unknown token: {${token.name}}`);
|
||
}
|
||
}
|
||
|
||
// กฎพิเศษสำหรับแต่ละประเภท
|
||
if (correspondenceType === 'RFA') {
|
||
if (!tokens.some(t => t.name === 'PROJECT')) {
|
||
errors.push('RFA template ต้องมี {PROJECT}');
|
||
}
|
||
}
|
||
|
||
if (correspondenceType === 'TRANSMITTAL') {
|
||
if (!tokens.some(t => t.name === 'SUB_TYPE')) {
|
||
errors.push('TRANSMITTAL template ต้องมี {SUB_TYPE}');
|
||
}
|
||
}
|
||
|
||
return { valid: errors.length === 0, errors };
|
||
}
|
||
}
|
||
```
|
||
|
||
**API Endpoint**:
|
||
|
||
```typescript
|
||
// PUT /api/v1/document-numbering/configs/:configId
|
||
@Put('configs/:configId')
|
||
@Roles('PROJECT_ADMIN')
|
||
async updateTemplate(
|
||
@Param('configId') configId: number,
|
||
@Body() dto: UpdateTemplateDto
|
||
): Promise<DocumentNumberConfig> {
|
||
// Validate template
|
||
const validation = await this.templateValidator.validate(
|
||
dto.template,
|
||
dto.correspondenceType
|
||
);
|
||
|
||
if (!validation.valid) {
|
||
throw new BadRequestException(validation.errors);
|
||
}
|
||
|
||
// บันทึก template (ไม่ส่งผลต่อเอกสารที่สร้างแล้ว)
|
||
return await this.configService.update(configId, dto);
|
||
}
|
||
```
|
||
|
||
### 3.11.7.2. Template Versioning
|
||
|
||
**Database Table**: `document_number_config_history`
|
||
|
||
```sql
|
||
CREATE TABLE document_number_config_history (
|
||
id INT AUTO_INCREMENT PRIMARY KEY,
|
||
config_id INT NOT NULL,
|
||
template_before TEXT,
|
||
template_after TEXT NOT NULL,
|
||
changed_by INT NOT NULL,
|
||
changed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
change_reason TEXT,
|
||
|
||
FOREIGN KEY (config_id) REFERENCES document_number_configs(id),
|
||
FOREIGN KEY (changed_by) REFERENCES users(id)
|
||
) ENGINE=InnoDB COMMENT='Template Change History';
|
||
```
|
||
|
||
**Audit Trail Implementation**:
|
||
|
||
```typescript
|
||
@Injectable()
|
||
export class ConfigHistoryService {
|
||
async recordChange(
|
||
configId: number,
|
||
oldTemplate: string,
|
||
newTemplate: string,
|
||
userId: number,
|
||
reason: string
|
||
): Promise<void> {
|
||
await this.historyRepo.save({
|
||
configId,
|
||
templateBefore: oldTemplate,
|
||
templateAfter: newTemplate,
|
||
changedBy: userId,
|
||
changeReason: reason
|
||
});
|
||
}
|
||
|
||
async rollback(configId: number, historyId: number): Promise<void> {
|
||
const history = await this.historyRepo.findOne({ where: { id: historyId }});
|
||
await this.configService.update(configId, {
|
||
template: history.templateBefore
|
||
});
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.11.7.3. Counter Reset Policy
|
||
|
||
**Automatic Reset**:
|
||
|
||
- **Yearly Reset**: ทุกวันที่ 1 มกราคม (00:00:00 ICT)
|
||
- ใช้ **BullMQ Cron Job**:
|
||
|
||
```typescript
|
||
// src/document-numbering/jobs/counter-reset.job.ts
|
||
@Processor('document-numbering')
|
||
export class CounterResetJob {
|
||
@Cron('0 0 1 1 *') // 1 Jan every year
|
||
async handleYearlyReset() {
|
||
const newYear = new Date().getFullYear();
|
||
|
||
// ไม่ต้อง reset counter เพราะ counter แยกตาม current_year อยู่แล้ว
|
||
// แค่เตรียม counter สำหรับปีใหม่
|
||
this.logger.log(`Year changed to ${newYear}, counters ready`);
|
||
}
|
||
}
|
||
```
|
||
|
||
**Manual Reset** (Admin only):
|
||
|
||
```typescript
|
||
// POST /api/v1/document-numbering/configs/:configId/reset-counter
|
||
@Post('configs/:configId/reset-counter')
|
||
@Roles('SUPER_ADMIN')
|
||
@RequireApproval() // Custom decorator: ต้อง approve จาก 2 admins
|
||
async resetCounter(
|
||
@Param('configId') configId: number,
|
||
@Body() dto: ResetCounterDto
|
||
): Promise<void> {
|
||
// Validate reason
|
||
if (!dto.reason || dto.reason.length < 20) {
|
||
throw new BadRequestException('ต้องระบุเหตุผลอย่างน้อย 20 ตัวอักษร');
|
||
}
|
||
|
||
// Audit log
|
||
await this.auditService.logCounterReset({
|
||
configId,
|
||
userId: req.user.id,
|
||
reason: dto.reason,
|
||
previousValue: counter.lastNumber
|
||
});
|
||
|
||
// Reset
|
||
await this.counterService.reset(configId);
|
||
}
|
||
|
||
## 3.11.8. Audit Trail
|
||
|
||
### 3.11.8.1. การบันทึก Audit Log
|
||
|
||
**Database Table**: `document_number_audit`
|
||
|
||
```sql
|
||
CREATE TABLE document_number_audit (
|
||
id BIGINT AUTO_INCREMENT PRIMARY KEY,
|
||
document_id INT NOT NULL,
|
||
generated_number VARCHAR(100) NOT NULL,
|
||
counter_key JSON NOT NULL COMMENT 'Counter key used (JSON format)',
|
||
template_used VARCHAR(200) NOT NULL,
|
||
user_id INT NOT NULL,
|
||
ip_address VARCHAR(45),
|
||
user_agent TEXT,
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
|
||
-- Performance & Error Tracking
|
||
retry_count INT DEFAULT 0,
|
||
lock_wait_ms INT COMMENT 'Lock acquisition time in milliseconds',
|
||
total_duration_ms INT COMMENT 'Total generation time',
|
||
fallback_used ENUM('NONE', 'DB_LOCK', 'RETRY') DEFAULT 'NONE',
|
||
|
||
INDEX idx_document_id (document_id),
|
||
INDEX idx_user_id (user_id),
|
||
INDEX idx_created_at (created_at),
|
||
FOREIGN KEY (document_id) REFERENCES documents(id) ON DELETE CASCADE,
|
||
FOREIGN KEY (user_id) REFERENCES users(id)
|
||
) ENGINE=InnoDB COMMENT='Document Number Generation Audit Trail';
|
||
```
|
||
|
||
**Audit Service Implementation**:
|
||
|
||
```typescript
|
||
// src/document-numbering/services/audit.service.ts
|
||
import { Injectable } from '@nestjs/common';
|
||
import { InjectRepository } from '@nestjs/typeorm';
|
||
|
||
@Injectable()
|
||
export class DocumentNumberAuditService {
|
||
async logGeneration(data: AuditLogData): Promise<void> {
|
||
await this.auditRepo.save({
|
||
documentId: data.documentId,
|
||
generatedNumber: data.number,
|
||
counterKey: JSON.stringify(data.counterKey),
|
||
templateUsed: data.template,
|
||
userId: data.userId,
|
||
ipAddress: data.ipAddress,
|
||
userAgent: data.userAgent,
|
||
retryCount: data.retryCount ?? 0,
|
||
lockWaitMs: data.lockWaitMs,
|
||
totalDurationMs: data.totalDurationMs,
|
||
fallbackUsed: data.fallbackUsed ?? 'NONE'
|
||
});
|
||
}
|
||
}
|
||
```
|
||
|
||
**Usage in Service**:
|
||
|
||
```typescript
|
||
@Injectable()
|
||
export class DocumentNumberingService {
|
||
async generateDocumentNumber(dto: GenerateNumberDto, req: Request) {
|
||
const startTime = Date.now();
|
||
let lockWaitMs = 0;
|
||
let retryCount = 0;
|
||
let fallbackUsed = 'NONE';
|
||
|
||
try {
|
||
// ... generate logic ...
|
||
const number = await this.doGenerate(dto);
|
||
|
||
// Audit log
|
||
await this.auditService.logGeneration({
|
||
documentId: dto.documentId,
|
||
number,
|
||
counterKey: dto.counterKey,
|
||
template: config.template,
|
||
userId: req.user.id,
|
||
ipAddress: req.ip,
|
||
userAgent: req.headers['user-agent'],
|
||
retryCount,
|
||
lockWaitMs,
|
||
totalDurationMs: Date.now() - startTime,
|
||
fallbackUsed
|
||
});
|
||
|
||
return number;
|
||
} catch (error) {
|
||
// Log error separately
|
||
await this.errorLogService.log(error, dto);
|
||
throw error;
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.11.8.2. Conflict & Error Logging
|
||
|
||
**Separate Error Log Table**: `document_number_errors`
|
||
|
||
```sql
|
||
CREATE TABLE document_number_errors (
|
||
id BIGINT AUTO_INCREMENT PRIMARY KEY,
|
||
error_type ENUM(
|
||
'LOCK_TIMEOUT',
|
||
'VERSION_CONFLICT',
|
||
'DB_ERROR',
|
||
'REDIS_ERROR',
|
||
'VALIDATION_ERROR'
|
||
) NOT NULL,
|
||
error_message TEXT,
|
||
stack_trace TEXT,
|
||
context_data JSON COMMENT 'Request context (user, project, etc.)',
|
||
user_id INT,
|
||
ip_address VARCHAR(45),
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
resolved_at TIMESTAMP NULL,
|
||
|
||
INDEX idx_error_type (error_type),
|
||
INDEX idx_created_at (created_at),
|
||
INDEX idx_user_id (user_id)
|
||
) ENGINE=InnoDB COMMENT='Document Numbering Error Log';
|
||
```
|
||
|
||
**Error Logging Service**:
|
||
|
||
```typescript
|
||
@Injectable()
|
||
export class ErrorLogService {
|
||
async log(error: Error, context: any): Promise<void> {
|
||
const errorType = this.classifyError(error);
|
||
|
||
await this.errorRepo.save({
|
||
errorType,
|
||
errorMessage: error.message,
|
||
stackTrace: error.stack,
|
||
contextData: JSON.stringify(context),
|
||
userId: context.userId,
|
||
ipAddress: context.ipAddress
|
||
});
|
||
|
||
// Alert if critical
|
||
if (this.isCritical(errorType)) {
|
||
await this.alertService.sendAlert({
|
||
severity: 'CRITICAL',
|
||
title: `Document Numbering Error: ${errorType}`,
|
||
details: error.message
|
||
});
|
||
}
|
||
}
|
||
|
||
private classifyError(error: Error): string {
|
||
if (error instanceof LockTimeoutError) return 'LOCK_TIMEOUT';
|
||
if (error instanceof OptimisticLockVersionMismatchError) return 'VERSION_CONFLICT';
|
||
if (error instanceof QueryFailedError) return 'DB_ERROR';
|
||
if (error instanceof RedisConnectionError) return 'REDIS_ERROR';
|
||
return 'UNKNOWN';
|
||
}
|
||
}
|
||
|
||
## 3.11.9. Performance Requirements
|
||
|
||
### 3.11.9.1. Response Time
|
||
|
||
**Target Response Times**:
|
||
- **95th percentile**: ≤ 2 วินาที
|
||
- **99th percentile**: ≤ 5 วินาที
|
||
- **Normal operation** (ไม่มี retry): ≤ 500ms
|
||
|
||
**Performance Optimization Strategies**:
|
||
|
||
```typescript
|
||
// 1. Database Connection Pooling
|
||
{
|
||
type: 'mysql',
|
||
extra: {
|
||
connectionLimit: 20, // Pool size
|
||
queueLimit: 0, // Unlimited queue
|
||
acquireTimeout: 10000 // 10s timeout
|
||
}
|
||
}
|
||
|
||
// 2. Redis Connection Pooling
|
||
import IORedis from 'ioredis';
|
||
|
||
const redis = new IORedis({
|
||
host: process.env.REDIS_HOST,
|
||
port: parseInt(process.env.REDIS_PORT),
|
||
maxRetriesPerRequest: 3,
|
||
enableReadyCheck: true,
|
||
lazyConnect: false,
|
||
// Connection pool
|
||
poolSize: 10
|
||
});
|
||
|
||
// 3. Query Optimization
|
||
// ใช้ Index-covered queries
|
||
const counter = await this.counterRepo
|
||
.createQueryBuilder('c')
|
||
.where('c.project_id = :projectId', { projectId })
|
||
.andWhere('c.correspondence_type_id = :typeId', { typeId })
|
||
.andWhere('c.current_year = :year', { year })
|
||
.useIndex('idx_counter_lookup') // Force index usage
|
||
.getOne();
|
||
```
|
||
|
||
**Performance Monitoring**:
|
||
|
||
```typescript
|
||
// Prometheus metrics
|
||
import { Counter, Histogram } from 'prom-client';
|
||
|
||
const generationDuration = new Histogram({
|
||
name: 'docnum_generation_duration_seconds',
|
||
help: 'Document number generation duration',
|
||
labelNames: ['project', 'type', 'status'],
|
||
buckets: [0.1, 0.5, 1, 2, 5, 10]
|
||
});
|
||
|
||
// Usage
|
||
const timer = generationDuration.startTimer();
|
||
try {
|
||
const number = await this.generate(dto);
|
||
timer({ status: 'success' });
|
||
} catch (error) {
|
||
timer({ status: 'error' });
|
||
throw error;
|
||
}
|
||
```
|
||
|
||
### 3.11.9.2. Throughput
|
||
|
||
**Capacity Requirements**:
|
||
|
||
- **Normal load**: ≥ 50 requests/second
|
||
- **Peak load**: ≥ 100 requests/second (ช่วงเร่งงาน)
|
||
- **Burst capacity**: ≥ 200 requests/second (short duration)
|
||
|
||
**Load Balancing Strategy**:
|
||
|
||
```yaml
|
||
# docker-compose.yml
|
||
services:
|
||
backend:
|
||
image: lcbp3-backend:latest
|
||
deploy:
|
||
replicas: 3 # 3 instances
|
||
resources:
|
||
limits:
|
||
cpus: '1.0'
|
||
memory: 1G
|
||
reservations:
|
||
cpus: '0.5'
|
||
memory: 512M
|
||
|
||
nginx:
|
||
image: nginx:alpine
|
||
volumes:
|
||
- ./nginx.conf:/etc/nginx/nginx.conf
|
||
ports:
|
||
- "80:80"
|
||
```
|
||
|
||
```nginx
|
||
# nginx.conf - Load Balancing Configuration
|
||
upstream backend {
|
||
least_conn; # Least connections algorithm
|
||
server backend:3000 max_fails=3 fail_timeout=30s;
|
||
server backend:3001 max_fails=3 fail_timeout=30s;
|
||
server backend:3002 max_fails=3 fail_timeout=30s;
|
||
}
|
||
|
||
server {
|
||
location /api/v1/documents/ {
|
||
proxy_pass http://backend;
|
||
proxy_next_upstream error timeout;
|
||
proxy_connect_timeout 10s;
|
||
proxy_read_timeout 30s;
|
||
}
|
||
}
|
||
```
|
||
|
||
**Rate Limiting**:
|
||
|
||
```typescript
|
||
// ใช้ @nestjs/throttler
|
||
import { ThrottlerGuard } from '@nestjs/throttler';
|
||
|
||
@Controller('document-numbering')
|
||
@UseGuards(ThrottlerGuard)
|
||
export class DocumentNumberingController {
|
||
@Throttle(10, 60) // 10 requests per 60 seconds per user
|
||
@Post('generate')
|
||
async generate(@Body() dto: GenerateNumberDto) {
|
||
return await this.service.generate(dto);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.11.9.3. Availability
|
||
|
||
**SLA Targets**:
|
||
|
||
- **Uptime**: ≥ 99.5% (excluding planned maintenance)
|
||
- **Maximum downtime**: ≤ 3.6 ชั่วโมง/เดือน
|
||
- **Recovery Time Objective (RTO)**: ≤ 30 นาที
|
||
- **Recovery Point Objective (RPO)**: ≤ 5 นาที
|
||
|
||
**High Availability Setup**:
|
||
|
||
```yaml
|
||
# High Availability Architecture
|
||
services:
|
||
# MariaDB - Master/Replica
|
||
mariadb-master:
|
||
image: mariadb:10.11
|
||
environment:
|
||
MYSQL_REPLICATION_MODE: master
|
||
|
||
mariadb-replica:
|
||
image: mariadb:10.11
|
||
environment:
|
||
MYSQL_REPLICATION_MODE: slave
|
||
MYSQL_MASTER_HOST: mariadb-master
|
||
|
||
# Redis - Sentinel Mode
|
||
redis-master:
|
||
image: redis:7-alpine
|
||
command: redis-server --appendonly yes
|
||
|
||
redis-replica:
|
||
image: redis:7-alpine
|
||
command: redis-server --replicaof redis-master 6379
|
||
|
||
redis-sentinel:
|
||
image: redis:7-alpine
|
||
command: >
|
||
redis-sentinel /etc/redis/sentinel.conf
|
||
--sentinel monitor mymaster redis-master 6379 2
|
||
```
|
||
|
||
**Health Checks**:
|
||
|
||
```typescript
|
||
// src/health/health.controller.ts
|
||
import { HealthCheck, HealthCheckService, TypeOrmHealthIndicator } from '@nestjs/terminus';
|
||
|
||
@Controller('health')
|
||
export class HealthController {
|
||
@Get()
|
||
@HealthCheck()
|
||
check() {
|
||
return this.health.check([
|
||
() => this.db.pingCheck('database'),
|
||
() => this.redis.pingCheck('redis'),
|
||
() => this.customHealthCheck()
|
||
]);
|
||
}
|
||
|
||
private async customHealthCheck() {
|
||
// ทดสอบ generate document number
|
||
const canGenerate = await this.testGeneration();
|
||
return { documentNumbering: { status: canGenerate ? 'up' : 'down' }};
|
||
}
|
||
}
|
||
|
||
## 3.11.10. Monitoring & Alerting
|
||
|
||
### 3.11.10.1. Metrics Collection
|
||
|
||
**Prometheus Metrics Implementation**:
|
||
|
||
```typescript
|
||
// src/document-numbering/metrics/metrics.service.ts
|
||
import { Injectable } from '@nestjs/common';
|
||
import { Counter, Histogram, Gauge } from 'prom-client';
|
||
|
||
@Injectable()
|
||
export class DocumentNumberingMetrics {
|
||
// Lock acquisition metrics
|
||
private lockAcquisitionDuration = new Histogram({
|
||
name: 'docnum_lock_acquisition_duration_ms',
|
||
help: 'Lock acquisition time in milliseconds',
|
||
labelNames: ['project', 'type'],
|
||
buckets: [10, 50, 100, 200, 500, 1000, 2000, 5000]
|
||
});
|
||
|
||
private lockAcquisitionFailures = new Counter({
|
||
name: 'docnum_lock_acquisition_failures_total',
|
||
help: 'Total number of lock acquisition failures',
|
||
labelNames: ['project', 'type', 'reason']
|
||
});
|
||
|
||
// Generation metrics
|
||
private generationDuration = new Histogram({
|
||
name: 'docnum_generation_duration_ms',
|
||
help: 'Total document number generation time',
|
||
labelNames: ['project', 'type', 'status'],
|
||
buckets: [100, 200, 500, 1000, 2000, 5000]
|
||
});
|
||
|
||
private retryCount = new Histogram({
|
||
name: 'docnum_retry_count',
|
||
help: 'Number of retries per generation',
|
||
labelNames: ['project', 'type'],
|
||
buckets: [0, 1, 2, 3, 5, 10]
|
||
});
|
||
|
||
// Connection health
|
||
private redisConnectionStatus = new Gauge({
|
||
name: 'docnum_redis_connection_status',
|
||
help: 'Redis connection status (1=up, 0=down)'
|
||
});
|
||
|
||
private dbConnectionPoolUsage = new Gauge({
|
||
name: 'docnum_db_connection_pool_usage',
|
||
help: 'Database connection pool usage percentage'
|
||
});
|
||
}
|
||
```
|
||
|
||
### 3.11.10.2. Alert Rules
|
||
|
||
**Prometheus Alert Rules** (`prometheus/alerts.yml`):
|
||
|
||
```yaml
|
||
groups:
|
||
- name: document_numbering_alerts
|
||
interval: 30s
|
||
rules:
|
||
# CRITICAL: Redis unavailable
|
||
- alert: RedisUnavailable
|
||
expr: docnum_redis_connection_status == 0
|
||
for: 1m
|
||
labels:
|
||
severity: critical
|
||
component: document-numbering
|
||
annotations:
|
||
summary: "Redis is unavailable for document numbering"
|
||
description: "System is falling back to DB-only locking"
|
||
|
||
# CRITICAL: High lock failure rate
|
||
- alert: HighLockFailureRate
|
||
expr: |
|
||
rate(docnum_lock_acquisition_failures_total[5m]) > 0.1
|
||
for: 5m
|
||
labels:
|
||
severity: critical
|
||
annotations:
|
||
summary: "Lock acquisition failure rate > 10%"
|
||
description: "Check Redis and database performance"
|
||
|
||
# WARNING: Elevated lock failure rate
|
||
- alert: ElevatedLockFailureRate
|
||
expr: |
|
||
rate(docnum_lock_acquisition_failures_total[5m]) > 0.05
|
||
for: 5m
|
||
labels:
|
||
severity: warning
|
||
annotations:
|
||
summary: "Lock acquisition failure rate > 5%"
|
||
|
||
# WARNING: Slow lock acquisition
|
||
- alert: SlowLockAcquisition
|
||
expr: |
|
||
histogram_quantile(0.95,
|
||
rate(docnum_lock_acquisition_duration_ms_bucket[5m])
|
||
) > 1000
|
||
for: 5m
|
||
labels:
|
||
severity: warning
|
||
annotations:
|
||
summary: "P95 lock acquisition time > 1 second"
|
||
|
||
# WARNING: High retry count
|
||
- alert: HighRetryCount
|
||
expr: |
|
||
sum by (project) (
|
||
rate(docnum_retry_count_sum[1h])
|
||
) > 100
|
||
for: 1h
|
||
labels:
|
||
severity: warning
|
||
annotations:
|
||
summary: "Retry count > 100 per hour in project {{ $labels.project }}"
|
||
|
||
# WARNING: Slow generation
|
||
- alert: SlowDocumentNumberGeneration
|
||
expr: |
|
||
histogram_quantile(0.95,
|
||
rate(docnum_generation_duration_ms_bucket[5m])
|
||
) > 2000
|
||
for: 5m
|
||
labels:
|
||
severity: warning
|
||
annotations:
|
||
summary: "P95 generation time > 2 seconds"
|
||
```
|
||
|
||
**AlertManager Configuration** (`alertmanager/config.yml`):
|
||
|
||
```yaml
|
||
route:
|
||
group_by: ['alertname', 'severity']
|
||
group_wait: 30s
|
||
group_interval: 5m
|
||
repeat_interval: 4h
|
||
receiver: 'ops-team'
|
||
routes:
|
||
# CRITICAL alerts → PagerDuty + Slack
|
||
- match:
|
||
severity: critical
|
||
receiver: 'pagerduty-critical'
|
||
continue: true
|
||
|
||
# WARNING alerts → Slack only
|
||
- match:
|
||
severity: warning
|
||
receiver: 'slack-warnings'
|
||
|
||
receivers:
|
||
- name: 'pagerduty-critical'
|
||
pagerduty_configs:
|
||
- service_key: <SERVICE_KEY>
|
||
description: '{{ .CommonAnnotations.summary }}'
|
||
|
||
- name: 'slack-warnings'
|
||
slack_configs:
|
||
- api_url: <SLACK_WEBHOOK>
|
||
channel: '#lcbp3-alerts'
|
||
title: '⚠️ {{ .GroupLabels.alertname }}'
|
||
text: '{{ .CommonAnnotations.description }}'
|
||
|
||
- name: 'ops-team'
|
||
email_configs:
|
||
- to: 'ops@example.com'
|
||
```
|
||
|
||
### 3.11.10.3. Grafana Dashboard
|
||
|
||
**Dashboard Configuration** (`grafana/dashboards/document-numbering.json`):
|
||
|
||
```json
|
||
{
|
||
"title": "Document Numbering Performance",
|
||
"panels": [
|
||
{
|
||
"title": "Lock Acquisition Success Rate",
|
||
"targets": [{
|
||
"expr": "1 - (rate(docnum_lock_acquisition_failures_total[5m]) / rate(docnum_lock_acquisition_total[5m]))"
|
||
}],
|
||
"type": "graph",
|
||
"gridPos": { "x": 0, "y": 0, "w": 12, "h": 8 }
|
||
},
|
||
{
|
||
"title": "Lock Acquisition Time (Percentiles)",
|
||
"targets": [
|
||
{
|
||
"expr": "histogram_quantile(0.50, rate(docnum_lock_acquisition_duration_ms_bucket[5m]))",
|
||
"legendFormat": "P50"
|
||
},
|
||
{
|
||
"expr": "histogram_quantile(0.95, rate(docnum_lock_acquisition_duration_ms_bucket[5m]))",
|
||
"legendFormat": "P95"
|
||
},
|
||
{
|
||
"expr": "histogram_quantile(0.99, rate(docnum_lock_acquisition_duration_ms_bucket[5m]))",
|
||
"legendFormat": "P99"
|
||
}
|
||
],
|
||
"type": "graph",
|
||
"gridPos": { "x": 12, "y": 0, "w": 12, "h": 8 }
|
||
},
|
||
{
|
||
"title": "Generation Rate (per minute)",
|
||
"targets": [{
|
||
"expr": "sum(rate(docnum_generation_duration_ms_count[1m])) * 60"
|
||
}],
|
||
"type": "stat",
|
||
"gridPos": { "x": 0, "y": 8, "w": 6, "h": 4 }
|
||
},
|
||
{
|
||
"title": "Redis Connection Status",
|
||
"targets": [{
|
||
"expr": "docnum_redis_connection_status"
|
||
}],
|
||
"type": "stat",
|
||
"gridPos": { "x": 6, "y": 8, "w": 6, "h": 4 },
|
||
"thresholds": {
|
||
"mode": "absolute",
|
||
"steps": [
|
||
{ "value": 0, "color": "red" },
|
||
{ "value": 1, "color": "green" }
|
||
]
|
||
}
|
||
},
|
||
{
|
||
"title": "Error Rate by Type",
|
||
"targets": [{
|
||
"expr": "sum by (reason) (rate(docnum_lock_acquisition_failures_total[5m]))"
|
||
}],
|
||
"type": "graph",
|
||
"gridPos": { "x": 12, "y": 8, "w": 12, "h": 8 }
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**Key Dashboard Panels**:
|
||
|
||
- **Lock Acquisition Success Rate**: Real-time success %
|
||
- **Lock Wait Time Percentiles**: P50, P95, P99 latency
|
||
- **Generation Rate**: Documents/minute
|
||
- **Error Breakdown**: By error type (LOCK_TIMEOUT, VERSION_CONFLICT, etc.)
|
||
- **Redis/DB Health**: Connection status
|
||
- **Retry Distribution**: Histogram of retry counts
|
||
|
||
## 3.11.12. API Reference
|
||
|
||
เอกสารนี้อ้างอิงถึง API endpoints ต่อไปนี้ (รายละเอียดใน `specs/02-architecture/api-design.md`):
|
||
|
||
- `POST /api/v1/documents/{documentId}/generate-number` - สร้างเลขที่เอกสาร
|
||
- `GET /api/v1/document-numbering/configs` - ดูการตั้งค่า template
|
||
- `PUT /api/v1/document-numbering/configs/{configId}` - แก้ไข template (Admin only)
|
||
- `POST /api/v1/document-numbering/configs/{configId}/reset-counter` - Reset counter (Admin only)
|
||
|
||
## 3.11.13. Database Schema Reference
|
||
|
||
เอกสารนี้อ้างอิงถึง tables ต่อไปนี้ (รายละเอียดใน `specs/04-data-dictionary/4_Data_Dictionary_V1_4_4.md`):
|
||
|
||
- `document_number_configs` - เก็บ template และ counter configuration
|
||
- `document_number_counters` - เก็บ current counter value
|
||
- `document_number_audit` - เก็บ audit trail
|
||
- `documents` - เก็บ document number ที่ถูกสร้าง
|
||
|
||
## 3.11.14. Database Schema Requirements
|
||
|
||
### 3.11.14.1. Counter Table Schema
|
||
|
||
ตาราง `document_number_counters` ต้องมีโครงสร้างดังนี้:
|
||
|
||
```sql
|
||
CREATE TABLE document_number_counters (
|
||
project_id INT NOT NULL,
|
||
originator_organization_id INT NOT NULL,
|
||
recipient_organization_id INT NULL, -- NULL for RFA
|
||
correspondence_type_id INT NOT NULL,
|
||
sub_type_id INT DEFAULT 0, -- for TRANSMITTAL
|
||
rfa_type_id INT DEFAULT 0, -- for RFA
|
||
discipline_id INT DEFAULT 0, -- for RFA
|
||
current_year INT NOT NULL,
|
||
version INT DEFAULT 0 NOT NULL, -- Optimistic Lock
|
||
last_number INT DEFAULT 0,
|
||
|
||
PRIMARY KEY (
|
||
project_id,
|
||
originator_organization_id,
|
||
COALESCE(recipient_organization_id, 0),
|
||
correspondence_type_id,
|
||
sub_type_id,
|
||
rfa_type_id,
|
||
discipline_id,
|
||
current_year
|
||
),
|
||
|
||
FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,
|
||
FOREIGN KEY (originator_organization_id) REFERENCES organizations(id) ON DELETE CASCADE,
|
||
FOREIGN KEY (recipient_organization_id) REFERENCES organizations(id) ON DELETE CASCADE,
|
||
FOREIGN KEY (correspondence_type_id) REFERENCES correspondence_types(id) ON DELETE CASCADE
|
||
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_general_ci
|
||
COMMENT = 'ตารางเก็บ Running Number Counters';
|
||
```
|
||
|
||
### 3.11.14.2. Index Requirements
|
||
|
||
```sql
|
||
-- Index สำหรับ Performance
|
||
CREATE INDEX idx_counter_lookup
|
||
ON document_number_counters (
|
||
project_id,
|
||
correspondence_type_id,
|
||
current_year
|
||
);
|
||
|
||
-- Index สำหรับ Originator lookup
|
||
CREATE INDEX idx_counter_org
|
||
ON document_number_counters (
|
||
originator_organization_id,
|
||
current_year
|
||
);
|
||
```
|
||
|
||
### 3.11.14.3. Important Notes
|
||
|
||
> **💡 Counter Key Design**
|
||
>
|
||
> - ใช้ `COALESCE(recipient_organization_id, 0)` ใน Primary Key เพื่อรองรับ NULL
|
||
> - `version` column สำหรับ Optimistic Locking (ป้องกัน race condition)
|
||
> - `last_number` เริ่มจาก 0 และเพิ่มขึ้นทีละ 1
|
||
> - Counter reset ทุกปี (เมื่อ `current_year` เปลี่ยน)
|
||
|
||
> **⚠️ Migration Notes**
|
||
>
|
||
> - ไม่มีข้อมูลเก่า ไม่ต้องทำ backward compatibility
|
||
> - สามารถสร้าง table ใหม่ได้เลยตาม schema ข้างต้น
|
||
> - ต้องมี seed data สำหรับ `correspondence_types`, `rfa_types`, `disciplines` ก่อน
|
||
|
||
### 3.11.14.4. Example Counter Records
|
||
|
||
```sql
|
||
-- Example: LETTER from คคง. to สคฉ.3 in LCBP3-C2 year 2025
|
||
INSERT INTO document_number_counters (
|
||
project_id, originator_organization_id, recipient_organization_id,
|
||
correspondence_type_id, sub_type_id, rfa_type_id, discipline_id,
|
||
current_year, version, last_number
|
||
) VALUES (
|
||
2, -- LCBP3-C2
|
||
22, -- คคง.
|
||
10, -- สคฉ.3
|
||
6, -- LETTER
|
||
0, 0, 0,
|
||
2025, 0, 0
|
||
);
|
||
|
||
-- Example: RFA from ผรม.2 in LCBP3-C2, discipline TER, type RPT, year 2025
|
||
INSERT INTO document_number_counters (
|
||
project_id, originator_organization_id, recipient_organization_id,
|
||
correspondence_type_id, sub_type_id, rfa_type_id, discipline_id,
|
||
current_year, version, last_number
|
||
) VALUES (
|
||
2, -- LCBP3-C2
|
||
42, -- ผรม.2
|
||
NULL, -- RFA ไม่มี specific recipient
|
||
1, -- RFA
|
||
0,
|
||
18, -- RPT (Report)
|
||
5, -- TER (Terminal)
|
||
2025, 0, 0
|
||
);
|
||
```
|
||
|
||
## 3.11.15. Security Considerations
|
||
|
||
### 3.11.14.1. Authorization
|
||
|
||
- เฉพาะ authenticated users เท่านั้นที่สามารถ request document number
|
||
- เฉพาะ Project Admin เท่านั้นที่แก้ไข template ได้
|
||
- เฉพาะ Super Admin เท่านั้นที่ reset counter ได้
|
||
|
||
### 3.11.14.2. Rate Limiting
|
||
|
||
- Limit ต่อ user: **10 requests/minute** (prevent abuse)
|
||
- Limit ต่อ IP: **50 requests/minute**
|
||
|
||
### 3.11.14.3. Audit & Compliance
|
||
|
||
- บันทึกทุก API call ที่เกี่ยวข้องกับ document numbering
|
||
- เก็บ audit log อย่างน้อย **7 ปี** (ตาม พ.ร.บ. ข้อมูลอิเล็กทรอนิกส์)
|