commit

2026-07-16 09:53:14 +07:00
parent 0fc112a2e8
commit 29cec708a3
1236 changed files with 212848 additions and 0 deletions
--- a/docs/review/employee-create-training-record-audit.md
+++ b/docs/review/employee-create-training-record-audit.md
@@ -0,0 +1,336 @@
+# Employee Create Training Record Audit Report
+
+## Executive Summary
+
+Overall Status:
+
+- Needs Improvement
+
+ภาพรวม:
+
+- flow สร้างประวัติการอบรมของ employee ใช้โครงสร้างหลักของโปรเจ็กต์ได้ดี ทั้ง route guard, shared form stack, minute-based duration input, local route handlers, และ server-side ownership checks
+- อย่างไรก็ดี implementation ปัจจุบันรองรับเพียงชุดข้อมูลพื้นฐานคือ employee, course, date, training type, duration, organizer, note, และ certificate upload หลัง create โดยยังไม่มีหลาย capability ที่ plan นี้คาดหวัง เช่น `location type`, `online URL`, `duplicate warning`, และ single-file certificate rule
+- จุดเสี่ยงหลักอยู่ที่ช่องว่างระหว่าง business requirement ในแผนกับ behavior จริงของหน้า create รวมถึงการ upload หลายไฟล์, การไม่มี duplicate warning, และ validation ที่ยังไม่ครอบคลุมบางกติกาเชิงธุรกิจ
+
+---
+
+## Scope Reviewed
+
+- Route/page:
+  - `src/app/dashboard/training-records/page.tsx`
+  - `src/app/dashboard/training-records/[trainingRecordId]/page.tsx`
+  - `src/lib/auth/page-guards.ts`
+- Form/components:
+  - `src/features/training-records/components/training-record-form.tsx`
+  - `src/features/training-records/components/training-record-view-page.tsx`
+  - `src/features/training-records/components/training-record-course-combobox.tsx`
+- Validation/types/query/mutation:
+  - `src/features/training-records/schemas/training-record.ts`
+  - `src/features/training-records/api/types.ts`
+  - `src/features/training-records/api/service.ts`
+  - `src/features/training-records/api/queries.ts`
+  - `src/features/training-records/api/mutations.ts`
+  - `src/features/training-records/api/certificate-mutations.ts`
+- API/server/security:
+  - `src/app/api/training-records/route.ts`
+  - `src/app/api/training-records/[id]/certificates/route.ts`
+  - `src/features/training-records/server/training-record-data.ts`
+  - `src/lib/certificate-storage.ts`
+- Navigation:
+  - `src/config/nav-config.ts`
+
+---
+
+## Functional Review
+
+| Feature | Status | Notes |
+| ------- | ------ | ----- |
+| Employee can open create page | Pass | ใช้ dynamic route `[trainingRecordId]` ค่า `new` ผ่าน `TrainingRecordViewPage` |
+| Employee can create own training record | Pass | form บังคับ employee ID จาก current user และ API เช็ก ownership ฝั่ง server |
+| Employee cannot create for another employee | Pass | UI ซ่อน employee selector สำหรับ employee และ API เช็ก `assertUserAndCourseAccess()` |
+| Course selection / custom course | Pass | รองรับเลือก course master หรือกรอกชื่อ course เอง |
+| Training date required | Pass | มี client schema validation |
+| Training hours hour/minute format | Pass | ใช้ `DurationPicker` และ validate 1-1800 นาที |
+| Training type required | Pass | มี select และ schema validation |
+| Provider / institute | Pass | ใช้ field `organizer` แบบ optional |
+| Note | Pass | รองรับเป็น optional textarea |
+| Upload certificate/evidence | Partial | รองรับ upload หลัง create แต่เป็น multi-file ไม่ใช่ single-file |
+| Submit loading state | Pass | ปุ่ม submit disabled ระหว่าง create/update/upload |
+| Submit success feedback | Pass | มี toast success และ redirect กลับ history |
+| Submit error feedback | Partial | มี toast จาก error.message แต่ยังไม่คัดข้อความให้เหมาะกับผู้ใช้เสมอ |
+| Redirect after submit | Pass | `router.push('/dashboard/training-records')` หลัง create สำเร็จ |
+| Created record status is pending | Pass | API set `approvalStatus: 'pending'` ตายตัว |
+| Employee cannot set K/S/A category | Pass | ไม่มี field ใน form/payload และ API ไม่รับจาก client |
+| Employee cannot set approval status | Pass | ไม่มี field ใน form/payload และ API set เอง |
+| Location type | Fail | ไม่มี field หรือ contract นี้ใน implementation |
+| Online URL | Fail | ไม่มี field หรือ validation นี้ใน implementation |
+| Duplicate training warning | Fail | ไม่พบ duplicate-check หรือ warning flow |
+
+---
+
+## Business Rule Review
+
+| Rule | Status | Notes |
+| ---- | ------ | ----- |
+| Employee submits training records for themselves only | Pass | server ownership check ผ่าน `assertUserAndCourseAccess()` |
+| Employee cannot edit HRD-only fields | Pass | form create ไม่มี category/status/review fields |
+| HRD assigns K/S/A later | Pass | category ถูกจัดการใน review flow เท่านั้น |
+| HRD verifies and approves later | Pass | create route บันทึกสถานะ `pending` เสมอ |
+| Employee cannot approve own record | Pass | create flow ไม่มี approval capability |
+| Employee cannot change approval status | Pass | API ไม่รับ status จาก client |
+| Calendar year handled correctly | Partial | รับและบันทึก date ได้ แต่ไม่มี create-side business messaging เรื่องปี |
+| Training hours support hours and minutes | Pass | minute-based input และ normalize เป็น decimal hours ก่อนบันทึก |
+| Certificate attachment allows 1 file only | Fail | UI และ API รองรับหลายไฟล์ (`maxFiles=5`, `multiple`) |
+| Certificate/evidence rules match project requirements | Partial | file type/size validation มี แต่จำนวนไฟล์ไม่ตรงกับ plan |
+| Online training URL rules are consistent | Fail | ไม่มี field/validation นี้ใน create flow |
+| Duplicate course behavior is warn but allow save | Fail | ไม่พบ logic เตือน duplicate |
+| New record should appear in Pending Review / History correctly | Pass | create mutation invalidate `trainingRecordKeys.all` และ API บันทึกสถานะ pending |
+
+---
+
+## Role & Permission Review
+
+| Permission | Status | Notes |
+| ---------- | ------ | ----- |
+| Employee can open create training record page | Pass | `requireEmployeeDashboardAccess()` อนุญาต employee area |
+| Employee can create own training record | Pass | current user employeeId ถูกใช้เป็น payload สำหรับ employee |
+| Employee can upload own certificate/evidence | Pass | upload route อนุญาตเฉพาะ owner ของ pending record |
+| Employee can cancel and return | Pass | ปุ่มกลับใช้ `router.back()` |
+| Employee cannot create for another employee via UI | Pass | ไม่มี employee selector สำหรับ employee |
+| Employee cannot create for another employee via API | Pass | `assertUserAndCourseAccess()` บังคับ ownership server-side |
+| Employee cannot assign K/S/A | Pass | ไม่มี field และ API ไม่รับ |
+| Employee cannot approve/reject | Pass | create route set pending ตายตัว |
+| Employee cannot change status manually | Pass | payload ไม่มี field status |
+| Employee cannot bypass file validation through direct API call | Partial | type/size validation มี แต่จำนวนไฟล์หลายไฟล์ยังผ่าน |
+| Employee cannot access HRD-only create/edit pages | Partial | หน้าเดียวกันถูก reuse สำหรับ create/edit; protection หลักอยู่ที่ data access และ form state มากกว่าแยก route semantics |
+
+---
+
+## UI Review
+
+- layout ของ form ใช้ `Card`, shared inputs, shared select, และ spacing สอดคล้องกับ feature อื่นในโปรเจ็กต์
+- required fields ชัดสำหรับ course, date, type, duration แต่ optional/required semantics ของ `organizer` ยังไม่ได้สะท้อนกติกาธุรกิจพิเศษใด ๆ
+- `DurationPicker` ทำให้กรอกชั่วโมง/นาทีได้ชัดกว่าช่องตัวเลขดิบ
+- upload section อธิบายชนิดไฟล์ชัด แต่สื่อสารเป็น “แนบเอกสารได้หลายไฟล์” ผ่าน UI จริง แม้ requirement ใน plan ระบุ single-file
+- ไม่มี field group สำหรับ location mode, online URL, หรือ duplicate warning section ทำให้หน้า create ปัจจุบันดูเล็กกว่าขอบเขตธุรกิจที่แผนคาดหวัง
+- ปุ่ม action บน mobile ใช้ full-width ตาม pattern ที่ดีของ repo
+
+---
+
+## UX Review
+
+- flow พื้นฐานเข้าใจง่าย: เลือกหลักสูตร, เลือกวัน, เลือกประเภท, ระบุระยะเวลา, แนบเอกสาร, ส่ง
+- สำหรับ employee ทั่วไป การ fix employee ให้เป็น current user ช่วยลดโอกาสกรอกผิดคน
+- อย่างไรก็ดี requirement เชิง domain บางอย่างหายไปจาก UX ทั้งหมด เช่น duplicate warning, online URL guidance, และ location-specific branching
+- upload ถูกเลื่อนไปหลัง create ซึ่งใช้งานได้ แต่ทำให้ submit result ขึ้นกับ 2 mutations ต่อเนื่อง หาก upload ล้มเหลวหลัง create สำเร็จ ผู้ใช้จะได้ record ถูกสร้างแต่ attachment ไม่ครบ
+- ปุ่มกลับใช้ `router.back()` ซึ่งอาจพาผู้ใช้กลับไปหน้าที่ไม่คาดหวัง หากเข้าฟอร์มจาก deep link แทนที่จะเข้าจาก history list
+
+---
+
+## Accessibility Review
+
+- form fields ส่วนใหญ่มี label และ `aria-invalid`
+- upload ใช้ shared `FileUploader` แต่จากหน้า create นี้ยังไม่เห็นข้อความผูกกับ error state ของ uploader โดยตรง
+- textarea note ใช้ `aria-label`
+- ปุ่ม action เป็นข้อความปกติ อ่านได้ง่าย
+- ยังไม่มี evidence ว่ามี accessible description เฉพาะสำหรับ upload constraints เช่น “ได้ 1 ไฟล์เท่านั้น” เพราะ implementation จริงไม่ใช้กติกานั้น
+
+---
+
+## Code Quality Review
+
+- โครงสร้างโดยรวมดี: page -> feature component -> mutation/service -> route handler -> server helper
+- form component ค่อนข้างใหญ่และรวม create/edit/upload behavior ไว้ในไฟล์เดียว ทำให้ความรับผิดชอบหลายส่วนอยู่ร่วมกัน
+- validation schema กับ form fields ยังสอดคล้องกันดีในสิ่งที่ implementation รองรับจริง
+- มี import helper เวลา เช่น `formatDurationHHMM` และ `formatDurationThai` ใน form แต่ไม่ได้ถูกใช้งานในหน้า create นี้
+- ไม่มีร่องรอย duplicate-check abstraction หรือ online/location-specific contracts ใน feature นี้
+
+---
+
+## API Review
+
+- create mutation เรียก `POST /api/training-records` ผ่าน `apiClient`
+- API route ใช้ `requireOrganizationAccess()` และเช็ก ownership ผ่าน `assertUserAndCourseAccess()`
+- API set `approvalStatus: 'pending'` ฝั่ง server เสมอ
+- payload ของ create จำกัดอยู่ที่ `employeeId`, `courseId/courseName`, `trainingDate`, `trainingType`, `submittedMinutes`, `organizer`, `note`
+- upload certificates ใช้ route แยกหลัง create สำเร็จ และ invalidate เฉพาะ certificates query key
+- ไม่พบ duplicate-check endpoint หรือ warning contract
+- ไม่พบ validation/business contract สำหรับ `online URL` หรือ `location type`
+
+---
+
+## Security Review
+
+- route guard: employee ต้องผ่าน `requireEmployeeDashboardAccess()`
+- API guard: ต้องมี session + organization ผ่าน `requireOrganizationAccess()`
+- ownership check: employee ส่งให้คนอื่นไม่ได้ เพราะ `assertUserAndCourseAccess()` เทียบ employee IDs ของ actor กับ target
+- approval/category fields ไม่เปิดจาก client
+- file upload มี server-side type/size validation ที่ `saveCertificateFile()`
+- path traversal มีการกันผ่าน `ensureWithinUploadRoot()`
+- ช่องโหว่สำคัญเชิง requirement คือ API ยังรับหลายไฟล์ได้ แม้ plan ตั้งใจ single-file
+
+---
+
+## Performance Review
+
+- create page render เป็น client form ปกติ ไม่พบ heavy query หลายตัวเกินจำเป็นสำหรับ employee
+- employee ไม่โหลด `userOptions` เพราะ query นี้เปิดเฉพาะ HRD
+- course combobox preload course options ทั้งชุดแรก (`limit=50`) ซึ่งพอใช้ได้ในระยะสั้น แต่ไม่มี search-as-you-type จริง
+- create flow ใช้ sequential mutation: create ก่อน แล้วค่อย upload file(s); ถ้าแนบหลายไฟล์หรือไฟล์ใหญ่ UX จะช้าลงตามจำนวนไฟล์
+
+---
+
+## Data Validation Review
+
+- Missing course name: Pass ผ่าน schema/course selection logic
+- Missing training date: Pass
+- Missing training hours: Pass
+- Invalid hour/minute format: Pass ในกรอบของ `DurationPicker`
+- Zero hour behavior: Pass ถูก block ที่ `> 0`
+- Over 30 hours behavior: Pass ถูก block ที่ `<= 1800` นาที
+- Missing training type: Pass
+- Missing location type: Fail ไม่มี field นี้
+- Missing provider: Partial `organizer` เป็น optional
+- Invalid online URL: Fail ไม่มี field นี้
+- Missing certificate when required: Fail ไม่มี conditional rule จาก `certificate_required`
+- Multiple file upload: Fail ตาม requirement single-file แต่ implementation อนุญาตหลายไฟล์
+- Invalid file type: Pass
+- Invalid file size: Pass
+- Null handling: Pass ในระดับพื้นฐาน
+- Incorrect defaults: Partial default date ใช้ `new Date().toISOString().slice(0, 10)` ซึ่งอิง UTC มากกว่า business timezone
+
+---
+
+## Edge Case Review
+
+- New employee: ถ้ามี employee link แล้วสร้างได้; ถ้าไม่มีจะถูก block ก่อน submit
+- Employee profile missing: มี toast block ฝั่ง client และ server จะกันต่อผ่าน ownership check
+- No course master: รองรับผ่าน custom course
+- Course name duplicate: ไม่พบ warning flow
+- Training date in future: ไม่พบ rule ป้องกัน
+- Training date in previous year: บันทึกได้ ไม่มี warning
+- `00:00` hours: ถูก block
+- `00:15` hours: รองรับ
+- `01:45` hours: รองรับ
+- `30:00` hours: รองรับ
+- More than 30 hours: ถูก block
+- Online training without URL: ไม่มี field นี้ จึงไม่ถูกบังคับ
+- Offline training with URL: ไม่มี field นี้ จึงไม่เกี่ยว
+- File upload failed: record อาจถูก create สำเร็จแต่ attachment ไม่ขึ้น เพราะ upload เป็น step ที่สอง
+- API failure: form แสดง toast จาก `error.message`
+- Slow network: ปุ่ม disabled ระหว่าง mutation แต่ไม่มี progress state รายไฟล์
+- Double submit: ปุ่ม submit ถูก disable ระหว่าง pending
+- Permission denied: server-side ownership checks มีอยู่
+
+---
+
+## Problems Found
+
+### Critical
+
+- None observed.
+
+### High
+
+- Description: หน้า create ไม่มี `location type`, `online URL`, และ duplicate warning ทั้งที่เป็น scope หลักตาม audit plan นี้
+- File: `src/features/training-records/components/training-record-form.tsx`, `src/features/training-records/schemas/training-record.ts`, `src/features/training-records/api/types.ts`, `src/app/api/training-records/route.ts`
+- Component: `TrainingRecordForm`, `trainingRecordSchema`, create contract
+- Severity: High
+- Impact: flow ปัจจุบันไม่ครอบคลุม requirement เชิงธุรกิจตามแผน ทำให้ user ไม่สามารถกรอก/ตรวจสอบข้อมูลสำคัญบางประเภทได้เลย
+- Recommendation: กำหนด canonical contract ของ create flow ให้ชัดก่อนว่าต้องมี field/business rule ใดบ้าง แล้วค่อยเติมทั้ง form, schema, payload, และ route handler ให้ตรงกัน
+
+- Description: UI และ API ของ certificate upload อนุญาตหลายไฟล์ (`maxFiles={5}`, `multiple`, loop ผ่านทุกไฟล์) ขัดกับ requirement single-file ในแผน
+- File: `src/features/training-records/components/training-record-form.tsx:580`, `src/app/api/training-records/[id]/certificates/route.ts:106`, `src/lib/certificate-storage.ts:27`
+- Component: `FileUploader`, `POST /api/training-records/[id]/certificates`
+- Severity: High
+- Impact: ผู้ใช้สามารถแนบหลักฐานหลายไฟล์ได้จริง และข้อมูลที่บันทึกจะไม่ตรง business rule หากระบบต้องการหลักฐาน 1 ไฟล์ต่อ record
+- Recommendation: ตกลงกติกาจำนวนไฟล์ให้ชัด แล้ว align ทั้ง UI, mutation, และ API validation ไปทางเดียวกัน
+
+### Medium
+
+- Description: ไม่พบ duplicate-check หรือ warning flow ใด ๆ ก่อน create แม้ plan ระบุ “warn but allow save”
+- File: `src/features/training-records/components/training-record-form.tsx`, `src/features/training-records/server/training-record-data.ts`, `src/app/api/training-records/route.ts`
+- Component: create form, create API
+- Severity: Medium
+- Impact: ผู้ใช้สามารถส่งข้อมูลซ้ำโดยไม่มี feedback ทำให้เกิด duplicate history records ได้ง่าย
+- Recommendation: เพิ่ม business decision ก่อนว่า duplicate วัดจาก course/date/type/employee combination แบบใด แล้วค่อยออกแบบ warning flow
+
+- Description: ไม่มี rule บังคับหรือ messaging จาก `certificate_required` แม้ course options ส่ง field นี้มาด้วย
+- File: `src/features/training-records/api/types.ts:100`, `src/features/training-records/components/training-record-course-combobox.tsx:55`, `src/features/training-records/components/training-record-form.tsx:572`
+- Component: course option contract, create form
+- Severity: Medium
+- Impact: หลักสูตรที่ควรต้องแนบ certificate อาจถูกส่งโดยไม่มีหลักฐานได้ และ UI ไม่สื่อ requirement นี้กับผู้ใช้
+- Recommendation: ตัดสินใจให้ชัดว่าต้อง enforce ตอน create เลยหรือหลัง create แล้วสื่อสารผ่าน UI และ validation ให้ตรงกัน
+
+- Description: default วันที่ใช้ `new Date().toISOString().slice(0, 10)` ซึ่งอิง UTC และอาจคลาดกับวันตาม timezone ธุรกิจ
+- File: `src/features/training-records/components/training-record-form.tsx:143`
+- Component: `TrainingRecordForm`
+- Severity: Medium
+- Impact: ผู้ใช้ใกล้ช่วงเปลี่ยนวันอาจเห็นค่า default date เลื่อนไป 1 วันจากเวลาท้องถิ่น
+- Recommendation: ใช้ local-date strategy เดียวกับธุรกิจของระบบแทนค่า ISO UTC ตรง ๆ
+
+- Description: upload เกิดหลัง create แบบ sequential; ถ้า upload ล้มเหลว record จะถูกสร้างแล้วแต่ attachment หาย ทำให้ flow สำเร็จเพียงบางส่วน
+- File: `src/features/training-records/components/training-record-form.tsx:222`
+- Component: `TrainingRecordForm`
+- Severity: Medium
+- Impact: user อาจคิดว่าการส่งสำเร็จครบถ้วน แต่จริง ๆ เหลือ pending record ที่ไม่มีหลักฐานแนบ
+- Recommendation: เพิ่ม UX/state ที่สื่อชัดว่า create สำเร็จแต่ upload ล้มเหลว หรือออกแบบ transactional expectation ให้ชัด
+
+- Description: ปุ่มกลับใช้ `router.back()` แทน destination คงที่
+- File: `src/features/training-records/components/training-record-form.tsx:591`
+- Component: `TrainingRecordForm`
+- Severity: Medium
+- Impact: หากผู้ใช้เข้าฟอร์มจาก bookmark, deep link, หรือหน้าอื่น ปุ่มกลับอาจพาไปบริบทที่ไม่คาดหวัง
+- Recommendation: พิจารณา fallback destination ที่ชัด เช่น history list
+
+### Low
+
+- Description: `TrainingRecordForm` รวม create, edit, upload, review-status display ไว้ใน component เดียว ทำให้ไฟล์ค่อนข้างใหญ่
+- File: `src/features/training-records/components/training-record-form.tsx`
+- Component: `TrainingRecordForm`
+- Severity: Low
+- Impact: maintainability ลดลงเมื่อเพิ่ม business rules ใหม่
+- Recommendation: หากมีการขยาย flow เพิ่ม อาจแยก concern บางส่วนเป็น subcomponents
+
+- Description: มี import helper เวลา `formatDurationHHMM` และ `formatDurationThai` ที่ไม่ถูกใช้ในหน้า create
+- File: `src/features/training-records/components/training-record-form.tsx:40`
+- Component: `TrainingRecordForm`
+- Severity: Low
+- Impact: signal ว่า component ผ่านการเปลี่ยนแปลงหลายรอบและเริ่มมี residue
+- Recommendation: cleanup imports เมื่อมีรอบแก้ implementation
+
+---
+
+## Missing Features
+
+- `location type`
+- `online URL`
+- duplicate warning
+- single-file certificate enforcement
+- conditional certificate-required validation/messaging
+- create-specific error/partial-success UX สำหรับกรณี create สำเร็จแต่ upload ล้มเหลว
+
+---
+
+## Improvement Opportunities
+
+- แยก canonical employee-create flow ออกจาก edit/review semantics ให้ชัดกว่า component เดียว
+- ทำ business rules เป็น explicit contract ใน `types.ts` และ `schema` ก่อนเพิ่ม field ใหม่
+- เพิ่ม clearer post-submit state สำหรับ attachment upload
+- หาก requirement online/offline ต่างกันจริง ให้ใช้ conditional form sections แทน flat form ปัจจุบัน
+
+---
+
+## Final Assessment
+
+Architecture: 8.0/10  
+Functionality: 6.3/10  
+Role & Permission: 8.2/10  
+UI: 7.3/10  
+UX: 6.6/10  
+Accessibility: 7.0/10  
+Security: 8.1/10  
+Performance: 7.4/10  
+Maintainability: 7.1/10  
+Overall Score: 7.3/10
+