feat(phase-24/25): scheduled report delivery and health check endpoints

Phase 24: Report Schedules
- ReportSchedule model with BelongsToTenant, frequency, recipients, filters
- SendScheduledReportJob queues mail delivery and updates next_run_at
- ScheduledReportMail with styled HTML template for financial/inventory/HR
- ReportScheduleController: full CRUD + send-now endpoint
- Artisan command reports:send-scheduled dispatches due schedules
- Scheduled hourly via console routes
- 10 feature tests covering CRUD, validation, tenant isolation, mail delivery

Phase 25: Health Checks & Metrics
- GET /api/v1/health — public endpoint checking DB, cache, queue, storage
- GET /api/v1/metrics — authenticated endpoint with system stats
- Returns 200 (healthy) or 503 (unhealthy) based on check results
- 6 feature tests covering auth, structure, and check contents

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RdUGwo74JXChRCF88Yu27d

Author: claude

erp/app/Console/Commands/SendScheduledReports.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Jobs\SendScheduledReportJob;
+use App\Models\ReportSchedule;
+use Illuminate\Console\Command;
+
+class SendScheduledReports extends Command
+{
+    protected $signature   = 'reports:send-scheduled';
+    protected $description = 'Dispatch queued jobs for all due report schedules';
+
+    public function handle(): int
+    {
+        $due = ReportSchedule::where('is_active', true)
+            ->where(function ($q) {
+                $q->whereNull('next_run_at')
+                  ->orWhere('next_run_at', '<=', now());
+            })
+            ->get();
+
+        foreach ($due as $schedule) {
+            SendScheduledReportJob::dispatch($schedule);
+            $this->info("Queued report: {$schedule->name} ({$schedule->report_type})");
+        }
+
+        $this->info("Dispatched {$due->count()} scheduled report job(s).");
+
+        return self::SUCCESS;
+    }
+}

erp/app/Http/Controllers/Api/V1/HealthController.php

@@ -0,0 +1,113 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1;
+
+use Illuminate\Http\JsonResponse;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Queue;
+use Illuminate\Support\Facades\Storage;
+
+class HealthController extends ApiController
+{
+    public function check(): JsonResponse
+    {
+        $checks  = [];
+        $overall = 'healthy';
+
+        // Database
+        try {
+            DB::select('SELECT 1');
+            $checks['database'] = ['status' => 'healthy'];
+        } catch (\Throwable $e) {
+            $checks['database'] = ['status' => 'unhealthy', 'error' => $e->getMessage()];
+            $overall = 'unhealthy';
+        }
+
+        // Cache
+        try {
+            Cache::put('health_check', true, 5);
+            $checks['cache'] = Cache::get('health_check') === true
+                ? ['status' => 'healthy']
+                : ['status' => 'degraded', 'error' => 'Cache write/read mismatch'];
+            if ($checks['cache']['status'] !== 'healthy') {
+                $overall = 'degraded';
+            }
+        } catch (\Throwable $e) {
+            $checks['cache'] = ['status' => 'degraded', 'error' => $e->getMessage()];
+            $overall = 'degraded';
+        }
+
+        // Queue
+        try {
+            $failedJobs = DB::table('failed_jobs')->count();
+            $checks['queue'] = [
+                'status'      => 'healthy',
+                'failed_jobs' => $failedJobs,
+            ];
+            if ($failedJobs > 100) {
+                $checks['queue']['status'] = 'degraded';
+                $overall = 'degraded';
+            }
+        } catch (\Throwable $e) {
+            $checks['queue'] = ['status' => 'degraded', 'error' => $e->getMessage()];
+        }
+
+        // Storage
+        try {
+            $diskUsage = disk_free_space(storage_path());
+            $checks['storage'] = [
+                'status'     => 'healthy',
+                'free_bytes' => $diskUsage,
+            ];
+        } catch (\Throwable $e) {
+            $checks['storage'] = ['status' => 'degraded', 'error' => $e->getMessage()];
+        }
+
+        $httpStatus = $overall === 'healthy' ? 200 : 503;
+
+        return response()->json([
+            'status'    => $overall,
+            'timestamp' => now()->toIso8601String(),
+            'version'   => config('app.version', '1.0.0'),
+            'checks'    => $checks,
+        ], $httpStatus);
+    }
+
+    public function metrics(): JsonResponse
+    {
+        $tenantId = auth()->user()?->tenant_id;
+
+        $stats = [
+            'tenants'          => DB::table('tenants')->count(),
+            'users'            => DB::table('users')->count(),
+            'api_requests_today' => null, // would need request logging table
+            'queue_jobs'       => [
+                'pending' => DB::table('jobs')->count(),
+                'failed'  => DB::table('failed_jobs')->count(),
+            ],
+            'database'         => [
+                'size_mb' => $this->getDatabaseSize(),
+            ],
+            'memory_usage_mb'  => round(memory_get_usage(true) / 1024 / 1024, 2),
+            'peak_memory_mb'   => round(memory_get_peak_usage(true) / 1024 / 1024, 2),
+            'php_version'      => PHP_VERSION,
+            'laravel_version'  => app()->version(),
+        ];
+
+        return $this->success($stats);
+    }
+
+    private function getDatabaseSize(): ?float
+    {
+        try {
+            $path = database_path('database.sqlite');
+            if (file_exists($path)) {
+                return round(filesize($path) / 1024 / 1024, 2);
+            }
+            return null;
+        } catch (\Throwable) {
+            return null;
+        }
+    }
+}

