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

Announcement Approval Workflow Implementation Report

1. Executive Summary

Announcement now uses the same action-based approval flow as Online Lesson for authoring and review:

• remove status selection from the form
• add บันทึกร่าง and ส่งตรวจสอบ
• submit now notifies reviewer users
• approve / return / reject / publish still notify the author
• build and TypeScript both pass after the change

2. Architecture Review

• Reused shared approval rules from src/features/content-approval/lib/workflow.ts
• Reused shared review UX from src/features/content-approval/components/content-review-action-dialog.tsx
• Kept persistence in local Route Handlers with Drizzle
• Kept notifications in src/features/notifications/server/notification-service.ts
• Reused the Online Lesson approval pattern instead of duplicating new workflow logic

3. Files Modified

• src/features/announcements/components/announcement-form.tsx
• src/features/announcements/schemas/announcement.ts
• src/features/announcements/api/types.ts
• src/features/announcements/api/service.ts
• src/features/announcements/server/announcement-data.ts
• src/app/api/announcements/route.ts
• src/app/api/announcements/[id]/route.ts
• src/features/audit-logs/server/audit-service.ts
• src/features/audit-logs/constants/audit-log-options.ts

4. Business Logic Changes

• Create and edit form payloads now send action: 'draft' | 'submit' instead of editable status
• Route handlers derive draft or pending_review from the requested action
• Submit permission is enforced with the shared canTransitionContent() rule
• Reviewer recipients are resolved from organization memberships with announcement review permissions
• Added audit coverage for ANNOUNCEMENT_DRAFT_SAVED

5. UI Changes

• Removed status dropdown from the announcement form
• Added form-level error summary with field errors
• Added footer workflow actions matching Online Lesson
• Kept publish and archive as reviewer/manager actions on edit and detail views
• Preserved review comment visibility for authors and reviewers

6. Permission Changes

• No new permission names were introduced
• Existing content approval permissions are now used more consistently for author submit vs reviewer actions
• Draft save and draft edit remain owner-scoped through existing shared permission checks

7. Workflow Changes

• Author can save draft without manually selecting a status
• Author can submit draft / returned / rejected content for review
• Submit now creates reviewer notifications for users with announcement review permissions
• Approve / return / reject / publish continue to notify the creator
• Publish still creates organization-wide announcement notifications

8. Refactoring Summary

• Announcement workflow now follows the same action-based contract used by Online Lesson
• Reviewer lookup was extracted into getAnnouncementReviewRecipientIds()
• Form and route contracts are cleaner because writable status is no longer exposed from the client

9. Breaking Changes

• Client announcement create/update multipart payload changed from status to action

10. Regression Risk

• Low for Online Lesson because its code path was not changed
• Medium for downstream clients that may still post announcement status directly instead of action

11. Test Checklist

• Create Draft
• Submit
• Approve
• Reject
• Publish
• Schedule Publish
• Notification
• Permission
• UI
• Validation

12. Known Issues

• Scheduled / Schedule Publish is still not implemented in the shared content workflow or announcement data model
• There is no scheduled_publish_at field or scheduled publish executor in the current app flow
• This report therefore treats schedule publish as a remaining follow-up, not a completed part of this change

13. Recommendation

• If schedule publish is required next, implement it once at the shared workflow and schema level for both Announcement and Online Lesson together
• Add scheduled status, scheduled_publish_at, and a publish processor entrypoint before exposing schedule actions in UI

Verification

• npx tsc --noEmit
• npm run build