@flusys/nestjs-form-builder 4.0.1 → 4.1.0

package/README.md

@@ -1,138 +1,85 @@
-# Form Builder Package Guide
+# @flusys/nestjs-form-builder
 
-> **Package:** `@flusys/nestjs-form-builder`
-> **Version:** 4.0.1
-> **Type:** Dynamic form management with schema versioning and access control
+> Dynamic form management for NestJS — JSON schema definitions, schema versioning, access control (PUBLIC/AUTHENTICATED/ACTION_GROUP), draft submissions, and a server-side computed fields engine.
 
-This guide covers the NestJS form builder package - dynamic form creation, submission storage, and multi-tenant support.
+[![npm version](https://img.shields.io/npm/v/@flusys/nestjs-form-builder.svg)](https://www.npmjs.com/package/@flusys/nestjs-form-builder)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![NestJS](https://img.shields.io/badge/NestJS-11.x-red.svg)](https://nestjs.com/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.x-green.svg)](https://nodejs.org/)
+
+---
 
 ## Table of Contents
 
 - [Overview](#overview)
+- [Features](#features)
+- [Compatibility](#compatibility)
 - [Installation](#installation)
-- [Constants](#constants)
-- [Package Architecture](#package-architecture)
-- [Module Setup](#module-setup)
+- [Quick Start](#quick-start)
+- [Module Registration](#module-registration)
+  - [forRoot (Sync)](#forroot-sync)
+  - [forRootAsync (Factory)](#forrootasync-factory)
+- [Configuration Reference](#configuration-reference)
+- [Feature Toggles](#feature-toggles)
+- [API Endpoints](#api-endpoints)
 - [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)
-- [Swagger Configuration](#swagger-configuration)
-- [Permission Utilities](#permission-utilities)
-- [Controller Security](#controller-security)
+- [Schema Versioning](#schema-versioning)
+- [Draft Support](#draft-support)
+- [Computed Fields Engine](#computed-fields-engine)
+- [Exported Services](#exported-services)
+- [Programmatic Usage](#programmatic-usage)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
 
 ---
 
 ## 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)
-```
+`@flusys/nestjs-form-builder` provides a complete dynamic form system where form structures are stored as JSON in the database. New forms can be created without any code changes. The module handles schema versioning (submissions snapshot the schema they were submitted against), per-form access control, draft submissions, and server-side computed field evaluation.
 
 ---
 
-## Installation
+## Features
 
-```bash
-npm install @flusys/nestjs-form-builder @flusys/nestjs-shared @flusys/nestjs-core
-```
+- **Database-driven forms** — JSON schema stored in PostgreSQL; no code changes for new forms
+- **Schema versioning** — Schema version auto-increments on change; each submission captures the version it used
+- **Access types** — `PUBLIC` (no auth), `AUTHENTICATED` (any logged-in user), `ACTION_GROUP` (IAM permission-based)
+- **Draft submissions** — Users can save partial form data and finalize later
+- **Computed fields engine** — Server-side arithmetic computed from submission data using rules and conditions
+- **Slug-based lookup** — Forms accessible by a URL-friendly slug
+- **Company scoping** — Optional `companyId` isolation via `FormWithCompany` entity
+- **Multi-tenant** — Per-tenant DataSource isolation
 
 ---
 
-## Constants
+## Compatibility
 
-```typescript
-// Injection Token
-export const FORM_BUILDER_MODULE_OPTIONS = 'FORM_BUILDER_MODULE_OPTIONS';
-```
+| Package | Version |
+|---------|---------|
+| `@flusys/nestjs-core` | `^4.0.0` |
+| `@flusys/nestjs-shared` | `^4.0.0` |
+| `@nestjs/core` | `^11.0.0` |
+| `typeorm` | `^0.3.0` |
+| Node.js | `>= 18.x` |
 
 ---
 
-## Package Architecture
+## Installation
 
-```
-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
+```bash
+npm install @flusys/nestjs-form-builder @flusys/nestjs-shared @flusys/nestjs-core
 ```
 
 ---
 
-## Module Setup
+## Quick Start
 
-### Basic Setup (Single Tenant)
+### Minimal Setup (Single Database)
 
 ```typescript
+import { Module } from '@nestjs/common';
 import { FormBuilderModule } from '@flusys/nestjs-form-builder';
 
 @Module({
@@ -146,11 +93,12 @@ import { FormBuilderModule } from '@flusys/nestjs-form-builder';
       },
       config: {
         defaultDatabaseConfig: {
-          host: 'localhost',
-          port: 5432,
-          username: 'postgres',
-          password: 'password',
-          database: 'flusys',
+          type: 'postgres',
+          host: process.env.DB_HOST,
+          port: Number(process.env.DB_PORT ?? 5432),
+          username: process.env.DB_USER,
+          password: process.env.DB_PASSWORD,
+          database: process.env.DB_NAME,
         },
       },
     }),
@@ -159,906 +107,344 @@ import { FormBuilderModule } from '@flusys/nestjs-form-builder';
 export class AppModule {}
 ```
 
-### With Company Feature
+After startup, create forms via `POST /form-builder/form/insert` and collect submissions via `POST /form-builder/result/insert`.
+
+---
+
+## Module Registration
+
+### forRoot (Sync)
 
 ```typescript
 FormBuilderModule.forRoot({
-  bootstrapAppConfig: {
-    databaseMode: 'single',
-    enableCompanyFeature: true,  // Enable company isolation
-  },
-  config: {
-    defaultDatabaseConfig: dbConfig,
-  },
+  global?: boolean;
+  includeController?: boolean;       // Default: true
+  bootstrapAppConfig?: {
+    databaseMode: 'single' | 'multi-tenant';
+    enableCompanyFeature: boolean;   // true = FormWithCompany entity
+  };
+  config?: IFormBuilderConfig;
 })
 ```
 
-### Async Configuration
+### forRootAsync (Factory)
 
 ```typescript
+import { ConfigService } from '@nestjs/config';
+
 FormBuilderModule.forRootAsync({
+  global: true,
+  includeController: true,
   bootstrapAppConfig: {
     databaseMode: 'single',
     enableCompanyFeature: true,
   },
-  useFactory: async (configService: ConfigService) => ({
-    defaultDatabaseConfig: configService.getDatabaseConfig(),
+  imports: [ConfigModule],
+  useFactory: (configService: ConfigService) => ({
+    defaultDatabaseConfig: {
+      type: 'postgres',
+      host: configService.get('DB_HOST'),
+      port: configService.get<number>('DB_PORT'),
+      username: configService.get('DB_USER'),
+      password: configService.get('DB_PASSWORD'),
+      database: configService.get('DB_NAME'),
+    },
   }),
   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 | Default | Description |
-|--------|------|---------|-------------|
-| `name` | `varchar(255)` | required | Form name |
-| `description` | `varchar(500)` | null | Optional description |
-| `slug` | `varchar(255)` | null | URL-friendly identifier |
-| `schema` | `json` | required | Form schema (sections, fields, settings) |
-| `schemaVersion` | `int` | 1 | Auto-incremented on schema changes |
-| `accessType` | `varchar(50)` | 'AUTHENTICATED' | `public`, `authenticated`, `action_group` |
-| `actionGroups` | `simple-array` | null | Permission codes for action_group access |
-| `isActive` | `boolean` | true | Form availability |
-| `metadata` | `simple-json` | null | Additional data |
-
-**Indexes (Form):**
-- `slug` - Unique index
-- `isActive` - Index for filtering active forms
-
-### Form vs FormWithCompany
-
-- **Form** - Used when `enableCompanyFeature: false`
-- **FormWithCompany** - Extends Form, adds `companyId` column for tenant isolation
-
-**FormWithCompany Additional Column:**
-
-| Column | Type | Description |
-|--------|------|-------------|
-| `companyId` | `uuid` | Company ID for tenant isolation |
-
-**FormWithCompany Indexes:**
-- `companyId` - Index for company filtering
-- `companyId, slug` - Unique compound index (slugs unique per company)
-- `companyId, isActive` - Compound index for active forms per company
-
-### FormResult
-
-Stores form submissions:
-
-| Column | Type | Default | Description |
-|--------|------|---------|-------------|
-| `formId` | `uuid` | required | Reference to form |
-| `schemaVersionSnapshot` | `json` | required | Full schema copy at submission time |
-| `schemaVersion` | `int` | required | Schema version at submission |
-| `data` | `json` | required | Submitted field values |
-| `submittedById` | `uuid` | null | User who submitted (null for public) |
-| `submittedAt` | `timestamp` | required | Submission timestamp |
-| `isDraft` | `boolean` | false | Draft vs final submission |
-| `metadata` | `simple-json` | null | Additional data |
-
-**Indexes:**
-- `formId` - Index for filtering by form
-
-**Note:** FormResult doesn't have `companyId` - company context is derived from the linked Form via `formId`. Company filtering is applied via JOIN in queries.
+**Exported services** (available for injection after registration):
+- `FormBuilderConfigService`
+- `FormBuilderDataSourceProvider`
+- `FormService`
+- `FormResultService`
 
 ---
 
-## 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 |
-
-#### CreateFormDto Fields
-
-```typescript
-class CreateFormDto {
-  name: string;                    // Required, max 255 chars
-  description?: string;            // Optional, max 500 chars
-  slug?: string;                   // Optional, max 255 chars (unique)
-  schema: Record<string, unknown>; // Required - form structure
-  accessType?: FormAccessType;     // Default: AUTHENTICATED
-  actionGroups?: string[];         // For ACTION_GROUP access type
-  companyId?: string;              // When company feature enabled
-  isActive?: boolean;              // Default: true
-  metadata?: Record<string, unknown>;
-}
-```
-
-#### UpdateFormDto Fields
-
-```typescript
-class UpdateFormDto extends PartialType(CreateFormDto) {
-  id: string;                      // Required
-  schemaVersion?: number;          // Auto-incremented on schema change
-}
-```
-
-### 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 |
-
-#### SubmitFormDto Fields
+## Configuration Reference
 
 ```typescript
-class SubmitFormDto {
-  formId: string;                  // Required
-  data: Record<string, unknown>;   // Required - field values
-  isDraft?: boolean;               // Default: false
-  metadata?: Record<string, unknown>;
+interface IFormBuilderConfig extends IDataSourceServiceOptions {
+  // No form-builder-specific runtime config.
+  // IDataSourceServiceOptions provides:
+  //   defaultDatabaseConfig?: IDatabaseConfig
+  //   tenantDefaultDatabaseConfig?: IDatabaseConfig
+  //   tenants?: ITenantDatabaseConfig[]
 }
 ```
 
-#### GetResultsByFormDto Fields
+Bootstrap configuration:
 
-```typescript
-class GetResultsByFormDto {
-  formId: string;                  // Required
-  page?: number;                   // Default: 0
-  pageSize?: number;               // Default: 10
-}
-```
+| Field | Type | Default | Effect |
+|-------|------|---------|--------|
+| `databaseMode` | `'single' \| 'multi-tenant'` | `'single'` | Controls DataSource resolution per request |
+| `enableCompanyFeature` | `boolean` | `false` | Uses `FormWithCompany` entity when `true` |
 
 ---
 
-## Services
-
-### FormBuilderConfigService
-
-Provides access to module configuration:
+## Feature Toggles
 
-```typescript
-@Injectable()
-export class FormBuilderConfigService implements IModuleConfigService {
-  // Check if company feature is enabled (supports per-tenant override)
-  isCompanyFeatureEnabled(tenant?: ITenantDatabaseConfig): boolean;
-
-  // Get database mode ('single' | 'multi-tenant')
-  getDatabaseMode(): DatabaseMode;
-
-  // Check if running in multi-tenant mode
-  isMultiTenant(): boolean;
-
-  // Get full module options
-  getOptions(): FormBuilderModuleOptions;
-
-  // Get config section (defaultDatabaseConfig, tenants, etc.)
-  getConfig(): IFormBuilderConfig | undefined;
-}
-```
-
-### FormService
-
-Extends `RequestScopedApiService` with form-specific operations:
-
-```typescript
-@Injectable({ scope: Scope.REQUEST })
-export class FormService extends RequestScopedApiService<...> {
-  // === Standard CRUD (inherited) ===
-  // insert(dto, user), update(dto, user), delete(id, user), getAll(filter, user), getById(id, user)
-
-  // === Public Access (no auth required) ===
-
-  // Get form for public submission (accessType must be PUBLIC)
-  async getPublicForm(formId: string): Promise<IPublicForm>;
-
-  // Get public form by slug (no auth required)
-  async getPublicFormBySlug(slug: string): Promise<IPublicForm | null>;
-
-  // Get access info for routing decisions
-  async getFormAccessInfo(formId: string): Promise<FormAccessInfoResponseDto>;
-
-  // === Authenticated Access ===
-
-  // Get form for authenticated submission (validates access + permissions)
-  async getAuthenticatedForm(formId: string, user: ILoggedUserInfo): Promise<IPublicForm>;
-
-  // Get form by slug (requires auth)
-  async getBySlug(slug: string): Promise<IForm | null>;
-
-  // Get form for submission (internal - validates access type)
-  async getFormForSubmission(formId: string, user: ILoggedUserInfo | null): Promise<Form>;
-}
-```
-
-**Schema Versioning:**
-- `schemaVersion` auto-increments when schema JSON changes
-- Comparison uses `JSON.stringify` for deep equality check
-- Version tracked in FormResult snapshots for historical accuracy
-
-### FormResultService
-
-Handles form submissions and drafts:
-
-```typescript
-@Injectable({ scope: Scope.REQUEST })
-export class FormResultService extends RequestScopedApiService<...> {
-  // === Standard CRUD (inherited) ===
-  // insert(dto, user), update(dto, user), delete(id, user), getAll(filter, user), getById(id, user)
-
-  // === Form Submission ===
-
-  // Submit form (validates access type, handles drafts)
-  async submitForm(
-    dto: SubmitFormDto,
-    user: ILoggedUserInfo | null,
-    isPublic?: boolean,  // default: false
-  ): Promise<IFormResult>;
-
-  // === Draft Management ===
-
-  // Get user's draft for a specific form
-  async getMyDraft(formId: string, user: ILoggedUserInfo): Promise<IFormResult | null>;
-
-  // Update existing draft (can convert to final submission)
-  async updateDraft(
-    draftId: string,
-    dto: SubmitFormDto,
-    user: ILoggedUserInfo,
-  ): Promise<IFormResult>;
-
-  // === Query Methods ===
-
-  // Get results by form ID with pagination
-  async getByFormId(
-    formId: string,
-    user: ILoggedUserInfo | null,
-    pagination?: { page?: number; pageSize?: number },
-  ): Promise<{ data: IFormResult[]; total: number }>;
-
-  // Check if user has submitted (non-draft) for single response mode
-  async hasUserSubmitted(formId: string, user: ILoggedUserInfo): Promise<boolean>;
-}
-```
-
-**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 (soft delete)
-- Computed fields applied only on final submission (not drafts)
-- Company filtering via JOIN when company feature enabled
-
-### FormBuilderDataSourceProvider
-
-Extends `MultiTenantDataSourceService` for dynamic entity loading:
-
-```typescript
-@Injectable({ scope: Scope.REQUEST })
-export class FormBuilderDataSourceProvider extends MultiTenantDataSourceService {
-  // Maintains separate static cache from other modules
-  protected static readonly tenantConnections = new Map<string, DataSource>();
-  protected static singleDataSource: DataSource | null = null;
-
-  // Get entities based on company feature flag
-  async getFormBuilderEntities(enableCompanyFeature?: boolean): Promise<any[]>;
-
-  // Inherited from MultiTenantDataSourceService
-  async getDataSource(): Promise<DataSource>;
-  async getRepository<T>(entity: EntityTarget<T>): Promise<Repository<T>>;
-}
-```
+| Feature | Config | Default | Effect |
+|---------|--------|---------|--------|
+| Company scoping | `enableCompanyFeature: true` | `false` | All queries filtered by `companyId` from JWT; uses `FormWithCompany` entity |
+| Multi-tenant | `databaseMode: 'multi-tenant'` | `'single'` | Per-tenant DataSource connections |
 
 ---
 
-## Controllers
+## API Endpoints
 
-### FormController
+All endpoints use **POST**. Authentication depends on the form's `accessType`.
 
-Base path: `/form-builder/form`
+### Forms — `POST /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 |
+| `POST /form-builder/form/insert` | `form.create` | Create a new form with JSON schema |
+| `POST /form-builder/form/get-all` | `form.read` | List all forms (admin) |
+| `POST /form-builder/form/get/:id` | `form.read` | Get form by ID |
+| `POST /form-builder/form/get-by-slug/:slug` | Varies* | Get form by URL slug |
+| `POST /form-builder/form/update` | `form.update` | Update form (increments schema version if schema changes) |
+| `POST /form-builder/form/delete` | `form.delete` | Delete form |
+| `POST /form-builder/form/publish` | `form.update` | Publish draft form |
+| `POST /form-builder/form/unpublish` | `form.update` | Unpublish form |
 
-### FormResultController
+*`get-by-slug` respects the form's `accessType` — PUBLIC forms are accessible without auth.
 
-Base path: `/form-builder/result`
+### Form Results (Submissions) — `POST /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 |
+| `POST /form-builder/result/insert` | Varies* | Submit a form result |
+| `POST /form-builder/result/get-all` | `form-result.read` | List all submissions |
+| `POST /form-builder/result/get/:id` | `form-result.read` | Get submission by ID |
+| `POST /form-builder/result/update` | `form-result.update` | Update a submission |
+| `POST /form-builder/result/delete` | `form-result.delete` | Delete a submission |
+| `POST /form-builder/result/save-draft` | Varies* | Save a partial draft submission |
+| `POST /form-builder/result/finalize` | Varies* | Convert draft to final submission |
+| `POST /form-builder/result/get-my-results` | JWT | Get current user's own submissions |
 
----
-
-## Access Control
+*Depends on the form's `accessType`.
 
-### Access Types
+---
 
-| Type | Description | Endpoint |
-|------|-------------|----------|
-| `public` | No authentication | `submit-public` |
-| `authenticated` | Login required | `submit` |
-| `action_group` | Specific permissions | `submit` + permission check |
+## Entities
 
-### Flow
+### Core Entities (always registered)
 
-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
+| Entity | Table | Description |
+|--------|-------|-------------|
+| `Form` | `form_builder_form` | Form definition with JSON schema, access type, version |
+| `FormResult` | `form_builder_result` | Submission data + schema version snapshot |
 
-### Permission Checking
+### Company Feature Entities (`enableCompanyFeature: true`)
 
-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`
+| Entity | Table | Description |
+|--------|-------|-------------|
+| `FormWithCompany` | `form_builder_form` | Same as Form + `companyId` |
 
 ```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
+import { FormBuilderModule } from '@flusys/nestjs-form-builder';
 
-```typescript
-FormBuilderModule.forRoot({
-  bootstrapAppConfig: {
-    enableCompanyFeature: true,
-  },
+TypeOrmModule.forRoot({
+  entities: [
+    ...FormBuilderModule.getEntities({ 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 extends IDynamicModuleConfig {
-  global?: boolean;                          // Make module global
-  includeController?: boolean;               // Include REST controllers
-  bootstrapAppConfig?: IBootstrapAppConfig;  // Bootstrap configuration
-  config?: IFormBuilderConfig;               // Form builder configuration
-}
-
-interface IFormBuilderConfig extends IDataSourceServiceOptions {
-  // Currently no form-builder specific runtime config
-  // Add form-builder specific settings here as needed
-  defaultDatabaseConfig?: IDatabaseConfig;
-  tenantDefaultDatabaseConfig?: IDatabaseConfig;
-  tenants?: ITenantDatabaseConfig[];
-}
-```
-
-### Async Options
-
-```typescript
-interface FormBuilderModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
-  global?: boolean;
-  includeController?: boolean;
-  bootstrapAppConfig?: IBootstrapAppConfig;
-  useFactory?: (...args: any[]) => Promise<IFormBuilderConfig> | IFormBuilderConfig;
-  inject?: any[];
-  useExisting?: Type<FormBuilderOptionsFactory>;
-  useClass?: Type<FormBuilderOptionsFactory>;
-}
+## Access Control
 
-interface FormBuilderOptionsFactory {
-  createFormBuilderOptions(): Promise<IFormBuilderConfig> | IFormBuilderConfig;
-}
-```
+Each form has an `accessType` field that controls who can access it:
 
-### Interfaces
+| Access Type | Description |
+|-------------|-------------|
+| `PUBLIC` | No authentication required. Anyone can view and submit. |
+| `AUTHENTICATED` | Requires valid JWT token. Any logged-in user can submit. |
+| `ACTION_GROUP` | Requires a specific IAM action permission (from `nestjs-iam`). |
 
-```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
-}
+**Creating a form with access control:**
 
-interface IPublicForm {
-  id: string;
-  name: string;
-  description: string | null;
-  schema: Record<string, unknown>;
-  schemaVersion: number;
+```json
+POST /form-builder/form/insert
+{
+  "name": "Employee Survey",
+  "slug": "employee-survey",
+  "accessType": "AUTHENTICATED",
+  "schema": { /* JSON schema */ },
+  "isPublished": true
 }
 ```
 
-### Enums
+**ACTION_GROUP form:**
 
-```typescript
-enum FormAccessType {
-  PUBLIC = 'public',
-  AUTHENTICATED = 'authenticated',
-  ACTION_GROUP = 'action_group',
+```json
+{
+  "name": "Finance Report",
+  "slug": "finance-report",
+  "accessType": "ACTION_GROUP",
+  "requiredAction": "finance.submit-report",
+  "schema": { /* JSON schema */ }
 }
 ```
 
 ---
 
-## 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
+## Schema Versioning
 
-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
+When you update a form's `schema` field, the `schemaVersion` counter is automatically incremented. Every form submission stores the `schemaVersion` at the time of submission.
 
-### Utility Functions
+This allows:
+- Viewing historical submissions against the exact schema that was active
+- Running analytics on form data across schema versions
+- Preventing schema changes from breaking existing submission records
 
-```typescript
-import { calculateComputedFields, IComputedField } from '@flusys/nestjs-form-builder';
+```json
+// Version 1 schema
+{ "fields": [{ "name": "firstName", "type": "text" }] }
 
-// Calculate computed fields from form data
-const computedValues = calculateComputedFields(formData, computedFields);
-// Result: { total_score: 15, category: 'premium' }
+// After update (version 2) - new field added
+{ "fields": [{ "name": "firstName", "type": "text" }, { "name": "lastName", "type": "text" }] }
 ```
 
-**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.
+Historical submissions still reference `schemaVersion: 1` so you know they were submitted before the `lastName` field existed.
 
-### Computed Field Interfaces
-
-```typescript
-interface IComputedField {
-  id: string;
-  name: string;
-  key: string;                              // Storage key in _computed
-  valueType: 'string' | 'number';
-  rules: IComputedRule[];
-  defaultValue?: string | number | null;
-  description?: string;
-}
+---
 
-interface IComputedRule {
-  id: string;
-  condition?: IComputedConditionGroup;      // Optional - no condition = always apply
-  computation: IComputation;
-}
+## Draft Support
 
-interface IComputedConditionGroup {
-  operator: 'AND' | 'OR';
-  conditions: IComputedCondition[];
-}
+Users can save partial form data as a draft and finalize later:
 
-interface IComputedCondition {
-  fieldId: string;
-  comparison: string;                       // See Condition Operators below
-  value: unknown;
+```json
+// Save draft (no validation on all required fields)
+POST /form-builder/result/save-draft
+{
+  "formId": "uuid",
+  "data": { "firstName": "John" }
 }
 
-interface IComputation {
-  type: ComputationType;
-  config: IDirectValueConfig | IFieldReferenceConfig | IArithmeticConfig;
+// Finalize (validates all required fields)
+POST /form-builder/result/finalize
+{
+  "draftId": "uuid",
+  "data": { "firstName": "John", "lastName": "Doe" }
 }
-
-type ComputationType = 'direct' | 'field_reference' | 'arithmetic';
 ```
 
-### Computation Config Types
+Draft submissions have `isDraft: true`. Finalized submissions have `isDraft: false`. Users can retrieve their own drafts via `POST /form-builder/result/get-my-results`.
 
-```typescript
-// Direct value - set a static value
-interface IDirectValueConfig {
-  type: 'direct';
-  value: string | number;
-}
-
-// Field reference - copy value from another field
-interface IFieldReferenceConfig {
-  type: 'field_reference';
-  fieldId: string;
-}
-
-// Arithmetic - calculate from multiple operands
-interface IArithmeticConfig {
-  type: 'arithmetic';
-  operation: ArithmeticOperation;
-  operands: IArithmeticOperand[];
-}
+---
 
-interface IArithmeticOperand {
-  type: 'field' | 'constant';
-  fieldId?: string;       // When type = 'field'
-  value?: number;         // When type = 'constant'
-}
-```
+## Computed Fields Engine
 
-### Supported Operations
-
-| Type | Description |
-|------|-------------|
-| `direct` | Set a static value |
-| `field_reference` | Copy value from another field |
-| `arithmetic` | Calculate using arithmetic operations |
-
-### Arithmetic Operations
-
-| Operation | Description |
-|-----------|-------------|
-| `sum` | Add all operand values |
-| `subtract` | Subtract subsequent values from first |
-| `multiply` | Multiply all operand values |
-| `divide` | Divide first value by subsequent values |
-| `average` | Calculate average of all operands |
-| `min` | Get minimum value |
-| `max` | Get maximum value |
-| `increment` | Alias for sum |
-| `decrement` | Alias for subtract |
-
-### Condition Operators
-
-Computed fields support conditional rules with these comparison operators:
-
-| Operator | Aliases | Description |
-|----------|---------|-------------|
-| `equals` | | Value equality (string-safe) |
-| `not_equals` | | Value inequality |
-| `contains` | | String contains substring |
-| `not_contains` | | String does not contain substring |
-| `starts_with` | | String starts with value |
-| `ends_with` | | String ends with value |
-| `greater_than` | | Numeric greater than |
-| `less_than` | | Numeric less than |
-| `greater_or_equal` | | Numeric greater or equal |
-| `less_or_equal` | | Numeric less or equal |
-| `is_empty` | | Null, undefined, empty string, or empty array |
-| `is_not_empty` | | Has a non-empty value |
-| `is_before` | | Date comparison (before) |
-| `is_after` | | Date comparison (after) |
-| `is_checked` | | Boolean true (or 'true', or 1) |
-| `is_not_checked` | | Boolean false (or 'false', 0, falsy) |
-| `is_any_of` | `in` | Value is in array |
-| `is_none_of` | `not_in` | Value is not in array |
-
-### Data Storage
-
-Submission data includes computed values:
+Server-side computed fields are calculated from submission data using declarative rules:
 
 ```json
+POST /form-builder/form/insert
 {
-  "formId": "uuid",
-  "data": {
-    "name": "John",
-    "rating": 5,
-    "_computed": {
-      "total_score": 100,
-      "satisfaction_level": "high"
-    }
+  "name": "Loan Calculator",
+  "schema": {
+    "fields": [
+      { "name": "principal", "type": "number", "label": "Loan Amount" },
+      { "name": "rate", "type": "number", "label": "Interest Rate (%)" },
+      { "name": "years", "type": "number", "label": "Term (Years)" }
+    ],
+    "computedFields": [
+      {
+        "name": "monthlyPayment",
+        "label": "Monthly Payment",
+        "expression": "(principal * (rate / 1200)) / (1 - Math.pow(1 + rate / 1200, -years * 12))",
+        "dependsOn": ["principal", "rate", "years"]
+      },
+      {
+        "name": "totalPayment",
+        "label": "Total Payment",
+        "expression": "monthlyPayment * years * 12",
+        "dependsOn": ["monthlyPayment", "years"]
+      }
+    ]
   }
 }
 ```
 
-### 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);
-```
+Computed values are evaluated server-side at submission time and stored with the result.
 
 ---
 
-## Response Mode
+## Exported Services
 
-The form schema supports a `responseMode` setting that controls whether users can submit multiple responses.
+| Service | Description |
+|---------|-------------|
+| `FormService` | Form CRUD, slug lookup, publish/unpublish |
+| `FormResultService` | Submission CRUD, draft management, computed field evaluation |
+| `FormBuilderConfigService` | Exposes runtime config and feature flags |
+| `FormBuilderDataSourceProvider` | Dynamic DataSource resolution per request |
 
-### Settings
-
-| Mode | Description |
-|------|-------------|
-| `multiple` | Default. Users can submit unlimited responses |
-| `single` | Each user can only submit once |
+---
 
-### Tracking by Access Type
+## Programmatic Usage
 
-| 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 |
+```typescript
+import { FormService, FormResultService } from '@flusys/nestjs-form-builder';
 
-### Backend Endpoint
+@Injectable()
+export class SurveyService {
+  constructor(
+    @Inject(FormService) private readonly formService: FormService,
+    @Inject(FormResultService) private readonly resultService: FormResultService,
+  ) {}
+
+  async getPublicForm(slug: string) {
+    return this.formService.getBySlug(slug);
+  }
 
-For authenticated forms, the frontend calls `hasUserSubmitted` to check if the user has already submitted:
+  async submitForm(formId: string, data: Record<string, any>, userId: string) {
+    return this.resultService.submit({ formId, data, userId });
+  }
 
-```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);
+  async getFormResults(formId: string) {
+    return this.resultService.getAll({ filter: { formId } }, null);
+  }
 }
 ```
 
-**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
+## Troubleshooting
 
-### Performance
+**`Form not found` for a public form**
 
-- Use pagination when fetching results
-- Select only needed fields in queries
-- Consider caching frequently accessed forms
+Check that the form is published (`isPublished: true`). Unpublished forms are not returned by the public API.
 
 ---
 
-## Swagger Configuration
-
-The package includes a Swagger configuration helper that adapts documentation based on feature flags:
-
-```typescript
-import { formBuilderSwaggerConfig } from '@flusys/nestjs-form-builder';
-import { setupSwaggerDocs } from '@flusys/nestjs-core/docs';
-
-// In bootstrap
-const bootstrapConfig = { enableCompanyFeature: true };
-setupSwaggerDocs(app, formBuilderSwaggerConfig(bootstrapConfig));
-```
-
-**Features:**
-- Automatically excludes `companyId` fields when company feature is disabled
-- Generates comprehensive API documentation
-- Documents all access types and workflows
-
-### Schema Exclusions
+**Draft finalization fails validation**
 
-When `enableCompanyFeature: false`, these schemas hide `companyId`:
-- `CreateFormDto`
-- `UpdateFormDto`
-- `FormQueryDto`
-- `FormResponseDto`
+The `finalize` endpoint applies full schema validation. Ensure all required fields in the form schema are present in the submitted data.
 
 ---
 
-## Permission Utilities
+**Computed fields not appearing in submission**
 
-The package provides permission validation utilities for action group access:
+Computed fields are evaluated at submission time. Check that `dependsOn` field names exactly match the form field `name` values (case-sensitive).
 
-```typescript
-import { validateUserPermissions } from '@flusys/nestjs-form-builder';
-
-// Validate user has at least one of the required permissions
-const hasPermission = await validateUserPermissions(
-  user,                           // ILoggedUserInfo
-  ['hr.survey.submit', 'admin'],  // Required permissions (OR logic)
-  cacheManager,                   // HybridCache instance
-  enableCompanyFeature,           // boolean
-  logger,                         // Logger instance
-  'submitting form',              // Context for audit logging
-  formId,                         // Resource ID for audit logging
-);
-```
-
-**Features:**
-- Reads permissions from cache (same format as PermissionGuard)
-- Fail-closed behavior: cache errors result in access denial
-- Audit logging for permission denials
+---
 
-### Permission Cache Key Format
+**`No metadata for entity`**
 
+Register entities in your `TypeOrmModule`:
 ```typescript
-// With company feature enabled
-`permissions:company:${companyId}:branch:${branchId}:user:${userId}`
-
-// Without company feature
-`permissions:user:${userId}`
+entities: [...FormBuilderModule.getEntities({ enableCompanyFeature: false })]
 ```
 
 ---
 
-## Controller Security
-
-Both controllers use `createApiController` with permission-based security:
-
-### Form Permissions
-
-| Operation | Permission |
-|-----------|------------|
-| Create | `FORM_PERMISSIONS.CREATE` |
-| Read | `FORM_PERMISSIONS.READ` |
-| Update | `FORM_PERMISSIONS.UPDATE` |
-| Delete | `FORM_PERMISSIONS.DELETE` |
-
-### Form Result Permissions
-
-| Operation | Permission |
-|-----------|------------|
-| Create | `FORM_RESULT_PERMISSIONS.CREATE` |
-| Read | `FORM_RESULT_PERMISSIONS.READ` |
-| Update | `FORM_RESULT_PERMISSIONS.UPDATE` |
-| Delete | `FORM_RESULT_PERMISSIONS.DELETE` |
-
-**Note:** Submit endpoints (`submit`, `submit-public`) don't require these permissions - they use the form's `accessType` for authorization.
-
----
-
-## See Also
+## License
 
-- [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
+MIT © FLUSYS
 
 ---
 
-**Last Updated:** 2026-02-25
+> Part of the **FLUSYS** framework — a full-stack monorepo powering Angular 21 + NestJS 11 applications.