Form Module

Overview

@barcoding/module-form is the system-wide form designer and execution layer. It lets quality, manufacturing, and service teams model structured forms, publish versioned revisions, assign them to business objects (parts, documents, NCRs, etc.), and capture auditable results from the Front application. The module bundles:

• Backend workbench widgets for managing forms, revisions, relations, and result analytics
• LoopBack models (Form, FormRevision, FormRelation, FormResult) that store definitions, assignments, and captured data
• A shared renderer (@barcoding/core) and dialog that power the Front widget used on shop-floor dashboards

The granular widget / API behaviour is covered in the Form Architecture Guide.

Domain Model & Statuses

Entity	Purpose	Status Codes & Notes
Form (api/b3api/src/models/form.model.ts)	Human-friendly wrapper (name, category, status) that points to an active revision.	status: 1=draft, 2=active, 3=archived. form_revision_id stores the published definition served to runners.
FormRevision	Versioned JSON definition with change notes.	status: 1=draft, 2=published, 3=deprecated. rev_number is incremented numerically to preserve ordering.
FormRelation	Connects a form to a module/object pair (e.g., Part, Document).	Fields include required and validation_scope (per_user, per_object, global).
FormResult	Captured answers referencing a form, revision snapshot, and contextual IDs (module/object/part/document).	status: 1=in_progress, 2=completed. Stores definition_snapshot, progress percentage, optional signature_* metadata, and relation pointers for analytics/printing.

Core Capabilities

• Designer & Revisions: build drag-and-drop definitions, maintain multiple revisions, and mark a published revision as the active schema delivered to production users.
• Contextual Assignments: relate forms to modules/objects and control validation scope (per user, per object, global) as well as whether a form is mandatory for a workflow.
• Result Lifecycle: operators fill forms through the Front widget with autosave, electronic signatures, and completion flows; results stay linked to parts/documents for auditing.
• Analytics & Reporting: built-in widgets surface progress, pass/fail breakdowns, and generate printable HTML/PDF reports for individual results or aggregated summaries.

Supported Field Types (High Level)

• Radio / Radio N/A: single-choice questions with optional "Not Applicable" state for compliance forms.
• Radio with Conditional Comment: prompts the user for a follow-up text value when a specific answer (e.g., "No") is chosen.
• Measurement: numeric inputs with units plus tolerance or min/max validation that power pass/fail analytics.
• Matrix: grid where each row must map to exactly one column—ideal for checklists that require per-row selections.
• Input Table: spreadsheet-style rows and columns for capturing multiple numeric readings per row.

See the Form Architecture Guide for data shapes and validation specifics for each type.

Key Workflows

1. Authoring – create the base form record, design questions in the builder, and iterate through revisions until published.
2. Assignment – map the form to modules, parts, NCRs, or documents using relations and define whether completion is per user or per object.
3. Execution – frontline widgets fetch required forms, open the renderer dialog, enforce validation, and capture signatures.
4. Review – supervisors view, print, or delete results from the Backend workbench and trigger analytics/summary reports.

Further Reading

• Form Architecture Guide for widget breakdowns, renderer behaviour, data schemas, and reporting pipelines.
• Form Widgets Suite for per-widget guides covering Backend and Front dashboards.
• Module Ecosystem to see how Form integrates with other feature modules.