251206:1710 specs: frontend plan P1,P3 wait Verification

specs/09-history/2025-12-06_p0-build-fixes.md

@@ -0,0 +1,53 @@
+# 2025-12-06 P0 Build Fix Summary
+
+**Date:** 2025-12-06
+**Status:** ✅ P0 Complete
+**Objective:** Resolve Critical Build Failures
+
+## Executive Summary
+This session addressed critical TypeScript build errors in the backend that were preventing successful compilation (`pnpm build`). These errors originated from stricter TypeScript settings interacting with legacy P0 code and recent refactors.
+
+**Result:** `pnpm build` now passes successfully.
+
+## Fixed Issues
+
+### 1. Workflow DSL Parser (`parser.service.ts`)
+- **Issue:** Property mismatches between DSL JSON and `WorkflowDefinition` entity (camelCase vs snake_case).
+- **Fix:** Mapped properties correctly:
+  - `dsl.name` -> `entity.workflow_code`
+  - `dsl.isActive` -> `entity.is_active`
+  - `dsl.dslContent` -> `entity.dsl` (Direct JSON storage)
+- **Issue:** Strict strict-mode errors in `catch(error)` blocks (unknown type).
+- **Fix:** Cast error to `any` and added fallback logic.
+
+### 2. Permissions Guard (`permissions.guard.ts`)
+- **Issue:** Strict type checking failures in `Ability.can(action, subject)`.
+- **Fix:** Explicitly cast action and subject to `any` to satisfy the CASL Ability type signature.
+
+### 3. Ability Factory (`ability.factory.ts`)
+- **Issue:** `item.constructor` access on potentially unknown type.
+- **Fix:** Explicitly typed `item` as `any` in `detectSubjectType`.
+
+### 4. RBAC Guard (`rbac.guard.ts`)
+- **Issue:** Incorrect import (`PERMISSION_KEY` vs `PERMISSIONS_KEY`) and mismatch with updated Decorator (Array vs String).
+- **Fix:** Updated to use `PERMISSIONS_KEY` and handle array of permissions. Fixed import paths (removed `.js`).
+
+### 5. Document Numbering Service
+- **Issue:** Unknown error type in catch block.
+- **Fix:** Cast error to `any` for logging.
+
+### 6. P0-1: RBAC Tests (`ability.factory.spec.ts`)
+- **Issue:** Tests failed to load due to `Cannot find module ... .js`.
+- **Fix:** Removed `.js` extensions from imports in `organization.entity.ts`, `project.entity.ts`, `contract.entity.ts`, `routing-template.entity.ts`.
+- **Issue:** Global Admin test failed (`can('manage', 'all')` -> false).
+- **Fix:**
+    1. Updated `detectSubjectType` to return string subjects directly (fixing CASL string matching).
+    2. Moved `system.manage_all` check to top of `parsePermission` to prevent incorrect splitting.
+- **Verification:** `pnpm test src/common/auth/casl/ability.factory.spec.ts` -> **PASS** (7/7 tests).
+
+## Verification
+- Ran `pnpm build`.
+- **Outcome:** Success (Exit code 0).
+
+## Next Steps
+- Continue to P3 (Admin Panel) or P2-5 (Tests) knowing the foundation is stable.

specs/09-history/2025-12-06_p1-frontend-plan.md

@@ -0,0 +1,33 @@
+# P1-Frontend: Setup & Authentication Plan
+
+## Goal
+Finalize frontend setup and implement robust Authentication connecting to the NestJS Backend (P2-2 Refresh Token support).
+
+## Status Analysis
+- **P1-1 (Setup):** ✅ Project structure, Tailwind, Shadcn/UI are already present.
+- **P1-2 (Auth):** 🚧 `lib/auth.ts` exists but lacks `refreshToken` rotation logic. Types need verification.
+
+## Proposed Changes
+
+### 1. Type Definitions (`types/next-auth.d.ts`)
+- [ ] Add `refreshToken`, `accessTokenExpires` (optional), and `error` field to `Session` and `JWT` types.
+
+### 2. Auth Configuration (`lib/auth.ts`)
+- [ ] Update `authorize` to store `refresh_token` from Backend response.
+- [ ] Implement `refreshToken` rotation logic in `jwt` callback:
+  - Check if token is expired.
+  - If expired, call backend POST `/auth/refresh`.
+  - Update `accessToken` and `refreshToken`.
+  - Handle refresh errors (Force sign out).
+
+### 3. Login Page (`app/(auth)/login/page.tsx`)
+- [ ] Polish Error Handling (Use Toasts instead of alerts).
+- [ ] Ensure redirect works correctly.
+
+### 4. Middleware (`middleware.ts`)
+- [ ] Verify middleware protects dashboard routes.
+
+## Verification Plan
+1.  **Manual Test:** Login with valid credentials.
+2.  **Inspection:** Check LocalStorage/Cookies (NextAuth session cookie).
+3.  **Token Rotation:** Wait for short access token expiry (if configurable) or manually invalidate, and verify seamless refresh.

specs/09-history/2025-12-06_p2-completion.md

