diff --git a/Docs/Tasks.md b/Docs/Tasks.md index 0235c86..f444c14 100644 --- a/Docs/Tasks.md +++ b/Docs/Tasks.md @@ -1,187 +1,3 @@ -## [Frontend] ErrorBoundary — non-standard `componentStack` property - -**Where found** - -- `frontend/src/components/ErrorBoundary.tsx` — accesses `errorInfo.componentStack` -- Property not in `React.ErrorInfo` public type definitions - -**Why this is needed** - -Accessing `errorInfo.componentStack` produces TypeScript error under strict mode. Property is React DevTools implementation detail, may change without notice. - -**Goal** - -Remove dependency on `errorInfo.componentStack`, use alternative for stack information. - -**What to do** - -1. Check what `recordCritical` does with `componentStack` parameter -2. Consider using standard `Error.prototype.stack` instead -3. Or cast `errorInfo` to `any` with comment explaining trade-off: - ```typescript - const stack = (errorInfo as any).componentStack as string | undefined; - // TODO: Remove when React types include componentStack - ``` -4. Handle case where `componentStack` is `undefined` - -**Possible traps and issues** - -- `Error.prototype.stack` contains JavaScript call stack, not React component stack -- Casting to `any` suppresses type checking — ensure it's documented -- In production builds `componentStack` may be empty or absent - -**Docs changes needed** - -- Update `Docs/Architekture.md` § 3.2 (Components) — note that `ErrorBoundary` uses React-internal error info - -**Doc references** - -- `frontend/src/components/ErrorBoundary.tsx` -- `Docs/Architekture.md` § 3.2 (Components section) - ---- - -## [Frontend] No loading skeleton for Login page - -**Where found** - -- `frontend/src/pages/LoginPage.tsx` — renders password form immediately without checking session validation state - -**Why this is needed** - -`AuthProvider` validates session on mount. During validation (network round-trip), `LoginPage` renders form. If user already has valid session, they briefly see login page before redirect — "flash" of wrong page. - -**Goal** - -Show loading state (spinner or skeleton) while session validation in progress. - -**What to do** - -1. Add `useSessionValidation` call to `LoginPage` to get `isValidating` flag -2. If `isValidating`, return `` -3. Alternatively, have `AuthProvider` expose `isValidating` state that `LoginPage` can read -4. Ensure redirect to dashboard happens automatically via `useEffect` - -**Possible traps and issues** - -- `useSessionValidation` may not expose `isValidating` — check hook implementation -- Ensure loading spinner is consistent with Fluent UI design language -- Redirect logic must handle `?next=` query parameter - -**Docs changes needed** - -- No documentation changes needed — UX improvement to existing component - -**Doc references** - -- `frontend/src/pages/LoginPage.tsx` -- `frontend/src/providers/AuthProvider.tsx` - ---- - -## [CRITICAL] Backend session cache not cluster-safe - -**Where found** - -- `backend/app/startup.py:66-91` — `verify_bangui_workers()` validates `BANGUI_WORKERS` env var but only if explicitly set -- `backend/app/utils/session_cache.py` — in-memory cache stored on `app.state` (process-local) -- Multi-worker deployments use separate worker processes with separate `app.state` - -**Why this is needed** - -Multi-worker deployments (e.g., `gunicorn -w 4`) create separate worker processes. Each has its own in-memory `app.state`, so sessions cached in Worker A are invisible to Workers B, C, D. Request landing on different worker shows session invalid — users randomly logged out. - -**Goal** - -Ensure multi-worker deployments either prevented at startup or migrate to shared session store (Redis, PostgreSQL). - -**What to do** - -**Option A (Strict single-worker):** -- Add runtime detection of actual worker count (not just env var checking) -- Fail startup if multi-worker scenario detected -- Document single-worker requirement prominently - -**Option B (Support multi-worker):** -- Migrate session cache to Redis or PostgreSQL -- Update `app/utils/session_cache.py` to use distributed backend -- Add `BANGUI_REDIS_URL` or similar to config - -**Immediate mitigation:** -- Document in deployment guide that `BANGUI_WORKERS=1` is mandatory -- Add validation that fails loudly if `BANGUI_WORKERS != 1` - -**Possible traps and issues** - -- `uvicorn --workers N` creates N processes, each with separate `app.state` -- Environment variable validation easily bypassed using command-line flag -- Detecting actual worker count at runtime is tricky — consider `os.getpid()` and shared lock file - -**Docs changes needed** - -- Update `Docs/Deployment.md` § Deployment Constraints — explicitly document single-worker requirement -- Add troubleshooting entry: "Why am I randomly logged out?" → Check `BANGUI_WORKERS` -- Update `Docker/docker-compose.yml` with comment explaining requirement - -**Doc references** - -- `Docs/Deployment.md` (deployment constraints) -- `backend/app/startup.py` (worker validation) -- `backend/app/utils/session_cache.py` (session cache) - ---- - -## [CRITICAL] Frontend-Backend type generation drift - -**Where found** - -- `frontend/src/types/` — manually maintained Pydantic model transcriptions -- `backend/app/models/` — source Pydantic models -- No build-time validation or code generation linking them - -**Why this is needed** - -Types manually copied from Python models. When backend model changes, frontend types not updated automatically. Frontend uses stale types, causing runtime errors, type errors at build time, or silent UI bugs. - -**Goal** - -Implement automated type synchronization from backend schema to frontend types, validated at build time. - -**What to do** - -1. **Recommended:** Generate TypeScript types from OpenAPI schema - ```bash - openapi-typescript http://localhost:8000/openapi.json -o src/types/generated.ts - ``` - -2. **Setup:** - - Ensure backend exposes OpenAPI schema at `/openapi.json` (FastAPI has this built-in) - - Add `openapi-typescript` to `frontend/package.json` devDependencies - - Generate types in pre-build step: `npm run generate:types` - - Import types from generated file, not hand-written - - Add CI check: fail build if generated types don't match committed types - -3. **Alternative:** Use `typed-rest-client` or `msw` with type generation - -**Possible traps and issues** - -- OpenAPI schema must be kept up-to-date — CI validation must enforce -- Generated types may have different names than hand-written types — migration needed -- Private/internal model fields should be excluded from schema - -**Docs changes needed** - -- Update `Docs/Web-Development.md` § Type Generation — document workflow -- Add pre-commit hook documentation -- Update `Docs/Backend-Development.md` to note API changes must keep schema in sync - -**Doc references** - -- `Docs/Web-Development.md` (type generation) -- `Docs/Backend-Development.md` (API changes) - ---- - ## [CRITICAL] Docker containers lack resource limits **Where found**