# API Routes Documentation
## Taiwan NPO Membership Management System

**Last Updated:** 2025-11-20

This document provides a complete routing table for the application.

---

## Route Legend

**Middleware:**
- `auth` - Requires authentication
- `admin` - Requires admin role/permission (via EnsureUserIsAdmin)
- `verified` - Requires email verification
- `paid` - Requires active paid membership (via CheckPaidMembership)

**HTTP Methods:**
- `GET` - Retrieve resource
- `POST` - Create resource
- `PATCH` - Update resource
- `DELETE` - Delete resource

---

## 1. Public Routes

| Method | URI | Name | Controller@Method | Middleware | Description |
|--------|-----|------|-------------------|------------|-------------|
| GET | `/` | - | Closure | - | Welcome page |
| GET | `/register/member` | register.member | PublicMemberRegistrationController@create | - | Public member registration form |
| POST | `/register/member` | register.member.store | PublicMemberRegistrationController@store | - | Process public registration |

---

## 2. Authentication Routes

Provided by Laravel Breeze (`routes/auth.php`):

| Method | URI | Name | Description |
|--------|-----|------|-------------|
| GET | `/login` | login | Login form |
| POST | `/login` | - | Process login |
| POST | `/logout` | logout | Logout |
| GET | `/register` | register | Registration form (default Laravel) |
| POST | `/register` | - | Process registration |
| GET | `/forgot-password` | password.request | Password reset request |
| POST | `/forgot-password` | password.email | Send reset email |
| GET | `/reset-password/{token}` | password.reset | Password reset form |
| POST | `/reset-password` | password.update | Update password |
| GET | `/verify-email` | verification.notice | Email verification notice |
| GET | `/verify-email/{id}/{hash}` | verification.verify | Verify email |
| POST | `/email/verification-notification` | verification.send | Resend verification |

---

## 3. Authenticated Member Routes

**Middleware:** `auth`

| Method | URI | Name | Controller@Method | Description |
|--------|-----|------|-------------------|-------------|
| GET | `/dashboard` | dashboard | Closure | Default dashboard |
| GET | `/my-membership` | member.dashboard | MemberDashboardController@show | Member dashboard |
| GET | `/member/submit-payment` | member.payments.create | MemberPaymentController@create | Payment submission form |
| POST | `/member/payments` | member.payments.store | MemberPaymentController@store | Submit payment |
| GET | `/profile` | profile.edit | ProfileController@edit | Edit profile |
| PATCH | `/profile` | profile.update | ProfileController@update | Update profile |
| DELETE | `/profile` | profile.destroy | ProfileController@destroy | Delete account |

---

## 4. Admin Routes

**Middleware:** `auth`, `admin`
**Prefix:** `/admin`
**Name Prefix:** `admin.`

### 4.1 Dashboard

| Method | URI | Name | Controller@Method | Description |
|--------|-----|------|-------------------|-------------|
| GET | `/admin/dashboard` | admin.dashboard | AdminDashboardController@index | Admin dashboard |

---

### 4.2 Member Management

| Method | URI | Name | Controller@Method | Required Permission | Description |
|--------|-----|------|-------------------|-------------------|-------------|
| GET | `/admin/members` | admin.members.index | AdminMemberController@index | - | List members |
| GET | `/admin/members/create` | admin.members.create | AdminMemberController@create | - | Create form |
| POST | `/admin/members` | admin.members.store | AdminMemberController@store | - | Store member |
| GET | `/admin/members/{member}` | admin.members.show | AdminMemberController@show | - | Show member |
| GET | `/admin/members/{member}/edit` | admin.members.edit | AdminMemberController@edit | - | Edit form |
| PATCH | `/admin/members/{member}` | admin.members.update | AdminMemberController@update | - | Update member |
| PATCH | `/admin/members/{member}/roles` | admin.members.roles.update | AdminMemberController@updateRoles | - | Update member roles |
| GET | `/admin/members/{member}/activate` | admin.members.activate | AdminMemberController@showActivate | activate_memberships | Activation form |
| POST | `/admin/members/{member}/activate` | admin.members.activate.store | AdminMemberController@activate | activate_memberships | Activate membership |
| GET | `/admin/members/import` | admin.members.import-form | AdminMemberController@importForm | - | Import form |
| POST | `/admin/members/import` | admin.members.import | AdminMemberController@import | - | Import CSV |
| GET | `/admin/members/export` | admin.members.export | AdminMemberController@export | - | Export CSV |

---

