# Workflow & Approval System

IFRS-Compliant Multi-Level Approval Workflows

Version 1.0 IFRS Compliant Phase 1 Complete IAS 1, IAS 2, IAS 7, IAS 8, IFRS 9, IFRS 15

### Overview

The CNPERP Workflow System provides a flexible, role-based approval mechanism for critical business transactions.

##### Key Benefits

- IFRS Compliance - Proper authorization controls as required by international standards
- Segregation of Duties - No user can approve their own transactions
- Multi-Level Approvals - Escalation based on materiality thresholds
- Complete Audit Trail - Every action logged with timestamps and comments

##### System Features

State Machine | Configurable states per workflow
Role-Based | Actions restricted by user role
Threshold Escalation | Auto-routing based on amount
Notifications | Real-time in-app alerts
Documentation | Required comments/attachments

### Getting Started

Quick Setup: Follow these steps to enable workflow approvals in your system.

##### Step 1: Seed Phase 1 Workflows

Navigate to Settings → Workflow & Approvals and click "Seed Phase 1 Workflows" or use the API:

POST `/api/v1/workflows/seed/phase1`

##### Step 2: Configure Approval Thresholds

In Settings → Workflow & Approvals, set your approval thresholds:

- Manager Approval Limit (default: $25,000)
- Finance Manager Limit (default: $50,000)
- CFO Approval Limit (default: $250,000)
- CEO Approval Limit (default: $500,000)

##### Step 3: Assign User Roles

Ensure users have appropriate roles assigned in Settings → Users:

manager finance_manager cfo ceo

##### Step 4: Enable Notifications

Configure notification preferences in Settings to receive alerts for pending approvals.

### Role Hierarchy

Level | Role | Code | Typical Authority
--- | --- | --- | ---
L0 | Any User | `*` | Create drafts, submit
L1 | Supervisor | `supervisor` | Up to $5,000
L2 | Manager | `manager` | $5,001 - $25,000
L3 | Finance Manager | `finance_manager` | $25,001 - $50,000
L4 | CFO | `cfo` | $50,001 - $500,000
L5 | CEO | `ceo` | Above $500,000
L5+ | Board | `board` | Material items, policy changes

### Phase 1 Workflows (Critical)

Phase 1 implements the five most critical approval workflows required for IFRS compliance.

##### 1. Journal Entry Approval IAS 8

┌─────────┐ ┌───────────┐ ┌─────────────┐ ┌──────────────────┐ ┌─────────────┐ │ Draft │───▶│ Submitted │───▶│ Manager │───▶│ Finance │───▶│ CFO │ │ │ │ │ │ Review │ │ Controller │ │ Approval │ └─────────┘ └───────────┘ └─────────────┘ └──────────────────┘ └─────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Rejected │ │ Posted │ │ Posted │ └─────────────┘ │ (< $50k) │ │ (> $50k) │ └─────────────┘ └─────────────┘

###### Critical Controls:

- ✅ No self-approval permitted
- ✅ All manual journals require approval
- ✅ Entries > $50,000 require CFO approval
- ✅ Year-end adjustments require CFO approval

##### 2. Vendor Payment Approval IAS 7, IFRS 9

┌─────────┐ ┌───────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Draft │───▶│ Scheduled │───▶│ Finance │───▶│ CFO │───▶│ CEO │ │ │ │ │ │ Review │ │ Approval │ │ Approval │ └─────────┘ └───────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ ▼ ▼ ▼ ┌────────────────┐ ┌─────────────┐ ┌─────────────┐ │ Approved │◀─│ Approved │◀───│ Approved │ │ (< $50k) │ │ ($50k-$250k)│ │ (> $250k) │ └────────────────┘ └─────────────┘ └─────────────┘

Amount | Required Approval
--- | ---
< $50,000 | Finance Manager
$50,000 - $250,000 | CFO
> $250,000 | CEO

##### 3. Sales Credit Note Approval IFRS 15

Critical: ALL credit notes require approval (revenue reduction risk)

- ✅ Submission requires justification comment
- ✅ Credit > $5,000 requires CFO
- ✅ Full invoice reversal requires CFO approval

##### 4. Bad Debt Write-off Approval IFRS 9

Amount | Required Approval
--- | ---
< $10,000 | Finance Manager
$10,000 - $100,000 | CFO
> $100,000 | Board (CEO as representative)

Requirements:

- ✅ Requires documented collection efforts
- ✅ Submission requires comment AND attachment

##### 5. Period Close Approval IAS 1

Period Type | Required Approval
--- | ---
Month-End | Finance Manager
Quarter-End | CFO
Year-End | CFO + External Audit

Controls:

- ✅ Soft close prevents new postings to period
- ✅ Period reopen requires CFO approval and justification

### Workflow States

Status | Code | Description | Terminal?
--- | --- | --- | ---
Draft | `draft` | Initial state, editable | No
Submitted | `submitted` | Awaiting routing | No
Pending Approval | `pending_approval` | Awaiting approver action | No
Approved | `approved` | Approved, awaiting completion | No
Completed | `completed` | Fully processed | Yes
Rejected | `rejected` | Declined by approver | Yes

