# Step 22 — Tasks, Calendar and Management Alerts — Implementation Report

**Status:** COMPLETED  
**Verified:** 12 August 2026  
**Pull request:** #34

## Overview

Step 22 adds persistent operational task management, a unified branch-scoped management calendar, configurable automatic collection tasks, and persistent management alerts over the permanent records already implemented in earlier modules.

The module does not duplicate loan schedules, payroll periods, recurring expenses, financial balances, collateral state, or document expiry dates into a separate calendar/reporting store. The calendar and alert engines read the existing authoritative records directly.

## Tasks

Tasks support the required lifecycle:

- Pending
- In Progress
- Completed
- Cancelled

Each task stores:

- Branch
- Title
- Description
- Category
- Priority
- Due date/time
- Assigned staff member
- Creator/updater
- Completed/cancelled user and timestamp
- Optional source type/id
- Optional automation key

### Assignment and authorization

- Task managers can create, edit and assign tasks within branches they can access.
- An assignee must be active staff assigned to the selected branch.
- Users with task-status permission can update the status of tasks assigned to themselves.
- Task managers can update any task in their branch scope.
- Completed and cancelled tasks are terminal permanent records and cannot be reopened through the status action.
- Cross-branch task access is rejected on the backend.

Task create/update/status changes are recorded through the existing audit service.

## Automatic collection tasks

Automatic collection tasks are optional and configurable per business through the existing `settings` table.

Configuration includes:

- Enable/disable automatic collection tasks
- Minimum overdue days before a task is generated

When enabled, the daily automation process:

1. Finds active loans at or beyond the configured overdue-day threshold.
2. Skips any loan that already has an open Pending or In Progress collection task.
3. Assigns the task to the recorded active loan creator/originator when available.
4. Falls back to the branch manager when the recorded loan officer is not available.
5. Creates the task with a stable daily automation key.

The process is idempotent for repeated runs and preserves completed task history. If the loan remains overdue after a prior collection task is completed, a later daily run can generate a new follow-up task.

## Unified management calendar

The management calendar contains all required roadmap event sources:

1. Loan due dates
2. Loan maturity
3. Tasks
4. Customer appointments
5. Payroll
6. Expense due dates
7. Document expiries

### Calendar source semantics

- **Loan due dates** come from active installments with remaining balances.
- **Loan maturity** is derived from the latest active installment due date for an active loan.
- **Tasks** come from persisted task due dates.
- **Customer appointments** are persistent appointment records linked to customer, branch and optional staff.
- **Payroll** comes from payroll-period pay dates.
- **Expense due dates** come from active recurring-expense next-due dates.
- **Document expiries** come from customer-document expiry dates.

The calendar supports:

- Start date
- End date
- Event type
- One, several, or all accessible branches

The backend rejects branch IDs outside the authenticated user's branch scope. Calendar ranges are validated and limited to 366 days per request.

## Customer appointments

Staff with appointment-management permission can create customer appointments from the calendar.

Appointments store:

- Branch
- Customer
- Optional assigned staff
- Title
- Purpose
- Scheduled date/time
- Notes
- Status
- Creator/updater

The selected customer and staff member must belong to the selected accessible branch.

Appointment statuses are:

- Scheduled
- Completed
- Cancelled

Appointment creation and status changes are audited.

## Management alerts

Management alerts are persistent records with:

- Business
- Branch
- Alert type
- Severity
- Title/message
- Source type/id
- Stable unique alert key
- Occurrence time
- Metadata
- Open / Acknowledged / Resolved state
- Acknowledgement user/time
- Resolution user/time/note

All nine required roadmap alert categories are implemented:

1. Large loan
2. Large expense
3. Overdue threshold
4. Low account balance
5. Cash shortage
6. Pending approval
7. Write-off request
8. Collateral ready for release
9. Expiring documents

### Large loan

Enabled by a configured amount threshold. Active/non-terminal loans whose principal meets the threshold generate an alert. If no Step 22 threshold has been stored yet, the existing business manager-approval threshold is used as a sensible fallback when it is greater than zero.

### Large expense

Enabled by a configured amount threshold. Approved expenses at or above the threshold generate an alert.

### Overdue threshold

