alla-tms/plans/sprint-6-phase-2.md

You are a Senior Full Stack Engineer.

Project: Training Management System (TMS)

Current status:

• Sprint 6 Phase 1 Audit Log Foundation is completed and approved.
• Audit service logAuditEvent(...) is available.
• Auth.js, RBAC, Thai localization, responsive layout, and mobile UX are already completed.

Current task: Implement Sprint 6 Phase 2: Notification Center

Important constraints:

• Do NOT change folder structure.
• Do NOT migrate ORM.
• Do NOT rename tables.
• Do NOT rename columns.
• Do NOT break existing routes.
• Reuse existing Auth.js.
• Reuse existing Drizzle ORM.
• Reuse existing UI components.
• Keep Thai UI.
• Keep responsive/mobile behavior.
• Minimal-impact changes only.
• Reuse existing Audit Log service for important notification actions.

Part 1: Notification Data Layer

Requirements:

1. Use existing notifications table if available.
2. If notifications table already exists, reuse it.
3. Do not create a new schema unless absolutely necessary.
4. Notification fields should support:
   • id
   • userId
   • title
   • message
   • type
   • referenceType
   • referenceId
   • isRead
   • readAt
   • createdAt

Part 2: Notification Service

Create reusable service functions:

• createNotification()
• createTrainingApprovedNotification()
• createTrainingRejectedNotification()
• createAnnouncementNotification()
• createImportCompletedNotification()
• createMasterReviewNotification()
• markNotificationAsRead()
• markAllNotificationsAsRead()

Notification types:

• TRAINING_APPROVED
• TRAINING_REJECTED
• ANNOUNCEMENT_PUBLISHED
• IMPORT_COMPLETED
• MASTER_REVIEW_APPROVED
• MASTER_REVIEW_REJECTED
• SYSTEM

Part 3: Integrate Notification Events

Add notification creation to existing workflows:

1. HRD approves training record

   • Notify employee
   • Title: รายการอบรมได้รับการอนุมัติ
   • Message should include course name, category, and approved hours

2. HRD rejects training record

   • Notify employee
   • Title: รายการอบรมไม่ผ่านการอนุมัติ
   • Message should include course name and reject reason

3. Employee import completed

   • Notify HRD user who performed import
   • Include total, success, failed count

4. Master review approved/rejected

   • Notify HRD user who performed action
   • Include master type and action result

Important:

• Do not implement Email notification in this phase.
• In-app notification only.

Part 4: Notification Center UI

Route:

• /dashboard/notifications

Requirements:

1. User can view own notifications.
2. HRD and Employee both can access notifications.
3. Show unread count.
4. Show list ordered by latest first.
5. Support filter:
   • All
   • Unread
   • Read
   • Type
6. Support search by title/message.
7. Support mark one as read.
8. Support mark all as read.
9. Support click notification to open related reference if reference route is known.
10. Use Thai labels.
11. Add loading state.
12. Add empty state.
13. Add error state.
14. Responsive/mobile friendly.

Part 5: Header / Sidebar Badge

Requirements:

1. Show unread notification badge in header or sidebar if existing notification UI exists.
2. Badge should show unread count.
3. Do not break existing header responsive behavior.

Part 6: Permissions

Rules:

1. User can only see their own notifications.
2. User can only mark their own notifications as read.
3. HRD cannot read another user's notifications from the notification center unless explicitly implemented later.
4. APIs must enforce user ownership server-side.

Part 7: Audit Log

Use existing logAuditEvent(...) for:

• NOTIFICATION_MARK_READ
• NOTIFICATION_MARK_ALL_READ
• NOTIFICATION_CREATE if created manually or system-level

Do not audit every automatic notification if it creates too much noise, but audit mark-read actions and system notifications.

Part 8: API Routes / Actions

Implement or reuse routes/actions:

• GET /api/notifications
• PATCH /api/notifications/[id]/read
• PATCH /api/notifications/read-all

If existing API path differs, reuse the existing pattern.

Part 9: Output Review File

Create:

docs/sprint-6-phase-2-notification-review.md

The review file must include:

1. Summary
2. Files Changed
3. Database Changes
4. Routes Added
5. Notification Events Implemented
6. Permission Rules
7. Audit Events Added
8. Thai Localization Changes
9. Responsive/Mobile Notes
10. Manual Test Checklist
11. Known Limitations
12. Next Phase Recommendation

Manual Test Checklist must include:

• Employee can see only own notifications.
• HRD can see only own notifications.
• Training approved creates notification for employee.
• Training rejected creates notification for employee.
• Import completed creates notification for HRD.
• Master review action creates notification for HRD.
• Unread count displays correctly.
• Mark as read works.
• Mark all as read works.
• Search works.
• Filter unread/read works.
• Notification center works on mobile.
• Direct API access cannot read other users' notifications.
• Audit log records mark read actions.

Return:

• Complete code changes with file paths.
• Content of docs/sprint-6-phase-2-notification-review.md.
• Migration commands if required.