##### Available Actions

- Submit - Send for approval
- Approve - Accept and advance
- Reject - Decline with reason
- Cancel - Cancel workflow

- Reassign - Transfer to another user
- Revise - Return for changes
- Hold - Pause workflow
- Resume - Resume from hold

### Approval Thresholds

Configure thresholds in Settings → Workflow & Approvals:

Setting | Default Value | Description
--- | --- | ---
Manager Approval Limit | $25,000 | Maximum amount manager can approve
Finance Manager Limit | $50,000 | Maximum amount finance manager can approve
CFO Approval Limit | $250,000 | Maximum amount CFO can approve
CEO Approval Limit | $500,000 | Maximum amount CEO can approve alone
Auto-Submit Threshold | $1,000 | Items below this skip workflow

### Notifications

##### Notification Types

Approval Pending | Item assigned to you for approval
Approved | Your item was approved
Rejected | Your item was rejected
Status Update | General status change

##### Notification Channels

- In-App Toast - Appears on page load if pending approvals exist
- Notification Bell - Badge counter shows unread notifications
- Notifications Page - Full list at /static/notifications.html

### Using Approvals

##### For Submitters

1. Create your document (journal entry, payment, etc.)
2. Click Submit for Approval
3. Add required comments if prompted
4. Track status in the Notifications page

##### For Approvers

1. Check the notification bell for pending items
2. Click the notification to view the item
3. Review the details and history
4. Click Approve or Reject
5. Add comments (required for rejections)

Important: You cannot approve your own submissions. The system enforces segregation of duties.

### API Reference

##### Workflow Definitions

GET `/api/v1/workflows/definitions` - List all workflow definitions
GET `/api/v1/workflows/definitions/{id}` - Get single workflow definition
POST `/api/v1/workflows/seed/phase1` - Seed Phase 1 workflows

##### Workflow Instances

GET `/api/v1/workflows/instances` - List workflow instances
POST `/api/v1/workflows/instances/{id}/approve` - Approve item
POST `/api/v1/workflows/instances/{id}/reject` - Reject item

##### Dashboard & User Endpoints

GET `/api/v1/workflows/my-pending-approvals` - Get user's pending items
GET `/api/v1/workflows/dashboard` - Get workflow dashboard stats
GET `/api/v1/workflows/entity-types` - Get all entity type definitions

### Supported Entity Types (36 Total)

###### Procurement

- `purchase_requisition`
- `purchase_order`
- `goods_receipt`
- `vendor_payment`

###### Sales

- `sales_quotation`
- `sales_order`
- `sales_invoice`
- `sales_credit_note`
- `customer_credit_limit`

###### Inventory

- `inventory_adjustment`
- `stock_writeoff`
- `stock_transfer`
- `inventory_revaluation`

###### Accounting

- `journal_entry`
- `accrual`
- `bad_debt_writeoff`
- `period_close`
- `coa_change`
- `intercompany`

###### Fixed Assets

- `asset_acquisition`
- `asset_disposal`
- `asset_impairment`
- `depreciation_policy`

###### Banking

- `bank_recon_adj`
- `cash_transfer`
- `petty_cash`

### Configuration

##### Settings Location

Navigate to Settings → Workflow & Approvals to configure:

- Global workflow enable/disable
- Approval thresholds by role
- Auto-submit settings
- Notification preferences
- Escalation settings
- Module-specific toggles
- Documentation requirements

##### Seeding Workflows via Python

    from app.database.seed_workflows import seed_phase1_workflows
    from app.core.database import SessionLocal

    db = SessionLocal()
    seed_phase1_workflows(db)
    db.close()

### Troubleshooting

##

Solution: Check that the user's role_id is in the state's `allowed_roles` array. Verify role assignment in Settings → Users.

##

Solution: Use `GET /api/v1/workflows/instances/{id}/available-actions` to see valid transitions. Check if required approvers are assigned.

##

Solution: Verify `notified_roles` are configured for the target state. Check notification settings in Settings → Workflow & Approvals.

##

This is expected behavior. The system enforces segregation of duties - users cannot approve their own transactions. Another authorized user must approve.

##### Debug Endpoints

GET `/api/v1/workflows/definitions/{id}` - Get workflow with all states/transitions
GET `/api/v1/workflows/instances/{id}/history` - Get full action history

### Implementation Phases

Phase | Entity Types | Status
--- | --- | ---
Phase 1 | journal_entry, vendor_payment, sales_credit_note, bad_debt_writeoff, period_close | ✅ Complete
Phase 2 | purchase_order, inventory_adjustment, stock_writeoff, asset_acquisition, asset_disposal | 📋 Planned
Phase 3 | sales_order, production_order, bom_change, expense_claim, payroll_run | 📋 Planned
Phase 4 | purchase_requisition, sales_quotation, stock_transfer, bank_recon_adj, budget_transfer | 📋 Planned