erp/app/Http/Controllers/Api/V1/ReportScheduleController.php

@@ -0,0 +1,81 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Jobs\SendScheduledReportJob;
+use App\Models\ReportSchedule;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+class ReportScheduleController extends ApiController
+{
+    public function index(Request $request): JsonResponse
+    {
+        $tenantId  = app()->has('tenant') ? app('tenant')->id : $request->user()->tenant_id;
+        $schedules = ReportSchedule::where('tenant_id', $tenantId)
+            ->with('user:id,name')
+            ->latest()
+            ->get();
+
+        return $this->success($schedules);
+    }
+
+    public function store(Request $request): JsonResponse
+    {
+        $tenantId = app()->has('tenant') ? app('tenant')->id : $request->user()->tenant_id;
+
+        $data = $request->validate([
+            'name'        => ['required', 'string', 'max:255'],
+            'report_type' => ['required', 'in:financial,inventory,hr'],
+            'frequency'   => ['required', 'in:daily,weekly,monthly'],
+            'recipients'  => ['required', 'array', 'min:1'],
+            'recipients.*' => ['email'],
+            'filters'     => ['nullable', 'array'],
+            'is_active'   => ['boolean'],
+        ]);
+
+        $schedule = ReportSchedule::create([
+            ...$data,
+            'tenant_id'  => $tenantId,
+            'user_id'    => $request->user()->id,
+            'is_active'  => $data['is_active'] ?? true,
+            'next_run_at' => (new ReportSchedule())->fill($data)->computeNextRunAt(),
+        ]);
+
+        return $this->success($schedule, 201);
+    }
+
+    public function show(Request $request, ReportSchedule $reportSchedule): JsonResponse
+    {
+        return $this->success($reportSchedule->load('user:id,name'));
+    }
+
+    public function update(Request $request, ReportSchedule $reportSchedule): JsonResponse
+    {
+        $data = $request->validate([
+            'name'        => ['sometimes', 'string', 'max:255'],
+            'report_type' => ['sometimes', 'in:financial,inventory,hr'],
+            'frequency'   => ['sometimes', 'in:daily,weekly,monthly'],
+            'recipients'  => ['sometimes', 'array', 'min:1'],
+            'recipients.*' => ['email'],
+            'filters'     => ['nullable', 'array'],
+            'is_active'   => ['boolean'],
+        ]);
+
+        $reportSchedule->update($data);
+
+        return $this->success($reportSchedule->fresh());
+    }
+
+    public function destroy(ReportSchedule $reportSchedule): JsonResponse
+    {
+        $reportSchedule->delete();
+        return $this->success(['message' => 'Report schedule deleted.']);
+    }
+
+    public function sendNow(ReportSchedule $reportSchedule): JsonResponse
+    {
+        SendScheduledReportJob::dispatch($reportSchedule);
+        return $this->success(['message' => 'Report queued for delivery.']);
+    }
+}

erp/app/Jobs/SendScheduledReportJob.php

