# Approval & Publishing Workflow Plan

## Summary

This plan covers the implementation of approval, publishing, scheduling, preview, versioning, audit logging, and notification support for:

- `announcements`
- `online-lessons`

The goal is to extend the current simple `draft/published/archived` model into a controlled workflow without breaking the project's existing Auth.js, Drizzle, route-handler, and TanStack Query patterns.

## Current Repo Reality

### Announcements

- Current status model: `draft | published | archived`
- Employee visibility is currently based on:
  - `status = published`
  - `start_date <= now`
  - `end_date is null or end_date >= now`
- HRD and super admin can manage records through existing create/update/delete endpoints
- Publish and archive are currently direct status updates
- Notifications already exist for published announcements
- Audit logging already exists for create, update, publish, archive

### Online Lessons

- Current status model: `draft | published | archived`
- Employee visibility is currently based on `is_published = true`
- Publish is currently a direct status change plus `isPublished/publishedAt`
- Audit logging and notifications are not yet as complete as announcements

### Roles

- Current business roles in code:
  - `IT`
  - `HRD`
  - `EMPLOYEE`
- Current elevated system role:
  - `super_admin`
- There is no dedicated `HRD_MANAGER` role in the current schema or auth helper layer

### Scheduler

- No existing publish scheduler or cron pattern was found in the repo
- Scheduled publish must therefore be introduced deliberately and in a way that matches deployment constraints

## Key Gaps To Solve

1. Status enums are too limited for the requested workflow.
2. No first-class review metadata exists for announcements or online lessons.
3. No versioning structure exists for either module.
4. No `HRD Manager` capability exists in the current role model.
5. No scheduled publish executor exists.
6. Employee visibility rules differ between announcements and online lessons and need to be normalized around `Published + current version`.

## Proposed Design Decisions

### 1. Workflow status model

Use the same workflow vocabulary for both modules:

- `draft`
- `pending_approval`
- `approved`
- `scheduled`
- `published`
- `rejected`
- `archived`

### 2. Versioning model

For both `announcements` and `online_lessons`, add:

- `version`
- `parent_id`
- `is_current`

Behavior:

- Records not yet published can be edited in place
- Once a record has been published, editing must create a new draft revision
- Only one version per logical record can be `is_current = true`
- Employee-facing queries must only show:
  - `status = published`
  - `is_current = true`

### 3. Permission model

Use the current auth model as the base and extend it with app-owned permission checks instead of inventing client-only gates.

Recommended interpretation for implementation:

- `super_admin`
  - full override for all workflow actions
- `HRD`
  - current generic HRD behavior should be split by permission, not by a brand new auth system

Recommended incremental approach:

- keep existing `businessRole` values
- introduce fine-grained permission checks for content workflow actions
- model `HRD Manager` as a permission-capable HRD user, not as a breaking replacement of the current role model

Suggested permission flags:

- `content:submit`
- `content:approve`
- `content:publish`
- `content:archive`
- `content:schedule`
- `content:manage_all`

This avoids rewriting the entire auth model while still supporting the requested behavior.

### 4. Scheduled publish

Because no scheduler pattern currently exists, implement in two layers:

- data model and API support first
- a server-triggerable publish processor second

Recommended first implementation:

- add a reusable server function that publishes due scheduled records
- expose an internal route handler or job entrypoint for future cron integration

This keeps the business logic testable even before infrastructure automation is added.

## Database Changes

### Announcements

Extend `announcements` with:

- `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`

Replace enum values to support the workflow states.

### Online Lessons

Extend `online_lessons` with the same workflow and versioning fields.

Review whether `is_published` should be retained temporarily as a derived compatibility field during migration or removed after full workflow migration.

## Backend Work Plan

### Phase 1. Shared workflow foundation

- add new enums to `src/db/schema.ts`
- add migration for announcements and online lessons
- add shared permission helpers for content workflow
- extend audit action constants
- extend notification service helpers

### Phase 2. Announcement workflow backend

- update list/detail access rules
- update create/edit behavior
- add submit for approval action
- add approve/reject action
- add publish now action
- add schedule publish action
- add cancel schedule action
- add unpublish action
- add archive action
- add create revision action for published records

### Phase 3. Online lesson workflow backend

- apply the same workflow actions and rules
- align employee visibility with `published + is_current`

### Phase 4. Scheduled publish processor

- create reusable processor for due announcements
- create reusable processor for due online lessons
- add internal route or task entrypoint for future cron wiring

## Frontend Work Plan

### Announcements

- refactor form actions:
  - `Save Draft`
  - `Submit for Approval`
  - `Preview`
- remove direct publish/archive controls from HRD staff flows
- add manager/admin action controls based on status
- add revision flow for published records
- add preview route/view

### Online Lessons

- refactor form actions to match announcement workflow
- replace direct publish/archive actions with workflow-aware actions
- add preview and revision behavior

### HRD Manager Dashboard

Introduce a dedicated manager workflow page that groups both modules by status:

- pending approval
- approved waiting publish
- scheduled
- published
- rejected
- archived

Recommended implementation path:

- start with one page under dashboard
- use tabs or segmented sections
- reuse existing table/list patterns instead of inventing a new shell

## API Surface To Add

Recommended route pattern:

- `POST /api/announcements/[id]/submit`
- `POST /api/announcements/[id]/approve`
- `POST /api/announcements/[id]/reject`
- `POST /api/announcements/[id]/publish`
- `POST /api/announcements/[id]/schedule`
- `POST /api/announcements/[id]/cancel-schedule`
- `POST /api/announcements/[id]/unpublish`
- `POST /api/announcements/[id]/archive`
- `POST /api/announcements/[id]/revision`

Mirror the same shape for `online-lessons`.

Keep these actions separate from generic `PATCH` to preserve explicit permission checks and status transitions.

## Audit And Notification Plan

### Audit

Extend audit coverage for both modules:

- submit
- approve
- reject
- publish
- schedule
- cancel schedule
- unpublish
- archive
- create revision

### Notifications

Reuse the existing notification service.

Add notification types/messages for:

- submitted for approval
- approved
- rejected
- scheduled
- published
- unpublished
- archived

## Risks

1. Role model ambiguity:
   `HRD Manager` does not yet exist as a first-class role, so permission-based implementation is safer than role explosion.

2. Scheduler infrastructure:
   automatic scheduled publish cannot be considered complete until deployment wiring is agreed.

3. Versioning migration:
   existing published records must be backfilled carefully so they become `version = 1` and `is_current = true`.

4. UI complexity:
   if both modules implement bespoke workflow UIs separately, the code may drift. Shared status/action utilities should be introduced where practical.

## Implementation Order

1. Add workflow plan document
2. Add schema changes and migration
3. Add shared workflow permission helpers
4. Upgrade announcement backend
5. Upgrade online lesson backend
6. Add preview and revision flows
7. Add manager dashboard
8. Add scheduled publish processor entrypoint
9. Add docs and implementation report

## Immediate Next Step

Start with schema and contract design for:

- workflow statuses
- versioning columns
- approval metadata
- publish metadata

Then implement announcement backend first as the reference module, followed by online lessons.
