# Gap-Filling Execution Order

## Principles
- Fix critical bugs FIRST (system doesn't function without these)
- Infrastructure before features (events/listeners before new modules)
- Schema before code (migrations before models/services)
- Dependencies dictate sequence (refunds need payments working, documents need templates)

---

## Cycle 0: Critical Bug Fixes (30 minutes)
**File:** `01-critical-bugs.md`

1. Fix scheduled command name mismatch (`attendance:mark-auto-absent` → `attendance:mark-absent`)
2. Apply `Auditable` trait to all domain models
3. Fix `Academy::branches()` wrong namespace reference
4. Add `ShouldDispatchAfterCommit` to all existing events
5. Add `$actor` parameter to all existing events

---

## Cycle 1: Event & Listener Infrastructure (2-3 hours)
**File:** `02-events-listeners.md`

1. Create all 30+ missing domain events (with correct interfaces)
2. Create listener directory structure per domain
3. Implement core listeners (notifications, audit, side effects)
4. Register event-listener mappings in EventServiceProvider
5. Verify events dispatch correctly from existing services

---

## Cycle 2: Scheduled Jobs & Commands (2-3 hours)
**File:** `03-scheduled-jobs.md`

1. Create all 27 missing Artisan commands
2. Register in `routes/console.php` with correct frequencies
3. Wire commands to existing services where applicable
4. Add new service methods where commands need them

---

## Cycle 3: Missing Schema — Financial (3-4 hours)
**File:** `04-financial-gaps.md`

1. `refunds` table + model + RefundService + approval workflow
2. `credits` + `credit_applications` tables + models + CreditService
3. `payment_allocations` table + model + logic in PaymentService
4. `daily_closings` table + model + DailyClosingService
5. `financial_audit_log` table (dedicated financial audit trail)
6. Missing columns on existing tables (invoices, payments, wallets, payment_plans, installments)
7. PaymentPlanService with late fees, defaults, pausing
8. Missing methods on InvoiceService, PaymentService, WalletService

---

## Cycle 4: Missing Schema — Identity & People (2-3 hours)
**File:** `05-identity-gaps.md`

1. `employees` table + model + EmployeeService
2. `trainers` + `trainer_qualifications` + `trainer_availability` tables + models
3. `branch_user` pivot table
4. `contacts` polymorphic table
5. Missing columns on organizations, branches, users, people, guardians
6. Impersonation feature

---

## Cycle 5: Missing Schema — Inventory & POS (2 hours)
**File:** `06-inventory-pos-gaps.md`

1. `suppliers` table + model + SupplierService
2. `pos_sessions` table + model (link POS to dedicated sessions)
3. Missing columns on products, kits, warehouses, purchase_orders
4. ProductService (extract from Livewire)
5. Missing events + listeners for inventory

---

## Cycle 6: Missing Schema — Notifications & Documents (3-4 hours)
**File:** `07-notifications-documents-gaps.md`

1. Upgrade `notification_templates` to full `templates` table (print/PDF/certificate support)
2. `generated_documents` table + model + DocumentService
3. PDF generation (DomPDF integration)
4. Certificate system (unique number, QR, verification route)
5. SMS gateway interface pattern
6. Retry mechanism for failed notifications
7. Missing channels (WhatsApp placeholder, push notification)

---

## Cycle 7: Training & Attendance Gaps (2-3 hours)
**File:** `08-training-attendance-gaps.md`

1. Missing statuses alignment (participant, enrollment, group, session)
2. Excuse management subsystem (submit, approve, reject, document)
3. Session Livewire UI (list/form/show)
4. Schedule management UI
5. Holiday CRUD UI
6. Waitlist management UI
7. Add missing FK constraints (facility_id on schedules/sessions)
8. Session events + listeners

---

## Cycle 8: Facility & Space UI (1-2 hours)
**File:** `09-facility-space-gaps.md`

1. Space Layout Editor (Livewire + Alpine visual editor)
2. Space Reservation booking UI
3. Segment management UI
4. `facility_operating_hours` table (per-day hours)
5. Missing facility columns
6. Conflict detection warnings in reservation UI

---

## Cycle 9: UI Component Library (4-5 hours)
**File:** `10-ui-component-library.md`

1. Create `resources/views/components/ui/` with all 18 components
2. Create `resources/views/components/forms/` with 5 components
3. Create `resources/views/components/data/` with 3 components
4. Refactor existing views to use component library
5. Add Chart.js + dashboard visualizations
6. Toast notification system
7. Dark mode support
8. Language switcher

---

## Cycle 10: Reporting & Exports (2-3 hours)
**File:** `11-reporting-exports.md`

1. Install DomPDF + Laravel Excel packages
2. Unified `ReportService::generate()` with format parameter
3. PDF templates (invoice, receipt, certificate, report)
4. Excel/CSV export for all report types
5. Dashboard charts (revenue trend, payment methods, attendance)
6. Role-specific dashboards (trainer, parent, admin)
7. Missing reports (aging, profitability, utilization)

---

## Cycle 11: Pricing Engine Alignment (1-2 hours)
**File:** `12-pricing-engine-gaps.md`

1. Add `billing_cycle` to base_prices
2. Auto-applied promotions (without coupon code)
3. `coupon_codes` table for multi-code-per-promotion
4. `stackable_with_rules` logic
5. PriceNotFoundException class
6. `min_final_amount` on pricing rules
7. Percentage applies to ORIGINAL base (non-cascading) per doc

---

## Cycle 12: Approval Workflows & Business Rules (2-3 hours)
**File:** `13-approval-workflows.md`

1. `approval_requests` table + model + ApprovalService
2. Configurable approval chains (refund > X, discount > Y%)
3. Notification on pending approvals
4. Dashboard widget for pending approvals
5. `business_rules` table for non-pricing decisions

---

## Cycle 13: Final Integration & Polish (2-3 hours)
**File:** `14-integration-polish.md`

1. Verify all FK constraints are applied correctly
2. Seed all permissions for new modules
3. Add new routes to sidebar navigation
4. Add loading states + empty states to all views
5. Run full `php artisan migrate` on fresh DB — verify no errors
6. Test critical flows: login → dashboard → create participant → enroll → POS sale → payment
7. Verify Docker build still works with new packages
8. Update seeders with new default data

---

## Total Estimated Effort: 30-40 hours of implementation

## Dependency Graph

```
Cycle 0 (bugs) ──→ Cycle 1 (events) ──→ ALL subsequent cycles
                                      ├──→ Cycle 2 (jobs)
                                      ├──→ Cycle 3 (financial)
                                      ├──→ Cycle 4 (identity)
                                      ├──→ Cycle 5 (inventory)
                                      ├──→ Cycle 7 (training)
                                      ├──→ Cycle 8 (facility)
                                      └──→ Cycle 12 (approvals)
Cycle 3 (financial) ──→ Cycle 6 (documents) ──→ Cycle 10 (reports)
Cycle 4 (identity) ──→ Cycle 8 (facility)
Cycle 9 (UI lib) ── independent, can run in parallel with Cycles 2-8
Cycle 11 (pricing) ── independent
Cycle 13 (integration) ── MUST be last
```