### 4.3 Payment Management (Admin)

| Method | URI | Name | Controller@Method | Description |
|--------|-----|------|-------------------|-------------|
| GET | `/admin/members/{member}/payments/create` | admin.members.payments.create | AdminPaymentController@create | Create payment form |
| POST | `/admin/members/{member}/payments` | admin.members.payments.store | AdminPaymentController@store | Store payment |
| GET | `/admin/members/{member}/payments/{payment}/edit` | admin.members.payments.edit | AdminPaymentController@edit | Edit payment form |
| PATCH | `/admin/members/{member}/payments/{payment}` | admin.members.payments.update | AdminPaymentController@update | Update payment |
| DELETE | `/admin/members/{member}/payments/{payment}` | admin.members.payments.destroy | AdminPaymentController@destroy | Delete payment |
| GET | `/admin/members/{member}/payments/{payment}/receipt` | admin.members.payments.receipt | AdminPaymentController@receipt | Download receipt |

---

### 4.4 Payment Verification

| Method | URI | Name | Controller@Method | Required Permission | Description |
|--------|-----|------|-------------------|-------------------|-------------|
| GET | `/admin/payment-verifications` | admin.payment-verifications.index | PaymentVerificationController@index | view_payment_verifications | Dashboard |
| GET | `/admin/payment-verifications/{payment}` | admin.payment-verifications.show | PaymentVerificationController@show | view_payment_verifications | Payment details |
| POST | `/admin/payment-verifications/{payment}/approve-cashier` | admin.payment-verifications.approve-cashier | PaymentVerificationController@approveByCashier | verify_payments_cashier | Tier 1 approval |
| POST | `/admin/payment-verifications/{payment}/approve-accountant` | admin.payment-verifications.approve-accountant | PaymentVerificationController@approveByAccountant | verify_payments_accountant | Tier 2 approval |
| POST | `/admin/payment-verifications/{payment}/approve-chair` | admin.payment-verifications.approve-chair | PaymentVerificationController@approveByChair | verify_payments_chair | Tier 3 approval |
| POST | `/admin/payment-verifications/{payment}/reject` | admin.payment-verifications.reject | PaymentVerificationController@reject | verify_payments_* | Reject payment |
| GET | `/admin/payment-verifications/{payment}/receipt` | admin.payment-verifications.download-receipt | PaymentVerificationController@downloadReceipt | view_payment_verifications | Download receipt |

---

### 4.5 Finance Documents

| Method | URI | Name | Controller@Method | Description |
|--------|-----|------|-------------------|-------------|
| GET | `/admin/finance-documents` | admin.finance.index | FinanceDocumentController@index | List documents |
| GET | `/admin/finance-documents/create` | admin.finance.create | FinanceDocumentController@create | Create form |
| POST | `/admin/finance-documents` | admin.finance.store | FinanceDocumentController@store | Store document |
| GET | `/admin/finance-documents/{financeDocument}` | admin.finance.show | FinanceDocumentController@show | Show document |
| POST | `/admin/finance-documents/{financeDocument}/approve` | admin.finance.approve | FinanceDocumentController@approve | Approve (multi-tier) |
| POST | `/admin/finance-documents/{financeDocument}/reject` | admin.finance.reject | FinanceDocumentController@reject | Reject |
| GET | `/admin/finance-documents/{financeDocument}/download` | admin.finance.download | FinanceDocumentController@download | Download attachment |

---

### 4.6 Issue Tracking

| Method | URI | Name | Controller@Method | Description |
|--------|-----|------|-------------------|-------------|
| GET | `/admin/issues` | admin.issues.index | IssueController@index | List issues |
| GET | `/admin/issues/create` | admin.issues.create | IssueController@create | Create form |
| POST | `/admin/issues` | admin.issues.store | IssueController@store | Store issue |
| GET | `/admin/issues/{issue}` | admin.issues.show | IssueController@show | Show issue |
| GET | `/admin/issues/{issue}/edit` | admin.issues.edit | IssueController@edit | Edit form |
| PATCH | `/admin/issues/{issue}` | admin.issues.update | IssueController@update | Update issue |
| DELETE | `/admin/issues/{issue}` | admin.issues.destroy | IssueController@destroy | Delete issue |
| POST | `/admin/issues/{issue}/assign` | admin.issues.assign | IssueController@assign | Assign user |
| PATCH | `/admin/issues/{issue}/status` | admin.issues.update-status | IssueController@updateStatus | Update status |
| POST | `/admin/issues/{issue}/comments` | admin.issues.comments.store | IssueController@addComment | Add comment |
| POST | `/admin/issues/{issue}/attachments` | admin.issues.attachments.store | IssueController@uploadAttachment | Upload file |
| GET | `/admin/issues/attachments/{attachment}/download` | admin.issues.attachments.download | IssueController@downloadAttachment | Download file |
| DELETE | `/admin/issues/attachments/{attachment}` | admin.issues.attachments.destroy | IssueController@deleteAttachment | Delete file |
| POST | `/admin/issues/{issue}/time-logs` | admin.issues.time-logs.store | IssueController@logTime | Log time |
| POST | `/admin/issues/{issue}/watchers` | admin.issues.watchers.store | IssueController@addWatcher | Add watcher |
| DELETE | `/admin/issues/{issue}/watchers` | admin.issues.watchers.destroy | IssueController@removeWatcher | Remove watcher |

