Initial commit

2026-08-31 14:10:20 -03:00
commit 8fcb5aac66
454 changed files with 60207 additions and 0 deletions
@@ -0,0 +1,177 @@
+# Payment Registration System Architecture
+
+## Overview
+A payment registration system that allows guardians/students to register payments for classes and enables admins to track payment status.
+
+## Requirements
+- **Users**: Guardians/students can register payments, admins can view payment status
+- **Payment Information**: Value, date/time, optional receipt image
+- **Access Control**: Only admins can view payment details; guardians/students can only register their own payments
+
+## Database Schema Design
+
+### Payment Model
+```javascript
+{
+  _id: ObjectId,
+  classId: ObjectId (ref: Class),
+  userId: ObjectId (ref: User),
+  amount: Number,
+  paymentDate: Date,
+  paymentMethod: String (e.g., "pix", "bank_transfer", "cash"),
+  status: String (enum: ["pending", "verified", "rejected"]),
+  receiptUrl: String (optional, from file upload),
+  notes: String (optional),
+  createdAt: Date,
+  updatedAt: Date
+}
+```
+
+### Key Features
+- **One-to-Many**: A class can have multiple payments (partial payments)
+- **Many-to-One**: A user can make multiple payments across different classes
+- **Status Tracking**: Pending → Verified/Rejected workflow
+
+## API Routes Structure
+
+### 1. Payment API Routes
+```
+/api/payments
+  GET    - List all payments (admin only)
+  POST   - Create new payment (guardian/student only)
+  GET/:id - Get single payment (admin only)
+  PUT/:id - Update payment status (admin only)
+  DELETE/:id - Delete payment (admin only)
+
+/api/payments/class/:classId
+  GET - Get all payments for a specific class (admin only)
+
+/api/payments/user/:userId
+  GET - Get all payments for a specific user (guardian/student only)
+```
+
+### 2. File Upload Integration
+- Use existing `/api/files` routes
+- Set `relatedToType` = "payment"
+- Set `relatedToId` = payment ID
+- Store receipt image URL in payment record
+
+## UI Components Structure
+
+### Admin Dashboard
+```
+/app/(protected)/admin/dashboard/payments/
+  page.jsx                    - Main payments dashboard
+  components/
+    PaymentsTable.jsx         - Table showing all payments
+    PaymentDetail.jsx         - Modal showing payment details
+    PaymentStats.jsx          - Statistics cards
+    VerifyPaymentButton.jsx   - Button to verify/reject payments
+```
+
+### Guardian Dashboard
+```
+/app/(protected)/dashboard/guardian/payments/
+  page.jsx                    - List of registered payments
+  register/
+    page.jsx                  - Payment registration form
+    components/
+      PaymentForm.jsx         - Form to register payment
+      ReceiptUpload.jsx       - File upload component
+
+/app/(protected)/dashboard/guardian/class/[id]/payments/
+  page.jsx                    - Payments for specific class
+```
+
+### Student Dashboard
+```
+/app/(protected)/dashboard/student/payments/
+  page.jsx                    - List of registered payments
+  register/
+    page.jsx                  - Payment registration form
+```
+
+## Payment Flow Diagram
+
+```mermaid
+sequenceDiagram
+    participant G as Guardian/Student
+    participant UI as UI Component
+    participant API as API Route
+    participant DB as Database
+    participant FS as File Storage
+
+    G->>UI: Submit payment form (amount, date, receipt)
+    UI->>API: POST /api/payments
+    API->>DB: Create payment record (status: pending)
+    API->>FS: Upload receipt image
+    API->>DB: Update payment with receipt URL
+    API-->>UI: Return payment confirmation
+    UI-->>G: Show success message
+
+    Note over Admin: Admin views dashboard
+    Admin->>UI: View payments dashboard
+    UI->>API: GET /api/payments
+    API-->>UI: Return all payments
+    UI-->>Admin: Display payment table with status
+```
+
+## Class View Integration
+
+### Guardian Class Detail Page
+- Add payment status indicator
+- Show "Register Payment" button if not paid
+- Show payment history for the class
+
+### Admin Class View
+- Show payment status for all students
+- Filter by payment status
+- Quick actions to verify/reject payments
+
+## Implementation Steps
+
+### Phase 1: Database & API
+1. Create Payment model
+2. Create API routes for payment CRUD operations
+3. Integrate with existing file upload system
+
+### Phase 2: Admin Dashboard
+1. Create payments dashboard page
+2. Build payments table with filtering
+3. Add payment detail modal
+4. Implement verify/reject functionality
+
+### Phase 3: Guardian/Student Interface
+1. Create payment registration form
+2. Build payment history view
+3. Integrate receipt upload
+4. Add payment status indicators
+
+### Phase 4: Integration
+1. Update class detail pages
+2. Add payment status to class cards
+3. Add payment reminders (optional)
+
+## Security Considerations
+- **Role-Based Access Control**: Only admins can view payment details
+- **Data Validation**: Validate payment amounts and dates
+- **File Upload Security**: Validate receipt images before storing
+- **User Authorization**: Users can only register payments for their own classes
+
+## Data Validation Rules
+- Amount: Must be positive number
+- Payment Date: Must be in the past or present
+- Receipt: Max file size, allowed image formats only
+- Payment Method: Must be from predefined list
+
+## Status Workflow
+```
+Pending (default) → Verified (admin approves) → Rejected (admin rejects)
+```
+
+## Future Enhancements
+- Payment reminders for pending payments
+- Payment history export
+- Bulk payment verification
+- Payment analytics and reports
+- Integration with payment gateways (optional)