task-f.5

plans/task-f.5.md

@@ -0,0 +1,474 @@
+# 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:
+
+```txt
+Approval Matrix
+Approval Workflow Builder
+Approval Runtime
+Notification Framework
+Audit Foundation
+```
+
+Current limitation:
+
+```txt
+Approval waits forever until someone approves.
+```
+
+---
+
+# Scope F.5.1 Approval SLA
+
+Each workflow step may define:
+
+```txt
+SLA Hours
+Due Date
+Reminder Policy
+Escalation Policy
+Timeout Policy
+```
+
+Example:
+
+```txt
+Sales Manager
+
+24 Hours
+
+Department Manager
+
+48 Hours
+
+CEO
+
+72 Hours
+```
+
+---
+
+# Scope F.5.2 Reminder Policy
+
+Create:
+
+```txt
+crm_approval_reminder_policies
+```
+
+Example:
+
+```txt
+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:
+
+```txt
+crm_approval_escalation_policies
+```
+
+Supported targets:
+
+```txt
+Manager
+Requester
+Explicit User
+Role
+Permission Group
+```
+
+Example:
+
+```txt
+After 3 days
+
+↓
+
+Notify Manager
+
+After 5 days
+
+↓
+
+Escalate Director
+```
+
+---
+
+# Scope F.5.4 Timeout Policy
+
+Supported actions:
+
+```txt
+None
+
+Auto Reject
+
+Auto Cancel
+
+Auto Escalate
+```
+
+Timeout actions must be configurable per workflow.
+
+---
+
+# Scope F.5.5 Automation Scheduler
+
+Create:
+
+```txt
+processApprovalAutomation()
+```
+
+Responsibilities:
+
+```txt
+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:
+
+```txt
+getPendingApprovalQueue()
+```
+
+Return:
+
+```txt
+Pending
+
+Due Today
+
+Overdue
+
+Escalated
+
+Waiting Time
+
+Remaining SLA
+```
+
+---
+
+# Scope F.5.7 Notification Integration
+
+Use existing:
+
+```txt
+publishNotificationEvent()
+```
+
+Events:
+
+```txt
+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:
+
+```txt
+Calendar Days
+```
+
+Future-ready for:
+
+```txt
+Working Days
+
+Holiday Calendar
+
+Business Hours
+```
+
+---
+
+# Scope F.5.9 APIs
+
+Create:
+
+```txt
+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:
+
+```txt
+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:
+
+```txt
+approval_reminder_sent
+
+approval_escalated
+
+approval_timeout
+
+approval_policy_created
+
+approval_policy_updated
+
+approval_policy_deleted
+```
+
+---
+
+# Scope F.5.12 Permissions
+
+Verify or add:
+
+```txt
+crm.approval.automation.read
+
+crm.approval.automation.run
+
+crm.approval.reminder.manage
+
+crm.approval.escalation.manage
+```
+
+---
+
+# Documentation
+
+Create:
+
+```txt
+docs/implementation/task-f5-approval-automation-foundation.md
+```
+
+Document:
+
+```txt
+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:
+
+```txt
+npm exec tsc --noEmit
+
+npm run build
+```
+
+Manual verification:
+
+```txt
+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:
+
+```txt
+Approval Automation Foundation = Established
+
+Reminder Engine = Operational
+
+Escalation Engine = Operational
+
+Ready for F.6 Approval Analytics & Dashboard
+```