---

### 4.7 Issue Labels

| Method | URI | Name | Controller@Method | Description |
|--------|-----|------|-------------------|-------------|
| GET | `/admin/issue-labels` | admin.issue-labels.index | IssueLabelController@index | List labels |
| GET | `/admin/issue-labels/create` | admin.issue-labels.create | IssueLabelController@create | Create form |
| POST | `/admin/issue-labels` | admin.issue-labels.store | IssueLabelController@store | Store label |
| GET | `/admin/issue-labels/{issueLabel}/edit` | admin.issue-labels.edit | IssueLabelController@edit | Edit form |
| PATCH | `/admin/issue-labels/{issueLabel}` | admin.issue-labels.update | IssueLabelController@update | Update label |
| DELETE | `/admin/issue-labels/{issueLabel}` | admin.issue-labels.destroy | IssueLabelController@destroy | Delete label |

---

### 4.8 Issue Reports

| Method | URI | Name | Controller@Method | Description |
|--------|-----|------|-------------------|-------------|
| GET | `/admin/issue-reports` | admin.issue-reports.index | IssueReportsController@index | View reports |

---

### 4.9 Budget Management

| Method | URI | Name | Controller@Method | Description |
|--------|-----|------|-------------------|-------------|
| GET | `/admin/budgets` | admin.budgets.index | BudgetController@index | List budgets |
| GET | `/admin/budgets/create` | admin.budgets.create | BudgetController@create | Create form |
| POST | `/admin/budgets` | admin.budgets.store | BudgetController@store | Store budget |
| GET | `/admin/budgets/{budget}` | admin.budgets.show | BudgetController@show | Show budget |
| GET | `/admin/budgets/{budget}/edit` | admin.budgets.edit | BudgetController@edit | Edit form |
| PATCH | `/admin/budgets/{budget}` | admin.budgets.update | BudgetController@update | Update budget |
| POST | `/admin/budgets/{budget}/submit` | admin.budgets.submit | BudgetController@submit | Submit for approval |
| POST | `/admin/budgets/{budget}/approve` | admin.budgets.approve | BudgetController@approve | Approve budget |
| POST | `/admin/budgets/{budget}/activate` | admin.budgets.activate | BudgetController@activate | Activate budget |
| POST | `/admin/budgets/{budget}/close` | admin.budgets.close | BudgetController@close | Close budget |
| DELETE | `/admin/budgets/{budget}` | admin.budgets.destroy | BudgetController@destroy | Delete budget |

---

### 4.10 Transaction Management

| Method | URI | Name | Controller@Method | Description |
|--------|-----|------|-------------------|-------------|
| GET | `/admin/transactions` | admin.transactions.index | TransactionController@index | List transactions |
| GET | `/admin/transactions/create` | admin.transactions.create | TransactionController@create | Create form |
| POST | `/admin/transactions` | admin.transactions.store | TransactionController@store | Store transaction |
| GET | `/admin/transactions/{transaction}` | admin.transactions.show | TransactionController@show | Show transaction |
| GET | `/admin/transactions/{transaction}/edit` | admin.transactions.edit | TransactionController@edit | Edit form |
| PATCH | `/admin/transactions/{transaction}` | admin.transactions.update | TransactionController@update | Update transaction |
| DELETE | `/admin/transactions/{transaction}` | admin.transactions.destroy | TransactionController@destroy | Delete transaction |

---

### 4.11 Roles & Permissions