@@ -0,0 +1,114 @@
+<?php
+
+namespace App\Jobs;
+
+use App\Mail\ScheduledReportMail;
+use App\Models\ReportSchedule;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Mail;
+use App\Modules\Finance\Models\Invoice;
+use App\Modules\Finance\Models\Bill;
+use App\Modules\Inventory\Models\Product;
+use App\Modules\Inventory\Models\StockMovement;
+use App\Modules\HR\Models\Employee;
+use App\Modules\HR\Models\PayrollRun;
+
+class SendScheduledReportJob implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public int $tries = 3;
+
+    public function __construct(public readonly ReportSchedule $schedule) {}
+
+    public function handle(): void
+    {
+        $data = match ($this->schedule->report_type) {
+            'financial' => $this->buildFinancialReport(),
+            'inventory' => $this->buildInventoryReport(),
+            'hr'        => $this->buildHrReport(),
+            default     => [],
+        };
+
+        foreach ($this->schedule->recipients as $email) {
+            Mail::to($email)->send(new ScheduledReportMail($this->schedule, $data));
+        }
+
+        $this->schedule->update([
+            'last_sent_at' => now(),
+            'next_run_at'  => $this->schedule->computeNextRunAt(),
+        ]);
+    }
+
+    private function buildFinancialReport(): array
+    {
+        $tenantId = $this->schedule->tenant_id;
+        $year     = now()->year;
+
+        $invoiceSummary = Invoice::where('tenant_id', $tenantId)
+            ->whereYear('created_at', $year)
+            ->selectRaw('SUM(total) as total_invoiced, SUM(CASE WHEN status = \'paid\' THEN total ELSE 0 END) as total_paid, SUM(CASE WHEN status != \'paid\' THEN total ELSE 0 END) as total_outstanding, SUM(CASE WHEN status != \'paid\' AND due_date < datetime(\'now\') THEN total ELSE 0 END) as total_overdue')
+            ->first();
+
+        $monthlyRevenue = DB::table('invoices')
+            ->join('invoice_items', 'invoices.id', '=', 'invoice_items.invoice_id')
+            ->where('invoices.tenant_id', $tenantId)
+            ->where('invoices.status', 'paid')
+            ->whereYear('invoices.created_at', $year)
+            ->selectRaw("strftime('%m', invoices.created_at) as month, SUM(invoice_items.quantity * invoice_items.unit_price) as revenue")
+            ->groupBy('month')
+            ->orderBy('month')
+            ->get()
+            ->toArray();
+
+        return [
+            'invoice_summary' => $invoiceSummary ? $invoiceSummary->toArray() : [],
+            'monthly_revenue' => $monthlyRevenue,
+        ];
+    }
+
+    private function buildInventoryReport(): array
+    {
+        $tenantId  = $this->schedule->tenant_id;
+        $stockStats = Product::where('tenant_id', $tenantId)
+            ->selectRaw('COUNT(*) as total_products, SUM(stock_quantity * cost_price) as stock_value')
+            ->first();
+
+        $lowStockCount = Product::where('tenant_id', $tenantId)
+            ->whereColumn('stock_quantity', '<=', 'reorder_point')
+            ->where('reorder_point', '>', 0)
+            ->count();
+
+        return [
+            'total_products'  => $stockStats?->total_products ?? 0,
+            'stock_value'     => $stockStats?->stock_value ?? 0,
+            'low_stock_count' => $lowStockCount,
+        ];
+    }
+
+    private function buildHrReport(): array
+    {
+        $tenantId = $this->schedule->tenant_id;
+
+        $headcount = Employee::where('tenant_id', $tenantId)
+            ->selectRaw('status, COUNT(*) as count')
+            ->groupBy('status')
+            ->get()
+            ->toArray();
+
+        $payrollSummary = PayrollRun::where('tenant_id', $tenantId)
+            ->whereYear('created_at', now()->year)
+            ->selectRaw('SUM(total_gross) as total_gross, SUM(total_net) as total_net, COUNT(*) as run_count')
+            ->first();
+
+        return [
+            'headcount'       => $headcount,
+            'payroll_summary' => $payrollSummary ? $payrollSummary->toArray() : [],
+        ];
+    }
+}

erp/app/Mail/ScheduledReportMail.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace App\Mail;
+
+use App\Models\ReportSchedule;
+use Illuminate\Mail\Mailable;
+use Illuminate\Mail\Mailables\Content;
+use Illuminate\Mail\Mailables\Envelope;
+use Illuminate\Queue\SerializesModels;
+
+class ScheduledReportMail extends Mailable
+{
+    use SerializesModels;
+
+    public function __construct(
+        public readonly ReportSchedule $schedule,
+        public readonly array $reportData,
+    ) {}
+
+    public function envelope(): Envelope
+    {
+        return new Envelope(
+            subject: "[{$this->schedule->report_type}] {$this->schedule->name} Report"
+        );
+    }
+
+    public function content(): Content
+    {
+        return new Content(
+            view: 'emails.scheduled-report',
+            with: [
+                'schedule'   => $this->schedule,
+                'reportData' => $this->reportData,
+            ]
+        );
+    }
+}