Active loans whose stored overdue days meet the configured threshold generate an alert. Loans at 90 or more overdue days are marked critical.

### Low account balance

Enabled by a configured balance threshold. The alert engine reconstructs the account balance from permanent financial-account transactions rather than trusting mutable `current_balance` as the reporting source. When an account has no transaction history, its opening balance is used.

Balances at or below zero are marked critical.

### Cash shortage

Active cash reconciliations with a negative variance whose absolute shortage meets the configured threshold generate a critical alert.

### Pending approval

The configured age threshold is applied to pending workflow records including:

- Loans under review
- Pending expenses
- Draft payroll periods awaiting the approval/payment workflow

### Write-off request

Pending loan write-off requests generate management alerts linked to the permanent write-off request record.

### Collateral ready for release

Collateral whose current custody status is `ready_for_release` generates an informational management alert.

### Expiring documents

Customer documents whose expiry date falls within the configured warning window generate an alert.

## Alert idempotency and actions

Each alert condition uses a stable unique key tied to its source record and relevant threshold/expiry context.

Repeated automation runs do not create duplicate alerts for the same condition.

Managers can:

- Acknowledge an open alert
- Resolve an alert with a required resolution note
- Configure task automation and alert thresholds

View-only roles such as auditors can inspect alerts but cannot acknowledge, resolve or change settings.

Resolved alerts remain permanent history and are not automatically reopened by the same alert key.

## Configurable business settings

Step 22 stores its configuration in the existing business `settings` table under the `management` group.

Settings include:

- Automatic collection tasks enabled
- Collection task overdue-day threshold
- Large-loan amount threshold
- Large-expense amount threshold
- Overdue alert day threshold
- Low-account-balance threshold
- Cash-shortage threshold
- Pending-approval age threshold
- Document-expiry warning days

Amount thresholds use zero as disabled where appropriate.

## Automation

A new command is available:

`management:process-work`

It runs both:

- Automatic collection-task generation
- Management-alert generation

The command is scheduled daily at **07:00** in the configured application timezone, before recurring-expense processing at 07:30 and reminder dispatch at 08:00.

The scheduler uses `withoutOverlapping()`.

## Permissions

Step 22 adds:

- `tasks.view`
- `tasks.manage`
- `tasks.update-status`
- `calendar.view`
- `appointments.manage`
- `management-alerts.view`
- `management-alerts.manage`

Role assignments preserve separation of duties:

- Branch administrators/managers receive full Step 22 management capability.
- Operational staff receive task/calendar access appropriate to assigned work.
- Loan officers and debt collectors can manage customer appointments.
- Accountants can view management alerts but do not receive alert-management authority by default.
- Auditors receive calendar and alert read access only.
- Super administrators continue to use the existing permission bypass.

## User interface

A new compact **Work** section appears in the sidebar when permitted:

- Tasks
- Calendar
- Management Alerts

The pages use the existing application UI system:

- `x-ui.page-toolbar`
- `mf-*` components/classes
- compact tables/forms/cards
- responsive layouts
- minimal nested card structure

## Database changes

Migration:

`database/migrations/2026_08_12_200000_create_tasks_calendar_management_alerts.php`

New tables:

- `tasks`
- `customer_appointments`
- `management_alerts`

No existing financial posting tables are replaced or rewritten.

## Verification

GitHub Actions Foundation CI on pull request #34:

- Fresh migrations: PASS
- All seeders: PASS
- Full Laravel test suite: **160 passed**
- Assertions: **1,676**
- Existing Step 1–21 regression tests: PASS
- Step 22 feature tests: **6 passed**

Step 22 tests cover:

1. Manual task assignment, task lifecycle, terminal history, assignee status updates and branch isolation.
2. Configured automatic collection tasks, same-day idempotency, open-task suppression and preserved completed history.
3. All seven roadmap calendar event sources and cross-branch exclusion.
4. All nine management alert types and alert-generation idempotency.
5. Alert acknowledgement/resolution, configuration, permissions and branch isolation.
6. Routes, sidebar navigation permissions and daily scheduler registration.

## Remaining Step 22 work

None.

## Next roadmap module

**Step 23 — Global Search**.
