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)
```bash
# 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
```bash
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](IMPLEMENTATION_STATUS.md)
- [Test Plan](tests/FINANCIAL_WORKFLOW_TEST_PLAN.md)
- [Laravel Documentation](https://laravel.com/docs)

### Common Commands
```bash
# 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.