alla-tms/docs/announcement-pin-action-enhancement-report.md

Announcement Pin Action Enhancement Report

1. Existing Structure Review

• Reused the existing announcements feature structure under src/features/announcements/ with the current api/service/mutations/types, route handlers, React Query, and form workflow.
• Reused the existing database field isPin / is_pin; no new pin table or parallel state model was introduced.
• Reused the current content workflow helpers from src/features/content-approval/lib/workflow.ts for publish/archive gating.
• Reused the existing audit infrastructure in src/features/audit-logs/server/audit-service.ts and src/features/audit-logs/server/audit-log-data.ts.
• Extended the existing announcements list/detail UI instead of creating a new action framework.
• Refactored create/edit form behavior so pin state is no longer part of form submission.

2. Files Changed

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

3. UI Changes

• Removed the pin checkbox/section from both create and edit announcement forms.
• Added pin status badge on announcement list cards and detail header.
• Added pin/unpin actions to the announcement list action area.
• Added pin/unpin actions to the announcement detail action area.
• Kept the existing responsive card layout and action button patterns.

4. Business Rules

• Only published announcements that have already started and are not expired can be pinned.
• Archived announcements are automatically unpinned in the existing workflow update route.
• Expired or otherwise ineligible pinned announcements are filtered out from pinned-first behavior and pinned-only filtering.
• Announcement ordering now prioritizes only active pinned announcements instead of every row with is_pin = true.
• Multiple pinned announcements remain supported; ordering among them still follows existing recency ordering.

5. Permission

• Reused announcement:publish as the permission for managing pin/unpin actions.
• Client-side checks use canManageAnnouncementPin(...) to hide unavailable actions.
• Server-side checks in /api/announcements/[id]/pin and /api/announcements/[id]/unpin enforce the same permission and eligibility rules.

6. Database and API Changes

• No schema migration was added because the existing isPin field already supports the feature.
• Create now defaults pin state to false.
• Create/edit payloads no longer send isPin from the form.
• Added dedicated endpoints:
  • POST /api/announcements/:id/pin
  • POST /api/announcements/:id/unpin
• Kept the existing workflow route focused on content state transitions instead of pin state changes.

7. Audit Log

• Added ANNOUNCEMENT_PINNED
• Added ANNOUNCEMENT_UNPINNED
• Added formatted Thai audit messages and filter options for both actions.

8. Testing Result

• Functional: implemented and code-reviewed against the requested workflow.
• Permission: client/server checks were added for restricted pin management.
• Responsive: list/detail changes follow existing flex-wrap action layouts and badge patterns.
• Regression: create/edit/workflow logic was kept on the same route and helper stack, with pin logic isolated into dedicated endpoints.
• Validation status: lint and build should be used as final verification for this change set.

9. Remaining Improvements

• Add explicit pin priority if the business wants manual ordering among multiple pinned announcements.
• Add optional automatic cleanup to clear is_pin when announcements expire, not only filter them out.
• Add a dedicated announcement:pin permission if pin management needs to diverge from publish authority later.
• Consider a dropdown action menu if the announcement action area grows further.