@flusys/nestjs-form-builder 1.1.0-beta → 2.0.0

package/README.md

@@ -0,0 +1,722 @@
+# Form Builder Package Guide
+
+> **Package:** `@flusys/nestjs-form-builder`
+> **Type:** Dynamic form management with schema versioning and access control
+
+This guide covers the NestJS form builder package - dynamic form creation, submission storage, and multi-tenant support.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Constants](#constants)
+- [Package Architecture](#package-architecture)
+- [Module Setup](#module-setup)
+- [Entities](#entities)
+- [DTOs](#dtos)
+- [Services](#services)
+- [Controllers](#controllers)
+- [Access Control](#access-control)
+- [Multi-Tenant Support](#multi-tenant-support)
+- [API Reference](#api-reference)
+- [Computed Fields](#computed-fields)
+- [Response Mode](#response-mode)
+- [Best Practices](#best-practices)
+
+---
+
+## Overview
+
+`@flusys/nestjs-form-builder` provides a comprehensive form management system:
+
+- **Dynamic Forms** - JSON schema-based form definitions
+- **Schema Versioning** - Auto-increment version on schema changes
+- **Result Snapshots** - Store schema at submission time for historical accuracy
+- **Access Control** - Public, authenticated, and permission-based access
+- **Multi-Tenant Support** - Optional company isolation
+- **POST-only RPC** - Follows project API conventions
+
+### Package Hierarchy
+
+```
+@flusys/nestjs-core     ← Foundation
+     ↓
+@flusys/nestjs-shared   ← Shared utilities
+     ↓
+@flusys/nestjs-form-builder  ← Form management (THIS PACKAGE)
+```
+
+---
+
+## Installation
+
+```bash
+npm install @flusys/nestjs-form-builder @flusys/nestjs-shared @flusys/nestjs-core
+```
+
+---
+
+## Constants
+
+```typescript
+// Injection Token
+export const FORM_BUILDER_MODULE_OPTIONS = 'FORM_BUILDER_MODULE_OPTIONS';
+```
+
+---
+
+## Package Architecture
+
+```
+nestjs-form-builder/
+├── src/
+│   ├── modules/
+│   │   └── form-builder.module.ts    # Main module
+│   │
+│   ├── config/
+│   │   ├── form-builder.constants.ts # Constants
+│   │   └── index.ts
+│   │
+│   ├── entities/
+│   │   ├── form.entity.ts            # Main form entity
+│   │   ├── form-with-company.entity.ts  # Extends Form with company
+│   │   ├── form-result.entity.ts     # Submissions
+│   │   └── index.ts
+│   │
+│   ├── dtos/
+│   │   ├── form.dto.ts               # Form DTOs
+│   │   ├── form-result.dto.ts        # Result DTOs
+│   │   └── index.ts
+│   │
+│   ├── services/
+│   │   ├── form-builder-config.service.ts  # Config service
+│   │   ├── form-builder-datasource.provider.ts
+│   │   ├── form.service.ts           # Form CRUD
+│   │   ├── form-result.service.ts    # Submission handling
+│   │   └── index.ts
+│   │
+│   ├── controllers/
+│   │   ├── form.controller.ts        # Form endpoints
+│   │   ├── form-result.controller.ts # Result endpoints
+│   │   └── index.ts
+│   │
+│   ├── enums/
+│   │   ├── form-access-type.enum.ts
+│   │   └── index.ts
+│   │
+│   ├── interfaces/
+│   │   ├── form.interface.ts
+│   │   ├── form-result.interface.ts
+│   │   ├── form-builder-module.interface.ts
+│   │   └── index.ts
+│   │
+│   ├── utils/
+│   │   ├── permission.utils.ts       # Permission validation
+│   │   ├── computed-field.utils.ts   # Computed field calculation
+│   │   └── index.ts
+│   │
+│   ├── docs/
+│   │   ├── form-builder-swagger.config.ts
+│   │   └── index.ts
+│   │
+│   └── index.ts                      # Public API
+```
+
+---
+
+## Module Setup
+
+### Basic Setup (Single Tenant)
+
+```typescript
+import { FormBuilderModule } from '@flusys/nestjs-form-builder';
+
+@Module({
+  imports: [
+    FormBuilderModule.forRoot({
+      global: true,
+      includeController: true,
+      bootstrapAppConfig: {
+        databaseMode: 'single',
+        enableCompanyFeature: false,
+      },
+      config: {
+        defaultDatabaseConfig: {
+          host: 'localhost',
+          port: 5432,
+          username: 'postgres',
+          password: 'password',
+          database: 'flusys',
+        },
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### With Company Feature
+
+```typescript
+FormBuilderModule.forRoot({
+  bootstrapAppConfig: {
+    databaseMode: 'single',
+    enableCompanyFeature: true,  // Enable company isolation
+  },
+  config: {
+    defaultDatabaseConfig: dbConfig,
+  },
+})
+```
+
+### Async Configuration
+
+```typescript
+FormBuilderModule.forRootAsync({
+  bootstrapAppConfig: {
+    databaseMode: 'single',
+    enableCompanyFeature: true,
+  },
+  useFactory: async (configService: ConfigService) => ({
+    defaultDatabaseConfig: configService.getDatabaseConfig(),
+  }),
+  inject: [ConfigService],
+})
+```
+
+### Migration Configuration
+
+Add form builder entities to your migration config:
+
+```typescript
+import { getFormBuilderEntitiesByConfig } from '@flusys/nestjs-form-builder/entities';
+
+function getEntitiesForTenant(tenantConfig?: ITenantDatabaseConfig): any[] {
+  const enableCompany = tenantConfig?.enableCompanyFeature ?? false;
+
+  // ... other entities
+  const formBuilderEntities = getFormBuilderEntitiesByConfig(enableCompany);
+
+  return [...otherEntities, ...formBuilderEntities];
+}
+```
+
+---
+
+## Entities
+
+### Entity Groups
+
+```typescript
+// Core entities (no company feature)
+export const FormCoreEntities = [Form, FormResult];
+
+// Company-specific entities
+export const FormCompanyEntities = [FormWithCompany, FormResult];
+
+// Helper function
+export function getFormBuilderEntitiesByConfig(enableCompanyFeature: boolean): any[] {
+  return enableCompanyFeature ? FormCompanyEntities : FormCoreEntities;
+}
+
+// Base type alias for backwards compatibility
+export { Form as FormBase } from './form.entity';
+```
+
+### Form
+
+Main form entity with all form fields:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `name` | `varchar(255)` | Form name |
+| `description` | `varchar(500)` | Optional description |
+| `slug` | `varchar(255)` | URL-friendly identifier (unique) |
+| `schema` | `json` | Form schema (sections, fields, settings) |
+| `schemaVersion` | `int` | Auto-incremented on schema changes |
+| `accessType` | `enum` | `public`, `authenticated`, `action_group` |
+| `actionGroups` | `simple-array` | Permission codes for action_group access |
+| `isActive` | `boolean` | Form availability |
+| `metadata` | `simple-json` | Additional data |
+
+### Form vs FormWithCompany
+
+- **Form** - Used when `enableCompanyFeature: false`
+- **FormWithCompany** - Extends Form, adds `companyId` column for tenant isolation
+
+### FormResult
+
+Stores form submissions:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `formId` | `uuid` | Reference to form |
+| `schemaVersionSnapshot` | `json` | Full schema copy at submission time |
+| `schemaVersion` | `int` | Schema version at submission |
+| `data` | `json` | Submitted field values |
+| `submittedById` | `uuid` | User who submitted (null for public) |
+| `submittedAt` | `timestamp` | Submission timestamp |
+| `isDraft` | `boolean` | Draft vs final submission |
+| `metadata` | `simple-json` | Additional data |
+
+**Note:** FormResult doesn't have `companyId` - company context is derived from the linked Form via `formId`.
+
+---
+
+## DTOs
+
+### Form DTOs
+
+| DTO | Purpose |
+|-----|---------|
+| `CreateFormDto` | Create new form |
+| `UpdateFormDto` | Update existing form |
+| `FormResponseDto` | Full form response |
+| `PublicFormResponseDto` | Limited fields for public access |
+| `FormAccessInfoResponseDto` | Access requirements info |
+
+### Form Result DTOs
+
+| DTO | Purpose |
+|-----|---------|
+| `SubmitFormDto` | Public submission input |
+| `CreateFormResultDto` | Internal with extra fields |
+| `UpdateFormResultDto` | Update result |
+| `GetMyDraftDto` | Get user's draft for a form |
+| `UpdateDraftDto` | Update existing draft |
+| `GetResultsByFormDto` | Query results by form ID |
+| `FormResultResponseDto` | Result response |
+
+---
+
+## Services
+
+### FormBuilderConfigService
+
+Provides access to module configuration:
+
+```typescript
+@Injectable()
+export class FormBuilderConfigService {
+  isCompanyFeatureEnabled(): boolean;
+  getDatabaseMode(): string;
+  isMultiTenant(): boolean;
+  getOptions(): FormBuilderModuleOptions;
+  getConfig();
+}
+```
+
+### FormService
+
+Extends `RequestScopedApiService` with form-specific operations:
+
+```typescript
+// Get form for public submission
+const form = await formService.getPublicForm(formId);
+
+// Get form for authenticated submission (validates access)
+const form = await formService.getAuthenticatedForm(formId, user);
+
+// Get form by slug
+const form = await formService.getBySlug('customer-feedback');
+
+// Get access info (for frontend routing)
+const info = await formService.getFormAccessInfo(formId);
+```
+
+**Schema Versioning:**
+- `schemaVersion` auto-increments when schema JSON changes
+- Comparison uses `JSON.stringify` for deep equality check
+
+### FormResultService
+
+Handles form submissions and drafts:
+
+```typescript
+// Submit form (validates access type)
+const result = await formResultService.submitForm(dto, user, isPublic);
+
+// Get results by form with pagination
+const { data, total } = await formResultService.getByFormId(formId, user, {
+  page: 0,
+  pageSize: 10,
+});
+
+// Draft management
+const draft = await formResultService.getMyDraft(formId, user);
+const updated = await formResultService.updateDraft(draftId, dto, user);
+const hasSubmitted = await formResultService.hasUserSubmitted(formId, user);
+```
+
+**Key behaviors:**
+- Schema snapshot stored with each submission for historical accuracy
+- Drafts auto-update if user re-submits as draft
+- Final submission deletes existing draft
+- Computed fields applied only on final submission (not drafts)
+
+---
+
+## Controllers
+
+### FormController
+
+Base path: `/form-builder/form`
+
+| Endpoint | Auth | Description |
+|----------|------|-------------|
+| `POST /insert` | JWT | Create form |
+| `POST /update` | JWT | Update form |
+| `POST /delete` | JWT | Delete form |
+| `POST /get-all` | JWT | List forms |
+| `POST /get/:id` | JWT | Get form by ID |
+| `POST /access-info/:id` | Public | Get access requirements |
+| `POST /public/:id` | Public | Get public form |
+| `POST /authenticated/:id` | JWT | Get authenticated form |
+| `POST /by-slug/:slug` | JWT | Get form by slug |
+| `POST /public/by-slug/:slug` | Public | Get public form by slug |
+
+### FormResultController
+
+Base path: `/form-builder/result`
+
+| Endpoint | Auth | Description |
+|----------|------|-------------|
+| `POST /insert` | JWT | Create result (internal) |
+| `POST /update` | JWT | Update result |
+| `POST /delete` | JWT | Delete result |
+| `POST /get-all` | JWT | List results |
+| `POST /get/:id` | JWT | Get result by ID |
+| `POST /submit` | JWT | Submit form (authenticated) |
+| `POST /submit-public` | Public | Submit form (public) |
+| `POST /my-draft` | JWT | Get user's draft for a form |
+| `POST /update-draft` | JWT | Update draft or convert to final |
+| `POST /by-form` | JWT | Get results by form ID |
+| `POST /has-submitted` | JWT | Check if user has submitted |
+
+---
+
+## Access Control
+
+### Access Types
+
+| Type | Description | Endpoint |
+|------|-------------|----------|
+| `public` | No authentication | `submit-public` |
+| `authenticated` | Login required | `submit` |
+| `action_group` | Specific permissions | `submit` + permission check |
+
+### Flow
+
+1. Frontend calls `access-info/:id` to determine requirements
+2. Based on `accessType`:
+   - `public` → Fetch via `public/:id`, submit via `submit-public`
+   - `authenticated` → Redirect to login if needed, use `authenticated/:id`, submit via `submit`
+   - `action_group` → Same as authenticated + permission check on submit
+
+### Permission Checking
+
+For `action_group` forms:
+- Form stores required permissions in `actionGroups` array
+- Service checks if user has ANY of the listed permissions
+- Uses cache-based permission lookup via `validateUserPermissions`
+
+```typescript
+import { validateUserPermissions } from '@flusys/nestjs-form-builder';
+
+// In FormService.getAuthenticatedForm()
+if (form.accessType === FormAccessType.ACTION_GROUP && form.actionGroups?.length) {
+  const hasPermission = await validateUserPermissions(
+    user,
+    form.actionGroups,
+    this.cacheManager,
+    this.formBuilderConfig.isCompanyFeatureEnabled(),
+    this.logger,
+    'accessing form',
+    form.id,
+  );
+  if (!hasPermission) {
+    throw new ForbiddenException('You do not have permission to access this form');
+  }
+}
+```
+
+---
+
+## Multi-Tenant Support
+
+### Configuration
+
+```typescript
+FormBuilderModule.forRoot({
+  bootstrapAppConfig: {
+    enableCompanyFeature: true,
+  },
+})
+```
+
+### Entity Selection
+
+The module automatically selects the correct entity:
+- `enableCompanyFeature: false` → `Form` + `FormResult`
+- `enableCompanyFeature: true` → `FormWithCompany` + `FormResult`
+
+### Company Filtering
+
+When company feature is enabled:
+- Forms are filtered by `user.companyId`
+- Results are filtered via JOIN to Form's `companyId`
+- New forms get `companyId` from user context or DTO
+
+### DataSource Provider
+
+`FormBuilderDataSourceProvider` extends `MultiTenantDataSourceService`:
+- Maintains separate static cache from other modules
+- Dynamically loads correct entities per tenant
+- Supports per-tenant feature flags
+
+---
+
+## API Reference
+
+### Module Options
+
+```typescript
+interface FormBuilderModuleOptions {
+  global?: boolean;              // Make module global
+  includeController?: boolean;   // Include REST controllers
+  bootstrapAppConfig?: {
+    databaseMode?: 'single' | 'multi-tenant';
+    enableCompanyFeature?: boolean;
+  };
+  config?: {
+    defaultDatabaseConfig?: IDatabaseConfig;
+  };
+}
+```
+
+### Interfaces
+
+```typescript
+interface IForm {
+  id: string;
+  name: string;
+  description: string | null;
+  slug: string | null;
+  schema: Record<string, unknown>;
+  schemaVersion: number;
+  accessType: FormAccessType;
+  actionGroups: string[] | null;
+  isActive: boolean;
+  companyId: string | null;
+  metadata: Record<string, unknown> | null;
+  createdAt: Date;
+  updatedAt: Date;
+  deletedAt: Date | null;
+  createdById: string | null;
+  updatedById: string | null;
+  deletedById: string | null;
+}
+
+interface IFormResult {
+  id: string;
+  formId: string;
+  schemaVersionSnapshot: Record<string, unknown>;
+  schemaVersion: number;
+  data: Record<string, unknown>;
+  submittedById: string | null;
+  submittedAt: Date;
+  isDraft: boolean;
+  metadata: Record<string, unknown> | null;
+  // ... audit fields
+}
+
+interface IPublicForm {
+  id: string;
+  name: string;
+  description: string | null;
+  schema: Record<string, unknown>;
+  schemaVersion: number;
+}
+```
+
+### Enums
+
+```typescript
+enum FormAccessType {
+  PUBLIC = 'public',
+  AUTHENTICATED = 'authenticated',
+  ACTION_GROUP = 'action_group',
+}
+```
+
+---
+
+## Computed Fields
+
+Computed fields are values automatically calculated from form responses when a form is submitted. The calculation happens server-side before storing the result.
+
+### How It Works
+
+1. Form schema contains `computedFields` in settings
+2. On final submission (not drafts), backend calculates values
+3. Computed values are stored in `data._computed` namespace
+4. Original field values remain unchanged
+
+### Utility Functions
+
+```typescript
+import { calculateComputedFields, IComputedField } from '@flusys/nestjs-form-builder';
+
+// Calculate computed fields from form data
+const computedValues = calculateComputedFields(formData, computedFields);
+// Result: { total_score: 15, category: 'premium' }
+```
+
+**Note:** Backend interface definitions mirror `@flusys/ng-form-builder` interfaces but are defined separately to avoid cross-package dependencies. Both use compatible JSON structures for serialization. See `computed-field.utils.ts` for implementation.
+
+### Supported Operations
+
+| Type | Description |
+|------|-------------|
+| `direct` | Set a static value |
+| `field_reference` | Copy value from another field |
+| `arithmetic` | Calculate using sum, subtract, multiply, divide, average, min, max |
+
+### Condition Operators
+
+Computed fields support conditional rules with these comparison operators:
+
+| Operator | Description |
+|----------|-------------|
+| `equals`, `not_equals` | Value equality |
+| `contains`, `not_contains` | String/array contains |
+| `greater_than`, `less_than` | Numeric comparison |
+| `greater_or_equal`, `less_or_equal` | Numeric comparison |
+| `is_empty`, `is_not_empty` | Null/empty check |
+| `is_before`, `is_after` | Date comparison |
+| `is_checked`, `is_not_checked` | Boolean/checkbox |
+| `is_any_of`, `is_none_of` | Array membership |
+
+### Data Storage
+
+Submission data includes computed values:
+
+```json
+{
+  "formId": "uuid",
+  "data": {
+    "name": "John",
+    "rating": 5,
+    "_computed": {
+      "total_score": 100,
+      "satisfaction_level": "high"
+    }
+  }
+}
+```
+
+### Integration in Service
+
+The `FormResultService` automatically calculates computed fields on submission via a private helper:
+
+```typescript
+// Private method in FormResultService
+private applyComputedFields(
+  data: Record<string, unknown>,
+  form: Form,
+  isDraft: boolean,
+): Record<string, unknown> {
+  if (isDraft) return data;
+
+  const schema = form.schema as Record<string, unknown>;
+  const settings = schema?.settings as Record<string, unknown> | undefined;
+  const computedFields = settings?.computedFields as IComputedField[] | undefined;
+
+  if (!computedFields || computedFields.length === 0) return data;
+
+  const computedValues = calculateComputedFields(data, computedFields);
+  return { ...data, _computed: computedValues };
+}
+
+// Used in submitForm() and updateDraft()
+const finalData = this.applyComputedFields(dto.data, form, isDraft);
+```
+
+---
+
+## Response Mode
+
+The form schema supports a `responseMode` setting that controls whether users can submit multiple responses.
+
+### Settings
+
+| Mode | Description |
+|------|-------------|
+| `multiple` | Default. Users can submit unlimited responses |
+| `single` | Each user can only submit once |
+
+### Tracking by Access Type
+
+| Access Type | Tracking Method | Reliability |
+|-------------|-----------------|-------------|
+| `authenticated` | Server-side via `submittedById` | Reliable |
+| `action_group` | Server-side via `submittedById` | Reliable |
+| `public` | Client-side (frontend handles) | Best-effort only |
+
+### Backend Endpoint
+
+For authenticated forms, the frontend calls `hasUserSubmitted` to check if the user has already submitted:
+
+```typescript
+// FormResultController - POST /form-builder/result/has-submitted
+@Post('has-submitted')
+@UseGuards(JwtAuthGuard)
+async hasUserSubmitted(
+  @Body() dto: GetMyDraftDto, // { formId: string }
+  @CurrentUser() user: ILoggedUserInfo,
+): Promise<boolean> {
+  return this.formResultService.hasUserSubmitted(dto.formId, user);
+}
+```
+
+**Note:** Public forms cannot be reliably tracked server-side since there's no user identity. The frontend uses `localStorage` as a best-effort solution, but this can be bypassed. For strict single-response enforcement, use `authenticated` or `action_group` access type.
+
+---
+
+## Best Practices
+
+### Schema Design
+
+- Store complete form schema including sections, fields, and settings
+- Use schema versioning to track changes
+- Store schema snapshots with results for historical accuracy
+
+### Access Control
+
+- Use `public` sparingly - only for truly anonymous forms
+- Prefer `authenticated` for most internal forms
+- Use `action_group` for sensitive forms requiring specific permissions
+
+### Company Isolation
+
+- Always set `companyId` when company feature is enabled
+- Use user's company context as default
+- Allow explicit `companyId` in DTO for admin operations
+
+### Performance
+
+- Use pagination when fetching results
+- Select only needed fields in queries
+- Consider caching frequently accessed forms
+
+---
+
+## See Also
+
+- [ng-form-builder Guide](../../FLUSYS_NG/docs/FORM-BUILDER-GUIDE.md) - Frontend components
+- [Shared Guide](SHARED-GUIDE.md) - Base classes and utilities
+- [Auth Guide](AUTH-GUIDE.md) - User and company management
+
+---
+
+**Last Updated:** 2026-02-21