alla-tms/plans/approval-publishing-workflow.md

Prompt: Implement Approval & Publishing Workflow for Announcement and Online Lesson

Objective

ปรับปรุงระบบหลังบ้านของ Training Management System (TMS) ให้รองรับ Approval & Publishing Workflow สำหรับโมดูล:

1. ประกาศ (Announcement)
2. บทเรียนออนไลน์ (Online Lesson)

โดยให้ HRD Staff / Admin สามารถสร้างและส่งอนุมัติได้ แต่ไม่สามารถเผยแพร่สู่สาธารณะได้เอง ยกเว้น Admin IT ซึ่งเป็น Super Admin และสามารถดำเนินการได้ทั้งหมด

---

Scope

ให้ดำเนินการเฉพาะโมดูล:

• Announcement
• Online Lesson

ยังไม่ต้องขยายไปยังโมดูลอื่น

---

Roles & Permissions

Admin IT / Super Admin

มีสิทธิ์ทำได้ทั้งหมด ได้แก่:

• Create
• Edit
• Delete
• Submit for Approval
• Approve
• Reject
• Publish
• Schedule Publish
• Unpublish
• Archive
• Preview
• Manage all records

HRD Staff

มีสิทธิ์:

• Create
• Edit Draft
• Delete Draft
• Submit for Approval
• Preview Draft

ไม่มีสิทธิ์:

• Approve
• Reject
• Publish
• Schedule Publish
• Unpublish
• Archive

HRD Manager

มีสิทธิ์:

• View Pending Approval
• Approve
• Reject
• Publish
• Schedule Publish
• Unpublish
• Archive
• Preview before Publish
• View HRD Manager Dashboard

Employee

มีสิทธิ์:

• เห็นเฉพาะรายการที่มีสถานะ Published เท่านั้น
• ไม่สามารถเห็น Draft, Pending Approval, Approved, Scheduled, Rejected หรือ Archived

---

Required Status

ให้รองรับสถานะดังนี้:

Draft
Pending Approval
Approved
Scheduled
Published
Rejected
Archived

---

Workflow

Create Flow

Create
  ↓
Draft
  ↓
Submit for Approval
  ↓
Pending Approval
  ↓
Approve
  ↓
Approved
  ↓
Publish Now / Schedule Publish
  ↓
Published

---

Reject Flow

Pending Approval
  ↓
Reject
  ↓
Draft

เมื่อ Reject:

• ต้องบันทึกเหตุผลการ Reject
• รายการกลับเป็น Draft
• ผู้สร้างสามารถแก้ไขได้
• ผู้สร้างสามารถลบได้
• สามารถ Submit for Approval ใหม่ได้

---

Schedule Publish Flow

Approved
  ↓
Schedule Publish
  ↓
Scheduled
  ↓
ถึงเวลาที่กำหนด
  ↓
Published

ต้องรองรับ:

• ตั้งวันเวลาเผยแพร่
• แก้ไขวันเวลาเผยแพร่
• ยกเลิก Schedule
• Publish ทันที แม้เคยตั้ง Schedule ไว้แล้ว

---

Versioning Requirement

ต้องเพิ่ม Versioning สำหรับ Announcement และ Online Lesson

กรณีรายการยังไม่ Published

• สามารถแก้ไข Draft ได้ตามปกติ

กรณีรายการ Published แล้ว

ห้ามแก้ไข Published Record โดยตรง

เมื่อมีการแก้ไขรายการที่ Published แล้ว ให้สร้าง Draft Revision ใหม่ เช่น:

Published V1
  ↓
Create Draft Revision
  ↓
Draft V2
  ↓
Submit for Approval
  ↓
Pending Approval
  ↓
Approved
  ↓
Published V2

ข้อกำหนด:

• ต้องเก็บ version number
• ต้องระบุ parent/original record
• ต้องรู้ได้ว่า version ไหนเป็น current published version
• เมื่อ Publish version ใหม่ ให้ version เดิมไม่แสดงเป็น current แล้ว
• ต้องมีประวัติ version ให้ตรวจสอบย้อนหลังได้

---

Preview Before Publish

ต้องเพิ่ม Preview ก่อน Publish

HRD Staff

• Preview ได้เฉพาะ Draft / Revision ของตนเองหรือรายการที่มีสิทธิ์

HRD Manager

• Preview รายการ Pending Approval, Approved, Scheduled ได้
• Preview ต้องแสดงหน้าตาใกล้เคียงกับที่ Employee จะเห็นจริง

Admin IT

• Preview ได้ทุกสถานะและทุกรายการ

