Initial commit
This commit is contained in:
366
QUICK_START_GUIDE.md
Normal file
366
QUICK_START_GUIDE.md
Normal file
@@ -0,0 +1,366 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user