commit

plans/training-record-submit.md

@@ -0,0 +1,830 @@
+# Training Record Draft Submit Workflow Review & Fix
+
+## Objective
+
+ตรวจสอบ วิเคราะห์ และแก้ไขปัญหา Workflow ของการส่งประวัติการอบรม (Training Record) จากสถานะ "ฉบับร่าง (Draft)" ไปเป็น "รอตรวจสอบ (Pending Review)"
+
+ปัจจุบันพบ Runtime Error
+
+```
+พนักงานสามารถอัปโหลดเอกสารได้เฉพาะรายการที่อยู่ในสถานะฉบับร่างหรือขอแก้ไขเท่านั้น
+```
+
+**ห้ามแก้ไขจากการคาดเดา**
+
+ต้องตรวจสอบ Source Code และลำดับการทำงานจริงก่อนทุกครั้ง
+
+---
+
+# Project Rules
+
+ก่อนแก้ไขให้ปฏิบัติตาม
+
+- AGENTS.md
+- docs/AI_DEVELOPMENT_GUIDE.md
+- docs/PROJECT_ARCHITECTURE.md
+
+ห้ามสร้าง Pattern ใหม่ หากระบบเดิมมี Pattern รองรับอยู่แล้ว
+
+Reuse
+
+- Shared Components
+- Shared Services
+- Shared Mutations
+- Shared Queries
+- Shared Hooks
+- Shared Upload Components
+
+---
+
+# Scope (Mandatory)
+
+การตรวจสอบและแก้ไข **ต้องครอบคลุมทั้งระบบ**
+
+ห้ามตรวจสอบหรือแก้ไขเฉพาะ
+
+```
+Training Record ID = 277
+```
+
+Record 277 เป็นเพียงตัวอย่างที่พบปัญหาเท่านั้น
+
+ต้องตรวจสอบทุก Workflow ที่เกี่ยวข้องกับ
+
+- Create Training Record
+- Save Draft
+- Edit Draft
+- Submit Draft
+- Revision Requested
+- Re-submit
+- Upload Certificate
+- Upload Supporting Files
+- Remove Files
+- HRD Review
+- Employee View
+
+ต้องยืนยันว่า Logic ทำงานถูกต้องกับทุก Record
+
+ห้าม
+
+- Hardcode Record ID
+- Hardcode Status
+- แก้ไขเฉพาะหน้าเดียว
+- แก้เฉพาะเคสตัวอย่าง
+
+การแก้ไขต้องอยู่ในระดับ
+
+- Shared Workflow
+- Shared Mutation
+- Shared Upload Logic
+- Shared Status Guard
+
+---
+
+# Current User Flow
+
+ผู้ใช้งานทำงานดังนี้
+
+```
+Create Training Record
+
+↓
+
+Save Draft
+
+↓
+
+Open Draft
+
+↓
+
+Edit
+
+↓
+
+Click "บันทึกประวัติการอบรม"
+
+↓
+
+Runtime Error
+```
+
+Backend ส่งข้อความ
+
+```
+พนักงานสามารถอัปโหลดเอกสารได้เฉพาะรายการที่อยู่ในสถานะฉบับร่างหรือขอแก้ไขเท่านั้น
+```
+
+---
+
+# Expected Workflow
+
+Workflow ที่ถูกต้องต้องเป็น
+
+```
+Create
+
+↓
+
+Save Draft
+
+↓
+
+Edit Draft
+
+↓
+
+Validate
+
+↓
+
+Save Form
+
+↓
+
+Upload Certificate
+
+↓
+
+Upload Supporting Files
+
+↓
+
+Verify Upload Success
+
+↓
+
+Update Status
+
+Draft
+
+↓
+
+Pending Review
+
+↓
+
+Refresh Query
+
+↓
+
+Redirect
+```
+
+ห้ามเปลี่ยน Status ก่อน Upload ทุกชนิดเสร็จ
+
+---
+
+# Mandatory Investigation
+
+## 1. Workflow Analysis
+
+ค้นหา
+
+- handleSubmit
+- onSubmit
+- submitTrainingRecord
+- updateTrainingRecord
+- saveTrainingRecord
+- uploadCertificate
+- uploadAttachment
+- saveDraft
+- submitDraft
+
+สร้าง Flow Diagram ปัจจุบัน
+
+เช่น
+
+```
+Save
+
+↓
+
+Update Status
+
+↓
+
+Upload
+```
+
+หรือ
+
+```
+Save
+
+↓
+
+Upload
+
+↓
+
+Update Status
+```
+
+---
+
+## 2. Execution Timeline
+
+ห้ามเดาจาก Error
+
+ต้องสร้าง Timeline จริง
+
+```
+User Click
+
+↓
+
+Validation
+
+↓
+
+Mutation A
+
+↓
+
+Mutation B
+
+↓
+
+Mutation C
+
+↓
+
+Upload
+
+↓
+
+Status Changed
+
+↓
+
+Redirect
+```
+
+ระบุ
+
+- API ไหนเรียกก่อน
+- API ไหนเรียกหลัง
+- API ไหน await
+- API ไหนทำงานพร้อมกัน
+
+---
+
+## 3. API Call Order
+
+ตรวจสอบทุก API
+
+เช่น
+
+```
+PATCH Training Record
+
+POST Certificate
+
+POST Attachment
+
+PATCH Status
+```
+
+สร้างลำดับจริง
+
+---
+
+## 4. React Query Analysis
+
+ตรวจสอบ
+
+- useMutation
+- mutate
+- mutateAsync
+- invalidateQueries
+- refetch
+- router.refresh
+- router.push
+- router.replace
+
+สร้าง Flow ของ Mutation
+
+---
+
+## 5. Async Analysis
+
+ตรวจสอบ
+
+- async
+- await
+- Promise.all
+- Promise.allSettled
+- Promise.any
+- queueMicrotask
+- setTimeout
+- background upload
+
+หากพบ
+
+ให้วิเคราะห์ผลกระทบต่อ Workflow
+
+---
+
+## 6. Race Condition Analysis
+
+ตรวจสอบว่ามี Race Condition หรือไม่
+
+ตัวอย่าง
+
+```
+PATCH Status
+
+────────────┐
+
+            ▼
+
+Pending Review
+
+            │
+
+            ▼
+
+POST Upload
+```
+
+หากพบ
+
+อธิบาย
+
+- สาเหตุ
+- หลักฐาน
+- วิธีแก้ไข
+
+---
+
+## 7. Upload Component Analysis
+
+ตรวจสอบ
+
+- CertificateUploader
+- AttachmentUploader
+- Dropzone
+- Upload Hook
+
+ว่ามี
+
+- Auto Upload
+- Upload On Mount
+- Upload After Save
+- Upload After State Change
+
+หรือไม่
+
+---
+
+## 8. Component Lifecycle
+
+ตรวจสอบ
+
+- useEffect
+- useMemo
+- useCallback
+
+ว่าทำให้ Upload หลัง Status เปลี่ยนหรือไม่
+
+---
+
+## 9. Backend Rule
+
+ตรวจสอบ Business Rule
+
+Backend อนุญาต Upload เฉพาะ
+
+- Draft
+- Revision Requested
+
+ห้ามแก้ไข Rule นี้
+
+ถือว่าเป็น Business Rule ที่ถูกต้อง
+
+Frontend ต้องทำงานให้สอดคล้องกับ Backend
+
+---
+
+# UI Review
+
+ตรวจสอบทุกหน้าที่เกี่ยวข้อง
+
+เมื่อ Status ไม่ใช่
+
+- Draft
+- Revision Requested
+
+ต้อง
+
+- Disable Upload
+- Disable Remove File
+- Disable Save Draft
+- Disable Submit
+
+หรือแสดงเป็น Readonly
+
+ห้ามเปิดให้ Upload แล้วปล่อยให้ Backend Reject
+
+---
+
+# Error Handling
+
+Runtime Error ต้องไม่เกิด
+
+ทุก Mutation
+
+ทุก Upload
+
+ทุก API
+
+ต้องมี
+
+```
+try/catch
+```
+
+หรือ
+
+```
+mutation.onError
+```
+
+แสดง
+
+- Toast
+- Inline Error
+
+แทน Runtime Error
+
+---
+
+# Validation
+
+ก่อน Submit
+
+ต้องผ่าน Validation ทั้งหมด
+
+หาก Validation ไม่ผ่าน
+
+- ไม่ Upload
+- ไม่ Submit
+- ไม่เปลี่ยน Status
+
+---
+
+# Required Fix
+
+หากพบ
+
+```
+Update Status
+
+↓
+
+Upload
+```
+
+ให้แก้เป็น
+
+```
+Validate
+
+↓
+
+Save Form
+
+↓
+
+Upload Certificate
+
+↓
+
+Upload Attachment
+
+↓
+
+Verify Upload Success
+
+↓
+
+Update Status
+
+↓
+
+Invalidate Query
+
+↓
+
+Redirect
+```
+
+---
+
+# Regression Test
+
+ทดสอบทุก Record
+
+ไม่ใช่เฉพาะ Record 277
+
+อย่างน้อย
+
+## Case 1
+
+Draft
+
+Create
+
+↓
+
+Save Draft
+
+↓
+
+Edit
+
+↓
+
+Submit
+
+Expected
+
+Success
+
+---
+
+## Case 2
+
+Draft
+
+Upload Certificate
+
+↓
+
+Submit
+
+Expected
+
+Success
+
+---
+
+## Case 3
+
+Draft
+
+Upload Multiple Attachments
+
+↓
+
+Submit
+
+Expected
+
+Success
+
+---
+
+## Case 4
+
+Revision Requested
+
+↓
+
+Edit
+
+↓
+
+Upload
+
+↓
+
+Submit
+
+Expected
+
+Success
+
+---
+
+## Case 5
+
+Pending Review
+
+↓
+
+Open
+
+Expected
+
+Readonly
+
+Upload Disabled
+
+---
+
+## Case 6
+
+Approved
+
+↓
+
+Open
+
+Expected
+
+Readonly
+
+---
+
+## Case 7
+
+Rejected
+
+↓
+
+Open
+
+Expected
+
+เป็นไปตาม Business Rule
+
+---
+
+## Case 8
+
+Existing Draft with Existing Files
+
+↓
+
+Edit
+
+↓
+
+Replace Files
+
+↓
+
+Submit
+
+Expected
+
+Success
+
+---
+
+## Case 9
+
+Existing Draft without Files
+
+↓
+
+Submit
+
+Expected
+
+ทำงานตาม Validation
+
+---
+
+## Case 10
+
+หลาย Record พร้อมกัน
+
+Draft A
+
+Draft B
+
+Draft C
+
+ต้องทำงานถูกต้องทุก Record
+
+---
+
+# Deliverables
+
+สร้างเอกสาร
+
+```
+docs/reports/training-record-submit-workflow-review.md
+```
+
+ประกอบด้วย
+
+## Executive Summary
+
+สรุปปัญหา
+
+---
+
+## Current Workflow
+
+Flow เดิม
+
+---
+
+## Expected Workflow
+
+Flow ใหม่
+
+---
+
+## Execution Timeline
+
+Timeline จริง
+
+---
+
+## API Call Sequence
+
+ลำดับ API
+
+---
+
+## React Query Flow
+
+Mutation ทั้งหมด
+
+---
+
+## Async Analysis
+
+await / Promise
+
+---
+
+## Race Condition Analysis
+
+พบหรือไม่
+
+หลักฐาน
+
+---
+
+## Upload Component Review
+
+ผลการตรวจสอบ
+
+---
+
+## Root Cause
+
+อธิบายสาเหตุที่แท้จริง
+
+พร้อมหลักฐาน
+
+ห้ามสรุปจากการคาดเดา
+
+---
+
+## Files Modified
+
+รายชื่อไฟล์ทั้งหมด
+
+พร้อมเหตุผล
+
+---
+
+## Risk Assessment
+
+ผลกระทบ
+
+- Employee
+- HRD
+- Admin
+
+---
+
+## Regression Test Result
+
+ผลการทดสอบทุก Case
+
+---
+
+## Remaining Issues
+
+สิ่งที่ควรปรับปรุงต่อ
+
+---
+
+# Constraints
+
+ห้าม
+
+- เปลี่ยน Business Rule ของ Backend
+- Hardcode Status
+- Hardcode Record ID
+- Hardcode Permission
+- สร้าง API ใหม่ หาก API เดิมรองรับ
+- เปลี่ยน Database Schema โดยไม่จำเป็น
+- เปลี่ยน Public Interface ของ Shared Component หากไม่มีเหตุผล
+
+ต้อง
+
+- Reuse Shared Components
+- Reuse Shared Services
+- Reuse Existing Pattern
+- รักษา Coding Style ของโปรเจค
+- แก้ไขที่ Root Cause ไม่ใช่แก้ปลายเหตุ
+- ตรวจสอบให้ครอบคลุมทั้งระบบ ไม่ใช่เฉพาะเคสตัวอย่าง