Preview ต้องไม่ทำให้สถานะเปลี่ยน

---

HRD Manager Dashboard

เพิ่มหรือปรับหน้า Dashboard สำหรับ HRD Manager เพื่อดูรายการที่ต้องดำเนินการ

ควรมี Section หรือ Tab อย่างน้อย:

• Pending Approval
• Approved รอ Publish
• Scheduled
• Published
• Rejected
• Archived

ควรแสดงข้อมูลสำคัญ:

• ชื่อรายการ
• ประเภท: Announcement / Online Lesson
• ผู้สร้าง
• วันที่สร้าง
• วันที่ส่งอนุมัติ
• สถานะ
• วันที่ตั้งเผยแพร่ ถ้ามี
• ปุ่ม Action ตามสิทธิ์

---

Frontend Requirement

HRD Staff / Admin User

ในหน้า Create/Edit ต้องมีปุ่ม:

• Save Draft
• Submit for Approval
• Preview

ห้ามแสดงปุ่ม:

• Approve
• Reject
• Publish
• Schedule Publish
• Unpublish
• Archive

ยกเว้นผู้ใช้เป็น Admin IT

---

HRD Manager

ต้องมีปุ่มตามสถานะ:

Pending Approval

• Preview
• Approve
• Reject

Approved

• Preview
• Publish Now
• Schedule Publish

Scheduled

• Preview
• Edit Schedule
• Cancel Schedule
• Publish Now

Published

• Preview
• Unpublish
• Archive

---

Admin IT

ต้องเห็นและใช้งานปุ่มทั้งหมดได้ทุกสถานะตามความเหมาะสม

---

Backend Requirement

ห้ามตรวจสอบสิทธิ์เฉพาะหน้า UI

ต้องตรวจสอบ Role/Permission ที่ API ทุกครั้ง

API สำคัญที่ต้องป้องกัน:

• Submit for Approval
• Approve
• Reject
• Publish
• Schedule Publish
• Cancel Schedule
• Unpublish
• Archive
• Delete
• Create Revision

หากไม่มีสิทธิ์ ให้ return:

403 Forbidden

---

Database Requirement

ตรวจสอบ schema เดิมก่อนเสมอ ห้ามเดาโครงสร้าง

ถ้ายังไม่มี field ที่จำเป็น ให้เพิ่มโดยออกแบบให้สอดคล้องกับ project pattern เดิม

ควรมี field ประมาณนี้:

status
version
parent_id
is_current
submitted_by
submitted_at
approved_by
approved_at
rejected_by
rejected_at
rejected_reason
scheduled_publish_at
published_by
published_at
unpublished_by
unpublished_at
archived_by
archived_at
created_by
updated_by
created_at
updated_at

ถ้ามี Audit Log เดิม ให้ใช้ของเดิม ถ้าไม่มี ให้เพิ่มตาม pattern ของโปรเจกต์

---

Audit Log Requirement

ต้องบันทึกทุก action สำคัญ:

• Create
• Update
• Delete
• Submit for Approval
• Approve
• Reject
• Create Revision
• Schedule Publish
• Cancel Schedule
• Publish
• Unpublish
• Archive

Audit Log ควรเก็บ:

• module
• record_id
• action
• old_value
• new_value
• actor_id
• actor_role
• created_at
• note / reason

---

Notification Requirement

ถ้ามีระบบ notification เดิม ให้ reuse ของเดิม

ต้องแจ้งเตือนอย่างน้อยในเหตุการณ์:

• HRD Staff ส่งอนุมัติ → แจ้ง HRD Manager
• HRD Manager Approve → แจ้งผู้สร้าง
• HRD Manager Reject → แจ้งผู้สร้าง พร้อมเหตุผล
• ตั้งเวลาเผยแพร่ → แจ้งผู้เกี่ยวข้อง
• Publish สำเร็จ → แจ้งผู้เกี่ยวข้อง
• Unpublish / Archive → แจ้งผู้เกี่ยวข้อง

---

Scheduled Publish Job

ต้องตรวจสอบว่าระบบมี cron/job/scheduler อยู่แล้วหรือไม่

ถ้ามี ให้ใช้ pattern เดิม

ถ้าไม่มี ให้เสนอแนวทางที่เหมาะสมก่อนลงมือแก้

Scheduled Job ต้องทำงานประมาณนี้:

ค้นหารายการ status = Scheduled
และ scheduled_publish_at <= current time
จากนั้นเปลี่ยนสถานะเป็น Published
บันทึก published_at
บันทึก Audit Log

ต้องระวัง timezone และใช้แนวทางเดียวกับ project เดิม

---