@@ -0,0 +1,61 @@
+# 2025-12-06 P2 Implementation Summary
+
+**Date:** 2025-12-06
+**Status:** ✅ P2 Complete
+**Objective:** Enhance Security and Documentation
+
+## Executive Summary
+This session focused on completing Priority 2 (P2) tasks for the Backend v1.4.3. All P2 objectives were met, including API documentation, secure session management, observability, and API hardening.
+
+**Note:** While P2 features are complete and verified by code review, the `pnpm build` process is currently failing due to pre-existing issues in P0 modules (Casl Ability & Workflow DSL) that were outside the scope of this session. These build errors must be addressed in the next session (P0 Urgent).
+
+## Completed Tasks
+
+### ✅ P2-1: Swagger API Documentation
+- **Objective:** Improve API discoverability.
+- **Changes:**
+  - Configured `SwaggerModule` at `/docs`.
+  - Added full documentation for `AuthController`, `CorrespondenceController`, `RfaController`, and `UserController`.
+  - Decorated DTOs with `@ApiProperty` for schema clarity.
+
+### ✅ P2-2: Refresh Token Mechanism
+- **Objective:** Secure session management implementation (ADR-016).
+- **Changes:**
+  - Created `RefreshToken` entity (hashed tokens).
+  - Implemented `AuthService` logic for:
+    - **Token Generation:** Access (15m) + Refresh (7d).
+    - **Storage:** Hashed in DB.
+    - **Rotation:** Refresh token reuse triggers rotation.
+    - **Revocation:** Security mechanism to invalidate stolen token families.
+  - Exposed `POST /auth/refresh` endpoint.
+
+### ✅ P2-3: Prometheus Metrics
+- **Objective:** System observability.
+- **Changes:**
+  - Integrated `@willsoto/nestjs-prometheus` and opened `/metrics`.
+  - Implemented standard metrics (CPU, Memory).
+  - Added custom HTTP metrics (`http_requests_total`, `http_request_duration_seconds`) via `PerformanceInterceptor`.
+  - Refactored `MonitoringModule` for modularity.
+
+### ✅ P2-4: Rate Limiting & Security Headers
+- **Objective:** API Hardening.
+- **Changes:**
+  - **Throttler:** Verified global rate limit (100/min) and strict login limit (5/min).
+  - **Helmet:** Configured Security Headers with custom CSP to support Swagger UI.
+  - **CORS:** Dynamic configuration connected to `ConfigService`.
+
+---
+
+## Known Issues (P0 - Urgent)
+
+The following build errors were identified but deferred as they belong to P0 scope:
+
+1.  **AbilityFactory (CASL):** TypeScript mismatch in Permission loops (`CASL integration`).
+2.  **WorkflowEngine (DSL):** TypeScript mismatch in Zod Schema validation (`WorkflowParser`).
+
+**Action Plan:** These must be fixed immediately in the next session to restore build stability.
+
+## Artifacts Created
+- `specs/09-history/2025-12-06_p2-completion.md` (This file)
+- `src/common/auth/entities/refresh-token.entity.ts`
+- `src/modules/monitoring/` (Refactored)

specs/09-history/2025-12-06_p3-admin-panel-plan.md

@@ -0,0 +1,44 @@
+# P3-1: Frontend Admin Panel Implementation Plan
+
+## Goal
+Implement a functional Admin Panel for User and Master Data Management, connected to existing Backend APIs.
+
+## Scope
+1.  **Admin Layout**: Sidebar navigation and layout structure at `/app/(admin)`.
+2.  **User Management**:
+    *   List Users (`GET /users`) with pagination/filtering.
+    *   Create/Edit User (`POST /users`, `PATCH /users/:id`).
+    *   Assign Roles (`POST /users/assign-role`).
+3.  **Organization Management**:
+    *   List Organizations (`GET /organizations`).
+    *   Create/Edit Organization (`POST`, `PATCH`).
+
+## Implementation Steps
+
+### 1. Admin Layout & Navigation
+- **File**: `app/(admin)/layout.tsx`
+- **File**: `components/admin/admin-sidebar.tsx`
+- **Logic**: Ensure only users with `ADMIN` role can access.
+
+### 2. User Management
+- **Page**: `app/(admin)/admin/users/page.tsx`
+- **Components**:
+    *   `components/admin/users/user-table.tsx` (using `tanstack/react-table`)
+    *   `components/admin/users/user-dialog.tsx` (Create/Edit Form with Zod validation)
+
+### 3. Organization Management
+- **Page**: `app/(admin)/admin/organizations/page.tsx`
+- **Components**:
+    *   `components/admin/orgs/org-table.tsx`
+    *   `components/admin/orgs/org-dialog.tsx`
+
+## Dependencies
+- Backend Endpoints: verified (`UserController`, `OrganizationController`).
+- UI Components: `Table`, `Dialog`, `Form` (Shadcn/UI - already installed).
+
+## Verification
+- [ ] Login as Admin.
+- [ ] Navigate to `/admin/users`.
+- [ ] Create a new user and verify in DB/List.
+- [ ] Edit user details.
+- [ ] Create a new Organization.