| Method | URI | Name | Controller@Method | Description |
|--------|-----|------|-------------------|-------------|
| GET | `/admin/roles` | admin.roles.index | AdminRoleController@index | List roles |
| GET | `/admin/roles/create` | admin.roles.create | AdminRoleController@create | Create form |
| POST | `/admin/roles` | admin.roles.store | AdminRoleController@store | Store role |
| GET | `/admin/roles/{role}` | admin.roles.show | AdminRoleController@show | Show role |
| GET | `/admin/roles/{role}/edit` | admin.roles.edit | AdminRoleController@edit | Edit form |
| PATCH | `/admin/roles/{role}` | admin.roles.update | AdminRoleController@update | Update role |
| POST | `/admin/roles/{role}/assign-users` | admin.roles.assign-users | AdminRoleController@assignUsers | Assign users |
| DELETE | `/admin/roles/{role}/users/{user}` | admin.roles.remove-user | AdminRoleController@removeUser | Remove user |

---

### 4.12 Audit Logs

| Method | URI | Name | Controller@Method | Description |
|--------|-----|------|-------------------|-------------|
| GET | `/admin/audit-logs` | admin.audit.index | AdminAuditLogController@index | List audit logs |
| GET | `/admin/audit-logs/export` | admin.audit.export | AdminAuditLogController@export | Export CSV |

---

## 5. Route Count Summary

| Category | Routes | Middleware |
|----------|--------|------------|
| Public | 3 | None |
| Auth (Breeze) | ~12 | Varies |
| Member | 7 | auth |
| Admin Dashboard | 1 | auth, admin |
| Admin Members | 12 | auth, admin |
| Admin Payments | 6 | auth, admin |
| Payment Verification | 7 | auth, admin, permission-based |
| Finance Documents | 7 | auth, admin |
| Issues | 16 | auth, admin |
| Issue Labels | 6 | auth, admin |
| Issue Reports | 1 | auth, admin |
| Budgets | 11 | auth, admin |
| Transactions | 7 | auth, admin |
| Roles | 8 | auth, admin |
| Audit Logs | 2 | auth, admin |
| **TOTAL** | **~106+** | - |

---

## 6. Permission Requirements

### Payment Verification Permissions

| Permission | Description | Can Perform |
|------------|-------------|-------------|
| `verify_payments_cashier` | Tier 1 approval | Approve as cashier |
| `verify_payments_accountant` | Tier 2 approval | Approve as accountant |
| `verify_payments_chair` | Tier 3 approval | Approve as chair |
| `activate_memberships` | Membership activation | Activate members |
| `view_payment_verifications` | View dashboard | Access verification dashboard |

### Default Role Permissions

| Role | Has Permissions |
|------|----------------|
| admin | All permissions (automatic) |
| payment_cashier | verify_payments_cashier, view_payment_verifications |
| payment_accountant | verify_payments_accountant, view_payment_verifications |
| payment_chair | verify_payments_chair, view_payment_verifications |
| membership_manager | activate_memberships, view_payment_verifications |

---

## 7. Request/Response Examples

### 7.1 POST /member/payments (Submit Payment)

**Request:**
```http
POST /member/payments HTTP/1.1
Content-Type: multipart/form-data

amount=1000
paid_at=2025-11-20
payment_method=bank_transfer
reference=ATM123456
receipt=[FILE]
notes=Annual membership fee
```

**Response (Success):**
```http
HTTP/1.1 302 Found
Location: /my-membership
Session: status="Payment submitted successfully!"
```

---

### 7.2 POST /admin/payment-verifications/{id}/approve-cashier

**Request:**
```http
POST /admin/payment-verifications/123/approve-cashier HTTP/1.1
Content-Type: application/x-www-form-urlencoded

notes=Receipt verified
```

**Response (Success):**
```http
HTTP/1.1 302 Found
Location: /admin/payment-verifications
Session: status="Payment approved by cashier."
```

**Response (Error - No Permission):**
```http
HTTP/1.1 403 Forbidden
```

---

### 7.3 GET /admin/issues (With Filters)

**Request:**
```http
GET /admin/issues?status=open&priority=urgent&search=login HTTP/1.1
```

**Response:**
```http
HTTP/1.1 200 OK
Content-Type: text/html

[Rendered Blade view with filtered issues]
```

---

## 8. CSRF Protection

All POST, PATCH, PUT, DELETE requests require CSRF token:

```html
<form method="POST" action="/admin/members">
    @csrf
    <!-- form fields -->
</form>
```

Or via JavaScript:
```javascript
fetch('/admin/members', {
    method: 'POST',
    headers: {
        'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').content,
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(data)
})
```

---

**End of API Routes Documentation**