387 lines
18 KiB
Markdown
387 lines
18 KiB
Markdown
# 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
|
|
|
|
```
|
|
|
|
---
|
|
|
|
## 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**
|