alla-allaos-fullstack/plans/task-f.5.md

Task F.5: Approval Automation (Reminder & Escalation) Foundation

Status

Planned

Objective

Build the Approval Automation Foundation that manages reminder scheduling, SLA monitoring, escalation policies, timeout handling, and automatic notification for approval workflows.

This task extends the Notification Framework (F.4) by introducing time-based automation while keeping approval business logic unchanged.

The goal is to support:

• Approval SLA
• Reminder policies
• Escalation policies
• Approval timeout handling
• Automation scheduler
• Approval queue monitoring
• Notification integration

This task does not implement Email, LINE OA, Webhook delivery, Delegation, Vacation replacement, or Analytics Dashboard.

---

Mandatory Review

Review:

• AGENTS.md
• docs/standards/project-foundations.md
• docs/standards/task-catalog.md
• docs/implementation/task-f2-approval-matrix-foundation.md
• docs/implementation/task-f3-approval-workflow-builder-foundation.md
• docs/implementation/task-f4-notification-framework-foundation.md
• Approval Runtime
• Notification Framework
• CRM Authorization Foundation
• Audit Foundation

---

Current Foundation

Already available:

Approval Matrix
Approval Workflow Builder
Approval Runtime
Notification Framework
Audit Foundation

Current limitation:

Approval waits forever until someone approves.

---

Scope F.5.1 Approval SLA

Each workflow step may define:

SLA Hours
Due Date
Reminder Policy
Escalation Policy
Timeout Policy

Example:

Sales Manager

24 Hours

Department Manager

48 Hours

CEO

72 Hours

---

Scope F.5.2 Reminder Policy

Create:

crm_approval_reminder_policies

Example:

Workflow A

Reminder

After 1 day

After 3 days

After 5 days

Rules:

• Multiple reminder points
• Prevent duplicate reminders
• Configurable per workflow

---

Scope F.5.3 Escalation Policy

Create:

crm_approval_escalation_policies

Supported targets:

Manager
Requester
Explicit User
Role
Permission Group

Example:

After 3 days

↓

Notify Manager

After 5 days

↓

Escalate Director

---

Scope F.5.4 Timeout Policy

Supported actions:

None

Auto Reject

Auto Cancel

Auto Escalate

Timeout actions must be configurable per workflow.

---

Scope F.5.5 Automation Scheduler

Create:

processApprovalAutomation()

Responsibilities:

Find pending approvals

↓

Calculate SLA

↓

Send reminders

↓

Run escalation

↓

Execute timeout actions

↓

Publish notification events

Rules:

• Idempotent
• Safe to execute repeatedly
• Transactional where required

---

Scope F.5.6 Approval Queue Monitor

Add service:

getPendingApprovalQueue()

Return:

Pending

Due Today

Overdue

Escalated

Waiting Time

Remaining SLA

---

Scope F.5.7 Notification Integration

Use existing:

publishNotificationEvent()

Events:

approval.reminder

approval.escalated

approval.timeout

No direct Email or LINE sending.

---

Scope F.5.8 Calendar Support

Prepare business calendar support.

For now support:

Calendar Days

Future-ready for:

Working Days

Holiday Calendar

Business Hours

---

Scope F.5.9 APIs

Create:

GET /api/crm/approval/automation/pending

POST /api/crm/approval/automation/run

GET /api/crm/approval/reminder-policies

POST /api/crm/approval/reminder-policies

GET /api/crm/approval/escalation-policies

POST /api/crm/approval/escalation-policies

Admin only.

---

Scope F.5.10 UI

Add settings pages:

Approval Reminder Policies

Approval Escalation Policies

Features:

• CRUD policies
• SLA configuration
• Reminder schedule
• Escalation target
• Timeout action

Use existing design system.

---

Scope F.5.11 Audit

Audit actions:

approval_reminder_sent

approval_escalated

approval_timeout

approval_policy_created

approval_policy_updated

approval_policy_deleted

---

Scope F.5.12 Permissions

Verify or add:

crm.approval.automation.read

crm.approval.automation.run

crm.approval.reminder.manage

crm.approval.escalation.manage

---

Documentation

Create:

docs/implementation/task-f5-approval-automation-foundation.md

Document:

SLA model

Reminder model

Escalation model

Timeout model

Automation scheduler

Notification integration

---

Explicit Non-Scope

Do not implement:

• SMTP Email
• LINE OA
• Webhook delivery
• Vacation replacement
• Delegate approval
• AI reminder suggestions
• Approval Analytics Dashboard
• Real-time push notifications

These belong to later tasks.

---

Verification

Run:

npm exec tsc --noEmit

npm run build

Manual verification:

Create reminder policy

Create escalation policy

Submit approval

Reminder generated after SLA

Escalation generated after configured threshold

Timeout action executes correctly

Notification created

Approval remains consistent

Audit logs created

Scheduler safe to rerun

---

Definition of Done

Task is complete when:

• Approval SLA exists
• Reminder policies exist
• Escalation policies exist
• Timeout policies exist
• Automation scheduler exists
• Reminder notifications are generated
• Escalation notifications are generated
• Notification Framework is reused
• Audit logs capture automation
• Existing approval flow remains operational

Result:

Approval Automation Foundation = Established

Reminder Engine = Operational

Escalation Engine = Operational

Ready for F.6 Approval Analytics & Dashboard