RHL-005-add(docs): create API documentation for HTTP endpoints and configuration

Docs/api.md

@@ -0,0 +1,242 @@
+<!-- --------------------------------------------------------------------------- -->
+
+<!-- Ordner: Docs -->
+
+<!-- Datei: api.md -->
+
+<!-- Relativer Pfad: Docs/api.md -->
+
+<!-- --------------------------------------------------------------------------- -->
+
+# API Overview
+
+This document describes the HTTP API exposed by the application using Next.js **Route Handlers** in the App Router (`app/api/*/route.js`).
+
+All routes below are served under the `/api` prefix.
+
+---
+
+## 1. Configuration Dependencies
+
+The API expects a valid server configuration.
+
+Required environment variables:
+
+- `MONGODB_URI` — database connection string (used by `lib/db.js`).
+- `SESSION_SECRET` — JWT signing secret for session cookies.
+- `NAS_ROOT_PATH` — NAS mount root for storage operations.
+
+Optional environment variables:
+
+- `SESSION_COOKIE_SECURE` — override for the cookie `Secure` flag (`true`/`false`).
+
+The environment can be validated via:
+
+- `lib/config/validateEnv.js`
+- `scripts/validate-env.mjs`
+
+In Docker/production-like runs, execute `node scripts/validate-env.mjs` before starting the server to fail fast.
+
+---
+
+## 2. Authentication & Authorization
+
+### 2.1 Sessions
+
+Authentication uses a signed JWT stored in an HTTP-only cookie (`auth_session`).
+
+To access protected endpoints:
+
+1. `POST /api/auth/login` to obtain the cookie.
+2. Send subsequent requests with that cookie.
+
+Notes:
+
+- In production-like setups, cookies should be `Secure` and the app should run behind HTTPS.
+- For local HTTP testing (`http://localhost:3000`), set `SESSION_COOKIE_SECURE=false` in your local docker env file.
+
+### 2.2 RBAC (Branch-Level)
+
+RBAC is enforced on filesystem-related endpoints.
+
+- **401 Unauthorized**: no valid session
+- **403 Forbidden**: session exists but branch access is not allowed
+
+---
+
+## 3. General Conventions
+
+- All endpoints return JSON.
+
+- Error responses use:
+
+  ```json
+  { "error": "Human-readable error message" }
+  ```
+
+- Route handlers use Web `Request` / `Response` primitives.
+
+- For dynamic routes, Next.js 16 resolves parameters asynchronously via `ctx.params`.
+
+---
+
+## 4. Endpoints
+
+### 4.1 `GET /api/health`
+
+**Purpose**
+
+Health check endpoint:
+
+- Verifies database connectivity (`db.command({ ping: 1 })`).
+- Verifies readability of `NAS_ROOT_PATH`.
+
+**Authentication**: not required.
+
+**Response 200 (example)**
+
+```json
+{
+	"db": "ok",
+	"nas": {
+		"path": "/mnt/niederlassungen",
+		"entriesSample": ["@Recently-Snapshot", "NL01", "NL02"]
+	}
+}
+```
+
+---
+
+### 4.2 `POST /api/auth/login`
+
+**Purpose**
+
+Authenticate a user and set the session cookie.
+
+**Authentication**: not required.
+
+**Request body (JSON)**
+
+```json
+{ "username": "example.user", "password": "plain-text-password" }
+```
+
+**Responses**
+
+- `200 { "ok": true }`
+- `400 { "error": "Invalid request body" }`
+- `400 { "error": "Missing username or password" }`
+- `401 { "error": "Invalid credentials" }`
+- `500 { "error": "Internal server error" }`
+
+---
+
+### 4.3 `GET /api/auth/logout`
+
+**Purpose**
+
+Destroy the current session by clearing the cookie.
+
+**Authentication**: recommended (but endpoint is idempotent).
+
+**Response**
+
+- `200 { "ok": true }`
+
+---
+
+### 4.4 `GET /api/branches`
+
+Returns the list of branches (e.g. `["NL01", "NL02"]`).
+
+**Authentication**: required.
+
+**RBAC behavior**
+
+- `branch` role → only own branch
+- `admin`/`dev` → all branches
+
+**Response 200**
+
+```json
+{ "branches": ["NL01", "NL02"] }
+```
+
+---
+
+### 4.5 `GET /api/branches/[branch]/years`
+
+Example: `/api/branches/NL01/years`
+
+**Authentication**: required.
+
+**Response 200**
+
+```json
+{ "branch": "NL01", "years": ["2023", "2024"] }
+```
+
+---
+
+### 4.6 `GET /api/branches/[branch]/[year]/months`
+
+Example: `/api/branches/NL01/2024/months`
+
+**Authentication**: required.
+
+**Response 200**
+
+```json
+{ "branch": "NL01", "year": "2024", "months": ["01", "02", "10"] }
+```
+
+---
+
+### 4.7 `GET /api/branches/[branch]/[year]/[month]/days`
+
+Example: `/api/branches/NL01/2024/10/days`
+
+**Authentication**: required.
+
+**Response 200**
+
+```json
+{ "branch": "NL01", "year": "2024", "month": "10", "days": ["01", "23"] }
+```
+
+---
+
+### 4.8 `GET /api/files?branch=&year=&month=&day=`
+
+Example:
+
+```text
+/api/files?branch=NL01&year=2024&month=10&day=23
+```
+
+**Authentication**: required.
+
+**Response 200**
+
+```json
+{
+	"branch": "NL01",
+	"year": "2024",
+	"month": "10",
+	"day": "23",
+	"files": [{ "name": "test.pdf", "relativePath": "NL01/2024/10/23/test.pdf" }]
+}
+```
+
+---
+
+## 5. Adding New Endpoints
+
+When adding new endpoints:
+
+1. Define URL + method.
+2. Implement a `route.js` under `app/api/...`.
+3. Use `lib/storage` for filesystem access.
+4. Enforce RBAC (`getSession()` + `canAccessBranch()` as needed).
+5. Add route tests (Vitest).
+6. Update this document.