usher-manage-stack/QUICK_START_GUIDE.md

Financial Workflow System - Quick Start Guide

🚀 Getting Started in 5 Minutes

Step 1: Run Setup Script (2 minutes)

# Make script executable
chmod +x setup-financial-workflow.sh

# Run setup
./setup-financial-workflow.sh

# Answer prompts:
# - "Create test users?" → Type 'y' and press Enter

What this does:

• Runs all database migrations
• Creates 27 permissions and 5 roles
• Creates test users (optional)
• Clears all caches

---

Step 2: Login and Assign Roles (1 minute)

1. Login as admin
2. Navigate to /admin/roles
3. Assign roles to your users:
   • finance_cashier → Users who handle money
   • finance_accountant → Users who manage books
   • finance_chair → Your organization's chair/president
   • finance_board_member → Board members
   • finance_requester → Staff who submit requests

OR use test users:

• cashier@test.com (password: password)
• accountant@test.com (password: password)
• chair@test.com (password: password)
• requester@test.com (password: password)

---

Step 3: Create Your First Finance Document (2 minutes)

1. Login as requester or admin
2. Navigate to /admin/finance-documents/create
3. Fill in the form:
   • Title: "測試報銷申請"
   • Amount: 3,000
   • Request Type: "事後報銷"
   • Description: "測試用"
   • Attachment: (optional) Upload receipt
4. Click "Submit"

Result: Document created with automatic amount tier classification!

---

📊 Understanding the Workflow

The Four Stages

┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│   STAGE 1   │ → │   STAGE 2   │ → │   STAGE 3   │ → │   STAGE 4   │
│  Approval   │   │   Payment   │   │  Recording  │   │Reconciliation│
└─────────────┘   └─────────────┘   └─────────────┘   └─────────────┘

Stage 1: Approval

Who: Cashier → Accountant → Chair (→ Board for large amounts)

Amount-based routing:

• Small (< NT$ 5,000): Cashier → Accountant
• Medium (NT$ 5,000 - 50,000): Cashier → Accountant → Chair
• Large (> NT$ 50,000): Cashier → Accountant → Chair → Board Meeting

Where: /admin/finance-documents

---

Stage 2: Payment

Who: Accountant creates, Cashier verifies & executes

Steps:

1. Accountant creates payment order (/admin/payment-orders/create/{document})
2. Cashier verifies payment order (approve/reject)
3. Cashier executes payment (upload receipt)

Where: /admin/payment-orders

Separation of Duties:

• Accountant decides WHAT to pay
• Cashier decides IF and WHEN to pay

---

Stage 3: Recording

Who: Cashier records ledger, Accountant records transactions

Steps:

1. Cashier records in cash ledger (/admin/cashier-ledger/create)
   • Automatically calculates balance
   • Links to payment order
2. Accountant records accounting entry (/admin/transactions/create)
   • Debit/credit entries
   • Links to finance document

Where:

• Cashier: /admin/cashier-ledger
• Accountant: /admin/transactions

---

Stage 4: Reconciliation

Who: Cashier prepares, Accountant reviews, Chair approves

Monthly Process:

1. Cashier creates bank reconciliation (/admin/bank-reconciliations/create)
   • Upload bank statement
   • Enter outstanding items
   • System calculates discrepancy
2. Accountant reviews reconciliation
3. Chair approves reconciliation

Where: /admin/bank-reconciliations

---

🎯 Common Tasks

As a Requester

Create expense reimbursement:

1. Go to /admin/finance-documents/create
2. Fill form (title, amount, type, description, attachment)
3. Submit
4. Wait for approval notifications

---

As a Cashier (出納)

Approve documents:

1. Go to /admin/finance-documents
2. Filter by status: "Pending Cashier Approval"
3. Review each document
4. Click "Approve" or "Reject"

Verify payment orders:

1. Go to /admin/payment-orders
2. Filter by status: "待出納覆核"
3. Review payment details
4. Click "通過覆核" or "駁回"

Execute payments:

1. Go to verified payment orders
2. Enter transaction reference (bank ref or check number)
3. Upload payment receipt
4. Click "確認執行付款"

Record in ledger:

1. Go to /admin/cashier-ledger/create
2. Select related finance document
3. Enter details (date, type, method, amount)
4. Submit (balance auto-calculated)

Monthly reconciliation:

1. Go to /admin/bank-reconciliations/create (end of month)
2. Enter bank statement details
3. Upload statement PDF
4. Add outstanding checks/deposits
5. Submit

