alla-tms/docs/content-approval-workflow-implementation-report.md

Content Approval Workflow Report

Executive Summary

เพิ่ม shared approval workflow สำหรับ announcements และ online-lessons บนสถาปัตยกรรมเดิมของโปรเจกต์ โดย reuse Route Handlers, Drizzle, Auth.js permission helpers, audit logs, notifications, และ TanStack Query mutation flow ที่มีอยู่แล้ว

Current Architecture

• Frontend ใช้ Next.js App Router + feature modules ใต้ src/features
• Backend ใช้ src/app/api/**/route.ts เป็น app boundary
• Authorization ใช้ requireOrganizationAccess() และ effective permissions
• Persistence ใช้ PostgreSQL + Drizzle
• Client data flow ใช้ React Query ผ่าน api/service.ts

Workflow Design

ใช้ shared workflow logic กลางที่ src/features/content-approval/lib/workflow.ts

รองรับ flow:

• draft -> pending_review -> approved -> published
• pending_review -> returned
• pending_review -> rejected
• published -> archived
• returned/rejected -> submit ใหม่

Permission Matrix

• Staff: create, edit draft, delete draft, submit
• Reviewer/Manager/IT/Admin: approve, return, reject, publish, archive
• Owner สามารถแก้ไขได้เฉพาะ draft, returned, rejected ตาม permission
• Server-side route handlers ตรวจ permission และ transition ทุกครั้ง

Status Transition

รองรับสถานะ:

• draft
• pending_review
• approved
• published
• returned
• rejected
• archived

UI Changes

• เพิ่ม shared ContentApprovalStatusBadge
• Announcement form/list/detail รองรับ workflow ใหม่
• Online lesson form/list/detail/action menu รองรับ workflow ใหม่
• ปุ่ม/เมนู action แสดงตาม permission และสถานะจริง
• เพิ่ม draft delete flow สำหรับ announcements

Backend Changes

• ขยาย schema และ migration สำหรับ workflow metadata
• เพิ่ม validation และ status transition guard ใน route handlers
• เพิ่ม announcement delete endpoint
• serialize metadata กลับไปยัง frontend ทั้งสองโมดูล

Notification

reuse notification service เดิม และเพิ่ม event:

• CONTENT_SUBMITTED
• CONTENT_APPROVED
• CONTENT_RETURNED
• CONTENT_REJECTED
• CONTENT_PUBLISHED

Audit Log

เพิ่ม audit actions สำหรับ:

• announcement submit/approve/return/reject/publish/archive/delete
• online lesson submit/approve/return/reject/publish/archive/delete

Files Modified

• src/features/content-approval/**
• src/app/api/announcements/**
• src/app/api/online-lessons/**
• src/features/announcements/**
• src/features/online-lessons/**
• src/features/notifications/**
• src/features/audit-logs/server/audit-service.ts
• src/db/schema.ts
• drizzle/0019_content_approval_workflow.sql

Testing Result

• npx tsc --noEmit
  • workflow-related changesผ่าน
  • ยังเหลือ error เดิมใน src/features/permission-management/components/user-permission-sheet.tsx

Regression Result

• Announcement และ Online Lesson ใช้ workflow shared เดียวกันแล้ว
• Route handlers บังคับ permission และ invalid transition แล้ว
• List/detail/form ของทั้งสองโมดูลรับ metadata และสถานะใหม่แล้ว

Risks

• review comment ตอน approve/return/reject ยังไม่ได้ทำเป็น dedicated form/dialog กลาง
• ไฟล์บางส่วนมีข้อความไทย encoding เพี้ยนจาก state เดิมของ repo ควรเก็บ cleanup แยก

Recommendations

• เพิ่ม shared reviewer action dialog สำหรับ comment-required actions
• เพิ่ม pending review dashboard widget
• เพิ่ม integration tests สำหรับ permission matrix และ transition rules

Future Improvements

• Scheduled publish
• Multiple reviewers
• Approval history timeline
• Versioning
• Workflow configuration per module