RHL-002-refactor: enhance API routes with detailed documentation and error handling

app/api/branches/[branch]/[year]/[month]/days/route.js

@@ -1,6 +1,13 @@
+// app/api/branches/[branch]/[year]/[month]/days/route.js
 import { NextResponse } from "next/server";
 import { listDays } from "@/lib/storage";
 
+/**
+ * GET /api/branches/[branch]/[year]/[month]/days
+ *
+ * Returns the list of day folders for a given branch, year, and month.
+ * Example: /api/branches/NL01/2024/10/days → { days: ["01", "02", ...] }
+ */
 export async function GET(request, ctx) {
 	const { branch, year, month } = await ctx.params;
 	console.log("[/api/branches/[branch]/[year]/[month]/days] params:", {
@@ -18,12 +25,11 @@ export async function GET(request, ctx) {
 
 	try {
 		const days = await listDays(branch, year, month);
+
 		return NextResponse.json({ branch, year, month, days });
 	} catch (error) {
-		console.error(
-			"[/api/branches/[branch]/[year]/[month]/days] Fehler:",
-			error
-		);
+		console.error("[/api/branches/[branch]/[year]/[month]/days] Error:", error);
+
 		return NextResponse.json(
 			{ error: "Fehler beim Lesen der Tage: " + error.message },
 			{ status: 500 }

app/api/branches/[branch]/[year]/months/route.js

@@ -1,6 +1,13 @@
+// app/api/branches/[branch]/[year]/months/route.js
 import { NextResponse } from "next/server";
 import { listMonths } from "@/lib/storage";
 
+/**
+ * GET /api/branches/[branch]/[year]/months
+ *
+ * Returns the list of month folders for a given branch and year.
+ * Example: /api/branches/NL01/2024/months → { months: ["01", "02", ...] }
+ */
 export async function GET(request, ctx) {
 	const { branch, year } = await ctx.params;
 	console.log("[/api/branches/[branch]/[year]/months] params:", {
@@ -17,9 +24,11 @@ export async function GET(request, ctx) {
 
 	try {
 		const months = await listMonths(branch, year);
+
 		return NextResponse.json({ branch, year, months });
 	} catch (error) {
-		console.error("[/api/branches/[branch]/[year]/months] Fehler:", error);
+		console.error("[/api/branches/[branch]/[year]/months] Error:", error);
+
 		return NextResponse.json(
 			{ error: "Fehler beim Lesen der Monate: " + error.message },
 			{ status: 500 }

app/api/branches/[branch]/years/route.js

@@ -1,10 +1,19 @@
+// app/api/branches/[branch]/years/route.js
 import { NextResponse } from "next/server";
 import { listYears } from "@/lib/storage";
 
+/**
+ * GET /api/branches/[branch]/years
+ *
+ * Returns the list of year folders for a given branch.
+ * Example: /api/branches/NL01/years → { branch: "NL01", years: ["2023", "2024"] }
+ */
 export async function GET(request, ctx) {
+	// Next.js 16: params are resolved asynchronously via ctx.params
 	const { branch } = await ctx.params;
 	console.log("[/api/branches/[branch]/years] params:", { branch });
 
+	// Basic validation of required params
 	if (!branch) {
 		return NextResponse.json(
 			{ error: "branch Parameter fehlt" },
@@ -14,9 +23,11 @@ export async function GET(request, ctx) {
 
 	try {
 		const years = await listYears(branch);
+
 		return NextResponse.json({ branch, years });
 	} catch (error) {
-		console.error("[/api/branches/[branch]/years] Fehler:", error);
+		console.error("[/api/branches/[branch]/years] Error:", error);
+
 		return NextResponse.json(
 			{ error: "Fehler beim Lesen der Jahre: " + error.message },
 			{ status: 500 }

app/api/branches/route.js

@@ -2,12 +2,22 @@
 import { NextResponse } from "next/server";
 import { listBranches } from "@/lib/storage";
 
+/**
+ * GET /api/branches
+ *
+ * Returns the list of branches (e.g. ["NL01", "NL02", ...]) based on the
+ * directory names under NAS_ROOT_PATH.
+ */
 export async function GET() {
 	try {
 		const branches = await listBranches();
+
 		return NextResponse.json({ branches });
 	} catch (error) {
-		console.error("[api/branches] Fehler:", error);
+		// Log the full error on the server for debugging
+		console.error("[api/branches] Error reading branches:", error);
+
+		// Return a generic error message to the client
 		return NextResponse.json(
 			{ error: "Fehler beim Lesen der Niederlassungen" },
 			{ status: 500 }

app/api/files/route.js

@@ -1,6 +1,14 @@
+// app/api/files/route.js
 import { NextResponse } from "next/server";
 import { listFiles } from "@/lib/storage";
 
+/**
+ * GET /api/files?branch=&year=&month=&day=
+ *
+ * Returns the list of PDF files for a specific branch + date.
+ * Example:
+ *   /api/files?branch=NL01&year=2024&month=10&day=23
+ */
 export async function GET(request) {
 	const { searchParams } = new URL(request.url);
 	const branch = searchParams.get("branch");
@@ -10,6 +18,7 @@ export async function GET(request) {
 
 	console.log("[/api/files] query:", { branch, year, month, day });
 
+	// Validate required query params
 	if (!branch || !year || !month || !day) {
 		return NextResponse.json(
 			{ error: "branch, year, month, day sind erforderlich" },
@@ -19,9 +28,11 @@ export async function GET(request) {
 
 	try {
 		const files = await listFiles(branch, year, month, day);
+
 		return NextResponse.json({ branch, year, month, day, files });
 	} catch (error) {
-		console.error("[/api/files] Fehler:", error);
+		console.error("[/api/files] Error:", error);
+
 		return NextResponse.json(
 			{ error: "Fehler beim Lesen der Dateien: " + error.message },
 			{ status: 500 }

app/api/health/route.js

@@ -3,23 +3,32 @@ import { NextResponse } from "next/server";
 import { getDb } from "@/lib/db";
 import fs from "fs/promises";
 
+/**
+ * GET /api/health
+ *
+ * Health check endpoint:
+ * - Verifies database connectivity.
+ * - Verifies readability of NAS_ROOT_PATH.
+ */
 export async function GET() {
 	const result = {
 		db: null,
 		nas: null,
 	};
 
-	// DB-Check
+	// --- Database health -------------------------------------------------------
 	try {
 		const db = await getDb();
 		await db.command({ ping: 1 });
 		result.db = "ok";
 	} catch (error) {
+		// We don't throw here – we report the error in the JSON result
 		result.db = `error: ${error.message}`;
 	}
 
-	// NAS-Check
+	// --- NAS health ------------------------------------------------------------
 	const nasPath = process.env.NAS_ROOT_PATH || "/mnt/niederlassungen";
+
 	try {
 		const entries = await fs.readdir(nasPath);
 		result.nas = {
@@ -27,7 +36,8 @@ export async function GET() {
 			entriesSample: entries.slice(0, 5),
 		};
 	} catch (error) {
-		// Lokal auf dem Mac ist der Pfad wahrscheinlich leer oder existiert nicht → Fehler ist ok
+		// It's okay if NAS is not available in some environments (like local dev),
+		// we just propagate the error message in the health object.
 		result.nas = `error: ${error.message}`;
 	}