251217:1704 Docunment Number: Update to 1.6.2

2025-12-17 17:04:06 +07:00
parent 48ed74a27b
commit aaa5da3ec1
121 changed files with 8072 additions and 2103 deletions
--- a/specs/06-tasks/TASK-FE-017-document-numbering-refactor.md
+++ b/specs/06-tasks/TASK-FE-017-document-numbering-refactor.md
@@ -0,0 +1,192 @@
+# TASK-FE-017: Document Numbering Frontend Refactor
+
+---
+status: TODO
+priority: HIGH
+estimated_effort: 2-3 days
+dependencies:
+  - TASK-BE-017-document-numbering-refactor.md
+  - specs/01-requirements/03.11-document-numbering.md (v1.6.2)
+  - specs/03-implementation/document-numbering.md (v1.6.2)
+---
+
+## Objective
+
+Refactor Frontend Document Numbering ตาม specification v1.6.2:
+- ป้องกัน User แก้ไขเลขที่เอกสาร
+- สร้าง Admin Dashboard ด้วย Metrics
+- Implement Admin Tools (Manual Override, Void/Replace)
+
+---
+
+## Implementation Checklist
+
+### 1. User Mode Forms (Create/Edit)
+
+#### 1.1 Correspondence Form
+- [ ] **Create Mode**: แสดง "Auto Generated" หรือ Preview เลขที่เอกสาร
+- [ ] **Edit Mode**: ช่อง Document No เป็น **Read-Only** เสมอ
+- [ ] **API Integration**: ตัดการส่ง field `documentNumber` ไป Backend ใน Edit mode
+
+#### 1.2 RFA Form
+- [ ] Same as above - Read-Only document number
+
+#### 1.3 Transmittal Form
+- [ ] Same as above - Read-Only document number
+
+**Files:**
+- `frontend/components/correspondences/form.tsx`
+- `frontend/components/rfas/form.tsx`
+- `frontend/components/transmittals/form.tsx`
+
+---
+
+### 2. Admin Dashboard (`/admin/numbering`)
+
+#### 2.1 Tab Structure
+```
+/admin/numbering
+├── Templates (existing - keep as is)
+├── Metrics & Audit (NEW)
+└── Admin Tools (NEW)
+```
+
+#### 2.2 Templates Tab (Existing)
+- [ ] Keep current functionality
+- [ ] เป็น Tab แรก (default)
+
+#### 2.3 Metrics & Audit Tab (NEW)
+- [ ] Fetch metrics from `GET /admin/document-numbering/metrics`
+- [ ] Display:
+  - Sequence utilization gauge
+  - Lock wait time chart
+  - Generation rate chart
+  - Recent errors table
+  - Audit logs table with filters
+
+#### 2.4 Admin Tools Tab (NEW)
+- [ ] **Manual Override Form**:
+  - Input: document_type, document_number, reason
+  - Calls `POST /admin/document-numbering/manual-override`
+
+- [ ] **Void & Replace Form**:
+  - Input: document_id, reason
+  - Calls `POST /admin/document-numbering/void-and-replace`
+
+- [ ] **Bulk Import Form**:
+  - Upload CSV/Excel file
+  - Preview before import
+  - Calls `POST /admin/document-numbering/bulk-import`
+
+---
+
+### 3. API Integration
+
+#### 3.1 New API Endpoints
+```typescript
+// services/document-numbering.service.ts (frontend)
+
+interface NumberingMetrics {
+  sequenceUtilization: number;
+  lockWaitTimeP95: number;
+  generationRate: number;
+  recentErrors: ErrorEntry[];
+}
+
+// GET /admin/document-numbering/metrics
+getMetrics(): Promise<NumberingMetrics>
+
+// POST /admin/document-numbering/manual-override
+manualOverride(dto: ManualOverrideDto): Promise<void>
+
+// POST /admin/document-numbering/void-and-replace
+voidAndReplace(dto: VoidReplaceDto): Promise<{ newDocumentNumber: string }>
+
+// POST /admin/document-numbering/bulk-import
+bulkImport(file: File): Promise<ImportResult>
+
+// GET /document-numbering/logs/audit
+getAuditLogs(params: AuditQueryParams): Promise<PaginatedAuditLogs>
+```
+
+#### 3.2 DTOs
+```typescript
+interface ManualOverrideDto {
+  documentType: string;
+  documentNumber: string;
+  reason: string;
+}
+
+interface VoidReplaceDto {
+  documentId: number;
+  reason: string;
+}
+
+interface AuditQueryParams {
+  operation?: 'RESERVE' | 'CONFIRM' | 'CANCEL' | 'MANUAL_OVERRIDE' | 'VOID' | 'GENERATE';
+  dateFrom?: string;
+  dateTo?: string;
+  userId?: number;
+  page?: number;
+  limit?: number;
+}
+```
+
+---
+
+### 4. Components to Create
+
+| Component          | Path                                            | Description                 |
+| ------------------ | ----------------------------------------------- | --------------------------- |
+| MetricsDashboard   | `components/numbering/metrics-dashboard.tsx`    | Metrics charts and gauges   |
+| AuditLogsTable     | `components/numbering/audit-logs-table.tsx`     | Filterable audit log viewer |
+| ManualOverrideForm | `components/numbering/manual-override-form.tsx` | Admin tool form             |
+| VoidReplaceForm    | `components/numbering/void-replace-form.tsx`    | Admin tool form             |
+| BulkImportForm     | `components/numbering/bulk-import-form.tsx`     | CSV/Excel uploader          |
+
+---
+
+### 5. UI/UX Requirements
+
+#### 5.1 Document Number Display
+- ใช้ Badge หรือ Chip style สำหรับ Document Number
+- สี: Info (blue) สำหรับ Auto-generated
+- สี: Warning (amber) สำหรับ Manual Override
+- สี: Destructive (red) สำหรับ Voided
+
+#### 5.2 Admin Tools Access Control
+- ซ่อน Admin Tools tab สำหรับ users ที่ไม่มี permission `system.manage_settings`
+- แสดง confirmation dialog ก่อน Manual Override / Void
+
+---
+
+## Files to Create/Modify
+
+| Action | Path                                                     |
+| ------ | -------------------------------------------------------- |
+| MODIFY | `frontend/app/(admin)/admin/numbering/page.tsx`          |
+| CREATE | `frontend/components/numbering/metrics-dashboard.tsx`    |
+| CREATE | `frontend/components/numbering/audit-logs-table.tsx`     |
+| CREATE | `frontend/components/numbering/manual-override-form.tsx` |
+| CREATE | `frontend/components/numbering/void-replace-form.tsx`    |
+| CREATE | `frontend/components/numbering/bulk-import-form.tsx`     |
+| MODIFY | `frontend/services/document-numbering.service.ts`        |
+| MODIFY | `frontend/components/correspondences/form.tsx`           |
+
+---
+
+## Acceptance Criteria
+
+- [ ] Document Number เป็น Read-Only ใน Edit mode ทุก form
+- [ ] Admin Dashboard แสดง Metrics ได้ถูกต้อง
+- [ ] Manual Override ทำงานได้และบันทึก Audit
+- [ ] Void/Replace สร้างเลขใหม่และ link กับเอกสารเดิม
+- [ ] Permission check ถูกต้องสำหรับ Admin Tools
+
+---
+
+## References
+
+- [Requirements v1.6.2](file:///d:/nap-dms.lcbp3/specs/01-requirements/03.11-document-numbering.md)
+- [Frontend Guidelines](file:///d:/nap-dms.lcbp3/specs/03-implementation/frontend-guidelines.md)
+- [REQ-009 Original Task](file:///d:/nap-dms.lcbp3/specs/06-tasks/REQ-009-DocumentNumbering.md)