Employee Visibility Rule

ทุกหน้า Employee ต้อง query เฉพาะ:

status = Published
is_current = true

ห้ามแสดง:

• Draft
• Pending Approval
• Approved
• Scheduled
• Rejected
• Archived
• version เก่า

---

Validation

ใช้ validation เดิมของ Create/Edit ให้มากที่สุด

ก่อน Submit for Approval ต้อง validate ข้อมูลเหมือนกับการเตรียมเผยแพร่จริง

หากข้อมูลไม่ครบ:

• ไม่เปลี่ยนสถานะ
• แสดง error ให้ครบทุกจุด
• ยังคงเป็น Draft

---

Required Implementation Steps

1. ตรวจสอบโครงสร้างโปรเจกต์เดิมก่อนแก้ไข
2. ตรวจสอบ Announcement module
3. ตรวจสอบ Online Lesson module
4. ตรวจสอบ Role/Permission เดิม
5. ตรวจสอบ API routes / server actions / services เดิม
6. ตรวจสอบ Database schema เดิม
7. สร้าง plan.md ก่อนเริ่มแก้ไข
8. Implement database migration
9. Implement backend permission checks
10. Implement workflow actions
11. Implement versioning
12. Implement preview page/modal
13. Implement HRD Manager dashboard
14. Implement scheduled publish
15. Update employee visibility query
16. Add audit log
17. Add notification
18. Test role-based behavior
19. Test regression ทั้ง Announcement และ Online Lesson
20. สร้างเอกสารสรุปหลังทำงานเสร็จ

---

Required Documents

หลังดำเนินการเสร็จ ต้องสร้างเอกสารไว้ในโฟลเดอร์ docs

ชื่อไฟล์แนะนำ:

docs/approval-publishing-workflow.md

เนื้อหาในเอกสารต้องมี:

• Summary
• Objective
• Scope
• Role & Permission Matrix
• Workflow Diagram
• Status Transition
• Versioning Design
• Preview Before Publish
• HRD Manager Dashboard
• Database Changes
• API Changes
• Security / Permission Checks
• Audit Log
• Notification
• Testing Summary
• Files Changed
• Known Issues / Follow-up Items

---

Testing Checklist

ต้องทดสอบอย่างน้อย:

HRD Staff

• สร้าง Draft ได้
• แก้ไข Draft ได้
• ลบ Draft ได้
• Submit ได้
• Publish ไม่ได้
• Approve ไม่ได้
• Schedule Publish ไม่ได้

HRD Manager

• เห็นรายการ Pending Approval
• Preview ได้
• Approve ได้
• Reject ได้
• Publish ได้
• Schedule Publish ได้
• Unpublish ได้
• Archive ได้

Admin IT

• ทำได้ทุก action
• เห็นทุกสถานะ
• Override Publish ได้

Employee

• เห็นเฉพาะ Published
• ไม่เห็น Draft / Pending / Approved / Scheduled / Rejected / Archived
• ไม่เห็น version เก่า

Versioning

• Published แล้วแก้ไขต้องสร้าง Draft Revision
• Publish version ใหม่แล้ว version เดิมไม่เป็น current
• Employee เห็นเฉพาะ current published version

Schedule Publish

• ตั้งเวลาเผยแพร่ได้
• ถึงเวลาแล้วเปลี่ยนเป็น Published
• ยกเลิก Schedule ได้
• Publish ทันทีได้

---

Important Rules

• ห้ามสร้างระบบใหม่ซ้ำ หากมี pattern เดิมอยู่แล้ว
• ต้อง reuse component, service, hook, validation, permission helper เดิมให้มากที่สุด
• ห้ามแก้เฉพาะ UI โดยไม่ป้องกัน backend
• ห้ามให้ HRD Staff publish ได้
• Admin IT ต้องเป็น Super Admin
• Employee ต้องเห็นเฉพาะ Published current version เท่านั้น
• ต้องสร้างเอกสารสรุปไว้ใน docs
• ต้องสร้าง plan.md ก่อนลงมือแก้ไข
• ต้องสร้าง report หลังแก้ไขเสร็จ

---

Final Deliverables

เมื่อทำเสร็จ ต้องมี:

1. Code changes สำหรับ Approval & Publishing Workflow
2. Database migration หรือ schema update
3. Updated frontend pages/components
4. Updated backend API/server actions
5. Role-based permission enforcement
6. Versioning support
7. Preview before Publish
8. HRD Manager Dashboard
9. Scheduled Publish support
10. Audit Log
11. Notification integration
12. plan.md
13. docs/approval-publishing-workflow.md
14. Final implementation report