docs(openspec): add reporting API contract documentation

Add comprehensive API documentation for the reporting endpoint: - Request/response structure - View type inference (did/is/will) - Blank vs explicit zero semantics - Status values and error responses Related to enhanced-allocation change.
2026-03-08 18:22:27 -04:00
parent 3324c4f156
commit b7bbfb45c0
27 changed files with 1632 additions and 35 deletions
--- a/backend/app/Http/Controllers/Api/ProjectMonthPlanController.php
+++ b/backend/app/Http/Controllers/Api/ProjectMonthPlanController.php
@@ -0,0 +1,151 @@
+<?php
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Http\Resources\ProjectMonthPlanResource;
+use App\Models\ProjectMonthPlan;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Validator;
+
+class ProjectMonthPlanController extends Controller
+{
+    /**
+     * GET /api/project-month-plans?year=2026
+     * Returns month-plan grid payload by project/month for the year.
+     */
+    public function index(Request $request): JsonResponse
+    {
+        $year = $request->query('year', date('Y'));
+        
+        $startDate = "{$year}-01-01";
+        $endDate = "{$year}-12-01";
+
+        $plans = ProjectMonthPlan::whereBetween('month', [$startDate, $endDate])
+            ->with('project')
+            ->get()
+            ->groupBy('project_id');
+
+        // Get all active projects for the year
+        $projects = \App\Models\Project::where('active', true)->get();
+
+        // Build grid payload
+        $data = $projects->map(function ($project) use ($plans, $year) {
+            $projectPlans = $plans->get($project->id, collect());
+            
+            $months = [];
+            for ($month = 1; $month <= 12; $month++) {
+                $monthDate = sprintf('%04d-%02d-01', $year, $month);
+                $plan = $projectPlans->firstWhere('month', $monthDate);
+                
+                $months[$monthDate] = $plan 
+                    ? [
+                        'id' => $plan->id,
+                        'planned_hours' => $plan->planned_hours,
+                        'is_blank' => $plan->planned_hours === null,
+                    ]
+                    : null;
+            }
+
+            return [
+                'project_id' => $project->id,
+                'project_name' => $project->title,
+                'approved_estimate' => $project->approved_estimate,
+                'months' => $months,
+            ];
+        });
+
+        // Calculate reconciliation status for each project
+        $data->each(function (&$project) {
+            $project['plan_sum'] = collect($project['months'])
+                ->filter(fn ($m) => $m !== null && $m['planned_hours'] !== null)
+                ->sum('planned_hours');
+            
+            $approved = $project['approved_estimate'] ?? 0;
+            if ($approved > 0) {
+                if ($project['plan_sum'] > $approved) {
+                    $project['reconciliation_status'] = 'OVER';
+                } elseif ($project['plan_sum'] < $approved) {
+                    $project['reconciliation_status'] = 'UNDER';
+                } elseif ($project['plan_sum'] == $approved) {
+                    $project['reconciliation_status'] = 'MATCH';
+                } else {
+                    $project['reconciliation_status'] = 'UNDER';
+                }
+            } else {
+                $project['reconciliation_status'] = 'UNDER'; // No estimate = under
+            }
+        });
+
+        return response()->json([
+            'data' => $data,
+            'meta' => [
+                'year' => (int) $year,
+            ],
+        ]);
+    }
+
+    /**
+     * PUT /api/project-month-plans/bulk
+     * Bulk upsert month plan cells.
+     */
+    public function bulkUpdate(Request $request): JsonResponse
+    {
+        $validator = Validator::make($request->all(), [
+            'year' => 'required|integer|min:2020|max:2100',
+            'items' => 'required|array',
+            'items.*.project_id' => 'required|uuid|exists:projects,id',
+            'items.*.month' => 'required|date_format:Y-m',
+            'items.*.planned_hours' => 'nullable|numeric|min:0',
+        ]);
+
+        if ($validator->fails()) {
+            return response()->json([
+                'message' => 'Validation failed',
+                'errors' => $validator->errors(),
+            ], 422);
+        }
+
+        $year = $request->input('year');
+        $items = $request->input('items');
+        $created = 0;
+        $updated = 0;
+        $cleared = 0;
+
+        foreach ($items as $item) {
+            $projectId = $item['project_id'];
+            $month = $item['month'] . '-01'; // Convert YYYY-MM to YYYY-MM-01
+            $plannedHours = $item['planned_hours']; // Can be null to clear
+
+            $plan = ProjectMonthPlan::firstOrNew([
+                'project_id' => $projectId,
+                'month' => $month,
+            ]);
+
+            if ($plannedHours === null && $plan->exists) {
+                // Clear semantics: delete the row to represent blank
+                $plan->delete();
+                $cleared++;
+            } elseif ($plannedHours !== null) {
+                $plan->planned_hours = $plannedHours;
+                $plan->save();
+                
+                if (!$plan->wasRecentlyCreated) {
+                    $updated++;
+                } else {
+                    $created++;
+                }
+            }
+        }
+
+        return response()->json([
+            'message' => 'Bulk update complete',
+            'summary' => [
+                'created' => $created,
+                'updated' => $updated,
+                'cleared' => $cleared,
+            ],
+        ]);
+    }
+}