---

As an Accountant (會計)

Approve documents:

1. Go to /admin/finance-documents
2. Filter by status: "Pending Accountant Approval"
3. Review and approve

Create payment orders:

1. From approved document, click "製作付款單"
2. Enter payee details
3. Select payment method
4. Enter bank details (if transfer)
5. Submit

Record accounting entries:

1. Go to /admin/transactions/create
2. Create debit/credit entries
3. Link to finance document
4. Submit

Review reconciliations:

1. Go to /admin/bank-reconciliations
2. Open cashier-prepared reconciliation
3. Review outstanding items
4. Click "Review"

---

As a Chair (理事長)

Approve medium/large amounts:

1. Go to /admin/finance-documents
2. Filter by status: "Pending Chair Approval"
3. Review document details
4. Approve or reject

Approve reconciliations:

1. Go to /admin/bank-reconciliations
2. Open reviewed reconciliations
3. Click "Approve"

---

📈 Reports and Monitoring

Cashier Ledger Balance Report

URL: /admin/cashier-ledger/balance-report

Shows:

• Current balance for each bank account
• Last transaction date
• Monthly receipts total
• Monthly payments total

Export Cashier Ledger

URL: /admin/cashier-ledger/export

Filters:

• Date range
• Bank account
• Entry type

Format: CSV (UTF-8 with BOM for Excel)

---

🔍 Filtering and Searching

Finance Documents Filters

• Status (pending, approved_cashier, etc.)
• Request Type (expense_reimbursement, advance_payment, etc.)
• Amount Tier (small, medium, large)
• Workflow Stage (approval, payment, recording, completed)

Payment Orders Filters

• Status (draft, pending_verification, verified, executed, cancelled)
• Verification Status (pending, approved, rejected)
• Execution Status (pending, completed, failed)

Cashier Ledger Filters

• Entry Type (receipt, payment)
• Payment Method (bank_transfer, check, cash)
• Bank Account
• Date Range

---

🔔 Notifications

Email Notifications Sent:

• Document submitted → Cashiers
• Cashier approved → Accountants
• Accountant approved (medium/large) → Chairs
• Document fully approved → Requester
• Document rejected → Requester
• (Payment order created → Cashiers) - TBD

---

🆘 Troubleshooting

"Permission denied" errors

Solution: Check if user has correct role assigned

php artisan tinker
>>> User::find(1)->roles->pluck('name')

Cannot see payment order button

Check: Document must complete approval stage first

Balance calculation incorrect

Check: Ensure all previous ledger entries are correct Fix: Review /admin/cashier-ledger and verify chronological order

Bank reconciliation shows discrepancy

Expected: This is normal if outstanding items exist Action: Review outstanding items and investigate if discrepancy is large

File upload fails

Check:

1. File size < 10MB
2. Storage directory writable: storage/app/
3. Run: php artisan storage:link

---

📞 Support

Documentation

• Implementation Status
• Test Plan
• Laravel Documentation

Common Commands

# Clear all caches
php artisan config:clear && php artisan cache:clear && php artisan view:clear

# Re-run migrations (CAUTION: Deletes data)
php artisan migrate:fresh --seed

# Re-seed permissions only
php artisan db:seed --class=FinancialWorkflowPermissionsSeeder

# Check routes
php artisan route:list | grep payment

# Create test user
php artisan tinker
>>> $user = User::create(['name' => 'Test', 'email' => 'test@example.com', 'password' => bcrypt('password')])
>>> $user->assignRole('finance_cashier')

---

✅ Quick Checklist for First Use

• Run ./setup-financial-workflow.sh
• Verify test users created (or create your own)
• Login and check routes accessible
• Create test document with small amount
• Approve as cashier
• Approve as accountant
• Create payment order as accountant
• Verify as cashier
• Execute as cashier
• Record in ledger as cashier
• Verify balance updated
• Check complete workflow in finance document

Estimated time: 15-20 minutes

---

🎓 Best Practices

1. Always test with small amounts first
2. Upload payment receipts for audit trail
3. Use descriptive notes in all stages
4. Perform bank reconciliation monthly
5. Review ledger balance regularly
6. Keep bank statements organized
7. Never skip verification steps
8. Document any discrepancies found

---

Need help? Check IMPLEMENTATION_STATUS.md for technical details or tests/FINANCIAL_WORKFLOW_TEST_PLAN.md for testing procedures.