NCR (Non-Conformance Report) Module

Overview

The NCR (Non-Conformance Report) module is a comprehensive quality management system designed to track, manage, and resolve product or process non-conformances. It provides a structured workflow for identifying issues, determining root causes, implementing corrective actions, and preventing recurrence.

Business Purpose: The NCR module helps organizations:

• Document quality issues from customers, suppliers, or internal audits
• Track the lifecycle of non-conformances from creation to resolution
• Implement corrective and preventive actions (CAPA)
• Maintain compliance with quality standards (ISO 9001, AS9100, etc.)
• Analyze trends in quality issues to drive continuous improvement

Module Location: web/projects/packages/@barcoding/modules/ncr/

Used By: Backend application instance (port 4200)

Key Concepts

NCR Types

The system supports three distinct types of non-conformances:

1. Customer NCR (type_id: 1): Non-conformances reported by customers related to delivered products or services
2. Supplier NCR (type_id: 2): Non-conformances found in materials or components received from suppliers
3. Internal NCR (type_id: 6): Non-conformances identified through internal audits, inspections, or process reviews

NCR Templates

Templates determine the workflow and complexity level:

1. Simple View (template_id: 1): Basic NCR workflow with 3 stages (Simple 1D, Simple 2D, Simple 3D)
2. Advanced View - 8D (template_id: 2): Complete 8D problem-solving methodology with 8 stages (Stage 1D through Stage 8D)
3. Internal Basic (template_id: 3): Simplified internal audit workflow with 2 stages (Internal 1D, Internal 2D)

Each template has an associated dashboard configuration that displays relevant widgets and information for that workflow.

NCR Stages

Stages represent workflow progression points. The 8D methodology stages include:

• Stage 1D: Team formation and problem definition
• Stage 2D: Problem description
• Stage 3D: Containment actions
• Stage 4D: Root cause analysis
• Stage 5D: Corrective actions
• Stage 6D: Implementation and verification
• Stage 7D: Preventive measures
• Stage 8D: Team congratulations and closure

NCR Status

NCRs have two primary statuses:

• Status 1: Open/Active
• Status 2: Closed/Completed

Architecture

Database Schema

Primary Table: Ncr

Field	Type	Description
id	int	Auto-increment primary key
uid	varchar(255)	Unique identifier (e.g., "NCR-2024-001")
name	varchar(255)	NCR title/summary
description	longtext	Detailed description of the non-conformance
type_id	int	NCR type (1=Customer, 2=Supplier, 6=Internal)
template_id	int	Workflow template (1=Simple, 2=8D, 3=Internal)
status	int	Current status (1=Open, 2=Closed)
stage_id	int	Current workflow stage
partner_id	int	Related customer or supplier
site_id	int	Manufacturing site/location
user_created_id	int	User who created the NCR
date_created	datetime	Creation timestamp
date_recived	date	Date non-conformance was received/identified
date_planned_completion	date	Target completion date
date_close	datetime	Actual closure date
external_ref	varchar(512)	Customer/supplier reference number
safety_issue	boolean	Flag for safety-critical issues
root_cause	longtext	Root cause analysis text
root_category_id	int	Root cause category
liability_id	int	Liability determination (1=Justified, 2=Not justified)
containment_action	longtext	Immediate containment actions
proposed_corrective_actions	longtext	Proposed corrective actions
permanent_corrective_actions	longtext	Permanent corrective actions implemented
preventive_measures	longtext	Preventive measures to avoid recurrence
ncr_parent_id	int	Parent NCR (for related/linked NCRs)
audit_id	int	Related internal audit
progress	int	Completion percentage (0-100)

Related Tables:

• NcrPart: Parts/components affected by the NCR (many-to-many relationship)
• NcrJobListView: Related work orders/jobs (many-to-many relationship)
• NcrStage: Available workflow stages
• NcrTemplate: Template configurations
• NcrType: Type definitions
• NcrRootCategory: Root cause categories
• NcrLiability: Liability classifications
• NcrInternalAuditCategory: Internal audit categories

State Management (NGXS)

Store: NcrState (@barcoding/module-ncr)

State Interface:

interface NcrModelState {
  ncr: NcrWithRelations | {};           // Currently selected NCR
  ncrs: NcrWithRelations[];             // List of NCRs (for grid)
  ncrPart: {                            // NCR parts sub-state
    ncrParts: NcrPartWithRelations[];
    total: number;
    state: DataStateChangeEvent | {};
  };
  customers: PartnerWithRelations[];    // Customer list
  suppliers: PartnerWithRelations[];    // Supplier list
  partners: PartnerWithRelations[];     // Combined partners
  types: NcrTypeWithRelations[];        // NCR types
  templates: NcrTemplateWithRelations[]; // Templates
  statuses: any[];                      // Status options
  stages: NcrStageWithRelations[];      // Available stages
  sites: SiteWithRelations[];           // Manufacturing sites
  total: number;                        // Total count for pagination
  state: DataStateChangeEvent | {};     // Grid state
  loading: boolean;                     // Loading indicator
}

Key Actions:

• FindNcr: Load NCRs with filtering and pagination
• FindOneNcr: Load single NCR with all relations
• UpdateNcr: Update NCR fields
• UpdateDescriptionNcr: Update specific description field
• CloseNcr: Close an NCR (set status=2, date_close=now)
• OpenNcr: Reopen an NCR (set status=1, date_close=null)
• FindNcrPart: Load parts associated with an NCR
• CreateNcrPart: Add part to NCR
• UpdateNcrPart: Update NCR part information
• DeleteNcrPart: Remove part from NCR
• SendCongratulationsNcr: Send team congratulations email on closure
• ChangeState: Handle grid state changes (sorting, filtering, pagination)

Key Selectors:

@Select(NcrState.ncr) ncr$: Observable<NcrWithRelations>;
@Select(NcrState.forGrid) data$: Observable<GridDataResult>;
@Select(NcrState.loading) loading$: Observable<boolean>;
@Select(NcrState.types) types$: Observable<NcrTypeWithRelations[]>;
@Select(NcrState.stages) stages$: Observable<NcrStageWithRelations[]>;
@Select(NcrState.statuses) statuses$: Observable<any[]>;

API Integration

All API interactions use auto-generated SDK services from @barcoding/sdk:

Primary Controllers:

• NcrControllerService: Main NCR CRUD operations
• NcrPartControllerService: NCR parts management
• NcrTypeControllerService: NCR type metadata
• NcrTemplateControllerService: Template configurations
• NcrStageControllerService: Stage definitions
• NcrStatusControllerService: Status metadata
• NcrRootCategoryControllerService: Root cause categories
• NcrLiabilityControllerService: Liability classifications
• NcrInternalAuditCategoryControllerService: Internal audit categories

Include Pattern: When loading NCRs, the following relations are typically included:

include = [
  { relation: 'partner' },           // Customer/supplier info
  { relation: 'template', scope: {   // Template with stages
    include: [{ relation: 'stages' }]
  }},
  { relation: 'type' },              // NCR type
  { relation: 'user_created' },      // Creator info
  { relation: 'status_format' },     // Status details
  { relation: 'root_category' },     // Root cause category
  { relation: 'liability' },         // Liability info
  { relation: 'stage' },             // Current stage
  { relation: 'site' }               // Site info
]

User Interface Components

1. NCR List Component

Path: ncrListComponent/ncrList.component.ts

Route: /ncr/list

Purpose: Displays a searchable, filterable grid of all NCRs

Features:

• Kendo Grid with server-side pagination
• Advanced filtering by:
  • NCR ID
  • Type (Customer/Supplier/Internal)
  • Owner (user_created_id)
  • Site
  • Partner (customer/supplier)
  • Stage
  • Name
  • External reference
  • Safety issue flag
  • Status (Open/Closed)
• Inline editing for name, stage_id, and site_id fields
• Row actions: Preview, Print
• Bulk actions: Export to Excel, Generate PDF report
• Sorting on all columns
• Customizable page sizes (10, 20, 50, 100, 200, 500, 1000)

Grid Columns:

• ID: NCR identifier
• Type: Customer/Supplier/Internal
• Owner: Creator name
• Site: Manufacturing location
• Partner: Customer or supplier name
• Stage: Current workflow stage
• Name: NCR title
• Date Received: When issue was identified
• Date Deadline: Planned completion date
• Reference: External reference number
• Safety Issue: Yes/No flag
• Days Open: Calculated field (date_close - date_created or now - date_created)
• Date Close: Closure timestamp
• Status: Open/Closed

Calculated Fields:

calculateDays(item) {
  if (item.date_close) {
    return moment(item.date_close).diff(moment(item.date_created), 'days');
  } else {
    return moment().diff(moment(item.date_created), 'days');
  }
}

2. NCR View Component

Path: ncrViewTest/ncrView.component.ts

Route: /ncr/view/:ncrID

Purpose: Display detailed NCR information using a dashboard-based widget layout

Architecture: This component uses the dynamic dashboard system (@barcoding/gridster-core) to display NCR information. The layout is driven by the template's dashboard configuration.

Workflow:

1. Extract ncrID from route parameters
2. Dispatch FindOneNcr(ncrID) action to load NCR with all relations
3. Render app-dashboard-wrapper component with template's dashboard_id
4. Dashboard displays configured widgets specific to the NCR workflow

Available Widgets (Backend app):

• widget-ncr-info: NCR header information and actions
• widget-ncr-part: Parts affected by the NCR
• widget-ncr-root-cause: Root cause analysis
• widget-ncr-containment-action: Containment actions
• widget-ncr-proposed-corrective-actions: Proposed solutions
• widget-ncr-permanent-corrective-actions: Implemented solutions
• widget-ncr-preventive-mesures: Preventive measures
• widget-user-ncr: Team members assigned
• widget-partner-ncr-list: Related partner NCRs

3. NCR Creation Components

The module provides three specialized creation components, one for each NCR type:

3.1 Customer NCR Creator

Path: ncrCreateFromCustomer/ncrCreate.component.ts

Route: /ncr/customerNcrCreator

Purpose: Create NCRs for customer-reported non-conformances

Default Values:

• type_id: 1 (Customer)
• status: 1 (Open)
• template_id: 1 (Simple View)
• date_planned_completion: date_recived + 30 days

Form Steps (stepper interface):

Step 1: Basic Information

• Name: NCR title
• Description: Detailed description
• Customer: Searchable dropdown (autocomplete, min 3 chars)
• External Reference: Customer's reference number
• Site: Manufacturing site selection
• Date Received: Date issue was identified
• Planned Completion: Auto-calculated (received + 30 days)
• Template: Workflow template selection
• Safety Issue: Boolean checkbox

Step 2: Parts Selection

• Part Number: Searchable autocomplete (min 3 chars)
• Quantity: Affected quantity
• Serial Number: Part serial number
• Customer Reference: Customer's part reference
• GRN (Goods Received Note): GRN number
• PO (Purchase Order): PO reference
• Add/Remove parts dynamically

Step 3: Related Jobs

• Work Order Number: Searchable autocomplete
• Link multiple work orders to the NCR
• Add/Remove jobs dynamically

Step 4: Team Assignment

• User: Searchable user selection
• Assign multiple team members
• Team members receive email notification on NCR creation

Validation:

• Name is required
• Customer selection required
• Date received required

Email Notification on Creation:

// Sent to all team members
Subject: "Initiation of NCR{id} - {name} - {uid}"
Content:
  "We are initiating a new Non-Conformance Report (NCR) process to address:
   {description}

   The purpose of this NCR is to identify the causes of non-conformance,
   propose and implement corrective actions, and prevent recurrence of
   similar issues in the future.

   Detailed information regarding the NCR can be found in the Syneo System.

   Your participation and contributions to this process are invaluable..."

3.2 Supplier NCR Creator

Path: ncrCreateFromSupplier/ncrCreate.component.ts

Route: /ncr/supplierNcrCreator

Differences from Customer NCR:

• type_id: 2 (Supplier)
• date_planned_completion: date_recived + 7 days (shorter timeline)
• Supplier selection instead of customer
• Same stepper workflow otherwise

3.3 Internal NCR Creator

Path: ncrCreateFromInternal/ncrCreate.component.ts

Route: /ncr/internalNcrCreator

Purpose: Create NCRs for internal audit findings or process issues

Default Values:

• type_id: 6 (Internal)
• status: 1 (Open)
• template_id: 1 (Simple View)
• date_planned_completion: date_recived + 30 days

Unique Fields:

• Internal Audit Category: Category from NcrInternalAuditCategory table
• No partner/customer selection (internal only)
• Simplified workflow (no parts or jobs by default)

4. NCR Form Component

Path: ncrForm/ncrForm.component.ts

Purpose: Reusable form for editing existing NCRs (used in modal dialogs)

Usage:

const dialogRef = this.dialog.open(NcrFormModal, {
  width: '850px',
  data: { ncr }
});

Editable Fields:

• External reference
• Audit ID
• Planned completion date
• Date received
• Parent NCR ID
• Status
• Safety issue flag
• Stage
• Name
• Site
• User created
• Liability
• Partner (if applicable)

Dynamic Behavior:

• Parts grid (with add/edit/delete)
• Jobs association
• Team member management
• Supplier/customer autocomplete based on type_id

5. NCR Dashboard Component

Path: ncrDashboard/ncrDashboard.component.ts

Route: /ncr/dashboard

Purpose: Overview dashboard for NCR metrics and analytics (to be implemented)

6. NCR Settings Component

Path: ncrSettings/ncrSettings.component.ts

Route: /ncr/settings

Purpose: Configure NCR module settings (types, templates, stages, categories)

Business Workflows

Workflow 1: Customer NCR Lifecycle (8D Methodology)

┌─────────────────────────────────────────────────────────────────┐
│ 1. NCR Creation (Customer Type)                                 │
│    - Customer reports quality issue                             │
│    - QA creates NCR with customer info                          │
│    - Links affected parts, jobs, assigns team                   │
│    - Sets template to "Advanced View (8D)"                      │
│    - Team receives email notification                           │
└─────────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. Stage 1D: Team Formation                                     │
│    - Assign cross-functional team members                       │
│    - Define problem scope                                       │
│    - Set stage_id = 1                                           │
└─────────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. Stage 2D: Problem Description                                │
│    - Document detailed description                              │
│    - Update "description" field                                 │
│    - Attach photos, documents                                   │
│    - Set stage_id = 2                                           │
└─────────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│ 4. Stage 3D: Containment Actions                                │
│    - Implement immediate containment                            │
│    - Update "containment_action" field                          │
│    - Quarantine affected products                               │
│    - Set stage_id = 3                                           │
└─────────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│ 5. Stage 4D: Root Cause Analysis                                │
│    - Perform 5-Why analysis, fishbone diagram                   │
│    - Update "root_cause" field                                  │
│    - Select "root_category_id"                                  │
│    - Determine "liability_id" (Justified/Not justified)         │
│    - Set stage_id = 4                                           │
└─────────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│ 6. Stage 5D: Corrective Actions                                 │
│    - Propose corrective actions                                 │
│    - Update "proposed_corrective_actions" field                 │
│    - Get customer approval if needed                            │
│    - Set stage_id = 5                                           │
└─────────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│ 7. Stage 6D: Implementation & Verification                      │
│    - Implement corrective actions                               │
│    - Update "permanent_corrective_actions" field                │
│    - Verify effectiveness                                       │
│    - Set stage_id = 6                                           │
└─────────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│ 8. Stage 7D: Preventive Measures                                │
│    - Identify systemic improvements                             │
│    - Update "preventive_measures" field                         │
│    - Update procedures, training                                │
│    - Set stage_id = 7                                           │
└─────────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│ 9. Stage 8D: Team Recognition & Closure                         │
│    - Send congratulations to team                               │
│    - Dispatch SendCongratulationsNcr action                     │
│    - Dispatch CloseNcr action                                   │
│    - Sets status = 2, date_close = now                          │
│    - Sets date_congratulate_team                                │
│    - Set stage_id = 8                                           │
└─────────────────────────────────────────────────────────────────┘

Workflow 2: Supplier NCR Lifecycle (Simple View)

┌─────────────────────────────────────────────────────────────────┐
│ 1. NCR Creation (Supplier Type)                                 │
│    - Receiving inspection finds defect                          │
│    - QA creates NCR with supplier info                          │
│    - Links affected parts, GRN, PO                              │
│    - Sets template to "Simple View"                             │
│    - Timeline: date_recived + 7 days                            │
└─────────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. Simple 1D: Problem Definition & Containment                  │
│    - Document issue description                                 │
│    - Implement containment (quarantine parts)                   │
│    - Contact supplier                                           │
│    - Request supplier CAPA                                      │
│    - Set stage_id = 9                                           │
└─────────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. Simple 2D: Corrective Action                                 │
│    - Receive supplier 8D report                                 │
│    - Review and approve corrective actions                      │
│    - Update "proposed_corrective_actions"                       │
│    - Set stage_id = 10                                          │
└─────────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│ 4. Simple 3D: Verification & Closure                            │
│    - Verify supplier implemented actions                        │
│    - Inspect new deliveries                                     │
│    - Update "permanent_corrective_actions"                      │
│    - Dispatch CloseNcr action                                   │
│    - Set stage_id = 11, status = 2                              │
└─────────────────────────────────────────────────────────────────┘

Workflow 3: Internal NCR Lifecycle

┌─────────────────────────────────────────────────────────────────┐
│ 1. NCR Creation (Internal Type)                                 │
│    - Internal audit identifies issue                            │
│    - Auditor creates NCR                                        │
│    - Selects internal audit category                            │
│    - Assigns responsible department                             │
│    - Sets template to "Internal Basic"                          │
└─────────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. Internal 1D: Root Cause & Corrective Action                  │
│    - Department investigates                                    │
│    - Determines root cause                                      │
│    - Proposes corrective action                                 │
│    - Updates root_cause, proposed_corrective_actions            │
│    - Set stage_id = 12                                          │
└─────────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. Internal 2D: Implementation & Closure                        │
│    - Implement corrective action                                │
│    - Update permanent_corrective_actions                        │
│    - QA verifies implementation                                 │
│    - Dispatch CloseNcr action                                   │
│    - Set stage_id = 13, status = 2                              │
└─────────────────────────────────────────────────────────────────┘

Key Features

1. Multi-Type NCR Support

The system supports three distinct NCR types, each with appropriate workflows:

• Customer NCRs: Focus on customer satisfaction and timely resolution
• Supplier NCRs: Emphasis on supplier accountability and CAPA verification
• Internal NCRs: Continuous improvement through internal audit findings

2. Template-Based Workflows

Templates provide flexibility:

• 8D Methodology: Comprehensive problem-solving for complex issues
• Simple View: Streamlined workflow for straightforward issues
• Internal Basic: Efficient handling of internal findings

3. Dynamic Dashboard System

NCR details are displayed using the gridster-core widget system:

• Template determines which widgets are displayed
• Widgets are database-configured and user-customizable
• Each widget handles a specific aspect (info, parts, root cause, actions, etc.)

4. Parts Management

Track affected parts with detailed information:

• Part number with category
• Quantity affected
• Serial numbers
• Customer references
• GRN (Goods Received Note)
• PO (Purchase Order)
• Full CRUD operations via NcrPart controller

5. Team Collaboration

• Assign multiple team members to each NCR
• Team receives email notifications on NCR creation
• Team receives congratulations email on closure
• Track user assignments and roles

6. Document Linking

• Link NCRs to work orders (JobListView)
• Associate multiple documents/jobs per NCR
• Traceability from production to quality issues

7. Root Cause Analysis

Structured root cause tracking:

• Free-text root cause description
• Categorization via NcrRootCategory
• Liability determination (Justified/Not Justified)
• Historical analysis for trend identification

8. Corrective Actions (CAPA)

Four-stage action tracking:

1. Containment Actions: Immediate actions to prevent further issues
2. Proposed Corrective Actions: Planned long-term solutions
3. Permanent Corrective Actions: Implemented solutions
4. Preventive Measures: System improvements to prevent recurrence

9. Safety Issue Flagging

• Boolean flag for safety-critical non-conformances
• Filterable in NCR list for priority management
• Enables special handling workflows

10. Reporting & Analytics

• NCR Summary Report: Detailed NCR report with all sections
• NCR List Report: Filterable list export
• Excel Export: Full data export with current filters
• PDF Generation: Print-ready NCR reports
• Instant delivery via ReportService

11. Status Management

Two-state lifecycle:

• Open (status=1): NCR is active and being worked on
• Closed (status=2): NCR is resolved and verified

Actions:

• CloseNcr: Sets status=2, date_close=now
• OpenNcr: Reopens NCR by setting status=1, date_close=null

12. Favorites System

• Users can mark NCRs as favorites
• Tracked in UserObjectFav table
• Per-user, per-module favorites

13. Advanced Filtering

NCR list supports complex filtering:

• Text search on ID, name, external reference
• Dropdown filters for type, stage, status, site, partner
• Boolean filter for safety issues
• User selection for owner filter
• Combined filter logic with URL state persistence

14. Inline Editing

Grid allows inline editing of:

• NCR name
• Stage (workflow progression)
• Site assignment

Changes are immediately persisted to the database.

15. Parent-Child NCR Linking

• Link related NCRs via ncr_parent_id
• Create hierarchies for complex issues
• Track systemic problems across multiple NCRs

Data Model

NCR Entity

interface Ncr {
  // Identity
  id: number;                          // Auto-increment PK
  uid: string;                         // Unique identifier
  name: string;                        // NCR title

  // Classification
  type_id: number;                     // 1=Customer, 2=Supplier, 6=Internal
  template_id: number;                 // Workflow template
  status: number;                      // 1=Open, 2=Closed
  stage_id: number;                    // Current workflow stage

  // References
  partner_id: number;                  // Customer or Supplier
  site_id: number;                     // Manufacturing site
  user_created_id: number;             // Creator
  audit_id: number;                    // Related internal audit
  ncr_parent_id: number;               // Parent NCR if linked

  // Dates
  date_created: datetime;              // Creation timestamp
  date_recived: date;                  // Issue identified date
  date_planned_completion: date;       // Target completion
  date_close: datetime;                // Actual closure
  date_required_finish: date;          // Hard deadline
  date_draft: datetime;                // Draft save timestamp
  date_congratulate_team: datetime;    // Team congratulations sent

  // Description
  description: longtext;               // Problem description
  external_ref: string;                // Customer/supplier reference
  safety_issue: boolean;               // Safety flag

  // Root Cause Analysis
  root_cause: longtext;                // Root cause text
  root_category_id: number;            // Root cause category
  liability_id: number;                // Liability determination

  // Corrective Actions
  containment_action: longtext;        // Immediate actions
  proposed_corrective_actions: longtext; // Proposed solutions
  permanent_corrective_actions: longtext; // Implemented solutions
  preventive_measures: longtext;       // Preventive measures

  // Metadata
  progress: number;                    // Completion % (0-100)
  congratulate_team: longtext;         // Congratulations message
  dashboard_id: number;                // Associated dashboard
}

NCR Relations

interface NcrWithRelations extends Ncr {
  partner: PartnerWithRelations;           // Customer or Supplier
  template: NcrTemplateWithRelations;      // Workflow template
  type: NcrTypeWithRelations;              // NCR type
  user_created: UserWithRelations;         // Creator user
  status_format: NcrStatusWithRelations;   // Status metadata
  root_category: NcrRootCategoryWithRelations; // Root cause category
  liability: NcrLiabilityWithRelations;    // Liability info
  stage: NcrStageWithRelations;            // Current stage
  site: SiteWithRelations;                 // Manufacturing site
  parts: NcrPartWithRelations[];           // Affected parts
  documents: NcrJobListViewWithRelations[]; // Related jobs
  stages: NcrStageStatusWithRelations[];   // Stage progression history
  ncr: NcrWithRelations;                   // Parent NCR
  audit_category: NcrInternalAuditCategoryWithRelations; // Internal audit category
  dashboard: DashboardWithRelations;       // Dashboard configuration
}

NCR Part Entity

interface NcrPart {
  id: number;
  ncr_id: number;              // FK to Ncr
  part_id: number;             // FK to Part
  qty: number;                 // Affected quantity
  serial_number: string;       // Part serial number
  customer_ref: string;        // Customer's part reference
  grn: string;                 // Goods Received Note
  po: string;                  // Purchase Order
}

Validation Rules

NCR Creation:

• name is required
• type_id is required (1, 2, or 6)
• template_id is required
• status defaults to 1 (Open)
• date_recived is required
• date_planned_completion is auto-calculated based on type:
  • Customer: date_recived + 30 days
  • Supplier: date_recived + 7 days
  • Internal: date_recived + 30 days

NCR Update:

• status can only be 1 or 2
• date_close is auto-set when CloseNcr action is dispatched
• stage_id must be valid for the selected template

Parts:

• part_id is required
• qty must be > 0
• ncr_id is required (foreign key)

Business Rules

Rule 1: Timeline Calculation

Different NCR types have different urgency levels:

• Customer NCRs: 30 days from receipt (customer satisfaction critical)
• Supplier NCRs: 7 days from receipt (immediate containment needed)
• Internal NCRs: 30 days from receipt (continuous improvement timeline)

Rule 2: Email Notifications

On NCR Creation:

• All assigned team members receive notification email
• Email includes NCR ID, name, UID, and description
• Template: "Initiation of NCR{id} - {name} - {uid}"

On NCR Closure with Congratulations:

• Triggered by SendCongratulationsNcr action
• Sent to all team members (via Team table)
• Subject: "Closure of NCR{id} - {name} - {uid}"
• Content: Custom message from user

Rule 3: Status Locking

When an NCR is closed (status=2):

• date_close is set to current timestamp
• Further edits may be restricted (application-level)
• Can be reopened via OpenNcr action (clears date_close)

Rule 4: Stage Progression

• Stages must be appropriate for the selected template
• 8D template uses Stage 1D through Stage 8D
• Simple template uses Simple 1D through Simple 3D
• Internal template uses Internal 1D and Internal 2D
• Stage progression is manual (user-controlled)

Rule 5: Partner Type Validation

• Customer NCRs (type_id=1) should have partner_id pointing to a Customer
• Supplier NCRs (type_id=2) should have partner_id pointing to a Supplier
• Internal NCRs (type_id=6) typically have no partner_id

Rule 6: Root Cause and Liability

• Root cause analysis is required before closure (best practice)
• root_category_id categorizes the root cause for trending
• liability_id determines accountability:
  • 1 = Justified (company is at fault)
  • 2 = Not justified (external/unavoidable cause)

Rule 7: Safety Issues

• Safety-critical NCRs (safety_issue=true) may require:
  • Expedited handling
  • Management notification
  • Regulatory reporting
• Filterable for priority management

Rule 8: Parent-Child Relationships

• NCRs can be linked via ncr_parent_id
• Useful for:
  • Related issues from same root cause
  • Follow-up NCRs for verification
  • Systemic issues affecting multiple areas

Integration Points

1. Partner Module

• Customer and Supplier data from Partner table
• Used for partner_id foreign key
• Autocomplete search on company name

2. Part Module

• Part master data for affected parts
• Part category for classification
• Linked via NcrPart junction table

3. User/Team Management

• User assignment for NCR ownership
• Team collaboration via Team table
• Email notifications via EmailQueue

4. Job/Work Order System

• Links NCRs to production jobs
• Traceability from job to quality issue
• Via NcrJobListView junction table

5. Site Management

• Manufacturing site/location tracking
• Multi-site NCR analysis
• Site-based filtering and reporting

6. Dashboard/Widget System

• Template determines dashboard layout
• Widgets display NCR sections
• User-customizable widget arrangement

7. Report System

• ReportService generates NCR reports
• Controllers: ncr_summary, ncr_list
• Output formats: HTML, PDF, Excel
• Delivery: Instant or scheduled

8. Internal Audit Module

• Link NCRs to audit findings via audit_id
• Internal audit categories
• Audit-driven continuous improvement

API Endpoints

All endpoints are auto-generated via LoopBack 4 and available in the SDK. Key endpoints include:

NCR Controller:

• GET /ncrs - Find NCRs with filter/pagination
• GET /ncrs/{id} - Get single NCR with relations
• POST /ncrs - Create new NCR
• PATCH /ncrs/{id} - Update NCR
• DELETE /ncrs/{id} - Delete NCR
• GET /ncrs/count - Count NCRs with filter

NCR Part Controller:

• GET /ncr-parts - Find NCR parts
• POST /ncr-parts - Add part to NCR
• PATCH /ncr-parts/{id} - Update NCR part
• DELETE /ncr-parts/{id} - Remove part from NCR

NCR Type Controller:

• GET /ncr-types - Get NCR types

NCR Template Controller:

• GET /ncr-templates - Get templates with stages

NCR Stage Controller:

• GET /ncr-stages - Get all stages

NCR Status Controller:

• GET /ncr-statuses - Get status options

NCR Root Category Controller:

• GET /ncr-root-categories - Get root cause categories

NCR Liability Controller:

• GET /ncr-liabilities - Get liability options

Code Examples

Creating a Customer NCR

import { NcrControllerService, NewNcr } from '@barcoding/sdk';

// In component
constructor(private ncrApi: NcrControllerService) {}

createCustomerNcr() {
  const ncrObject: NewNcr = {
    name: "Defective paint finish",
    description: "Customer reported paint peeling on product",
    type_id: 1,                    // Customer
    template_id: 2,                // 8D methodology
    status: 1,                     // Open
    partner_id: 123,               // Customer ID
    site_id: 1,                    // Production site
    user_created_id: 456,          // Current user
    date_recived: new Date().toISOString(),
    date_planned_completion: moment().add(30, 'days').toISOString(),
    external_ref: "CUST-2024-001",
    safety_issue: false,

    // Relations
    relation_parts: [
      {
        part_id: 789,
        qty: 100,
        serial_number: "SN12345",
        grn: "GRN-2024-001"
      }
    ],
    relation_team: [
      { user_id: 456 },
      { user_id: 789 }
    ],
    relation_documents: [
      { job_list_id: 999 }
    ]
  };

  this.ncrApi.create({ body: ncrObject }).subscribe(
    ncr => {
      console.log('NCR created:', ncr.id);
      this.router.navigate(['/ncr/view', ncr.id]);
    }
  );
}

Loading and Filtering NCRs

import { Store } from '@ngxs/store';
import { ChangeState, NcrState } from '@barcoding/module-ncr';

// In component
constructor(private store: Store) {}

loadOpenCustomerNcrs() {
  const state = {
    skip: 0,
    take: 50,
    sort: [{ field: 'id', dir: 'desc' }],
    filter: {
      logic: 'and',
      filters: [
        { field: 'status', operator: 'eq', value: 1 },      // Open
        { field: 'type_id', operator: 'eq', value: 1 },     // Customer
        { field: 'safety_issue', operator: 'eq', value: true } // Safety
      ]
    }
  };

  this.store.dispatch(new ChangeState(state));

  // Subscribe to results
  this.store.select(NcrState.forGrid).subscribe(data => {
    console.log('NCRs:', data.data);
    console.log('Total:', data.total);
  });
}

Updating NCR with Root Cause

import { Store } from '@ngxs/store';
import { UpdateNcr } from '@barcoding/module-ncr';

// In component
constructor(private store: Store) {}

addRootCause(ncrId: number) {
  this.store.dispatch(new UpdateNcr(ncrId, {
    root_cause: "Inadequate training on painting process",
    root_category_id: 1,  // "Lack of Training"
    liability_id: 1,      // "Justified"
    stage_id: 4           // Stage 4D - Root Cause Analysis
  }));
}

Closing an NCR

import { Store } from '@ngxs/store';
import { CloseNcr, SendCongratulationsNcr } from '@barcoding/module-ncr';

// In component
constructor(private store: Store) {}

closeNcrWithCongratulations(ncrId: number) {
  // Send congratulations email first
  const message = `
    Great work team!

    We have successfully resolved this quality issue through your
    collaborative efforts. The implemented corrective actions have
    been verified and preventive measures are in place.

    Thank you for your dedication to quality!
  `;

  this.store.dispatch(new SendCongratulationsNcr(ncrId, message))
    .subscribe(() => {
      // Then close the NCR
      this.store.dispatch(new CloseNcr(ncrId));
    });
}

Managing NCR Parts

import { Store } from '@ngxs/store';
import { CreateNcrPart, UpdateNcrPart, DeleteNcrPart } from '@barcoding/module-ncr';

// In component
constructor(private store: Store) {}

// Add part to NCR
addPart(ncrId: number) {
  const part = {
    ncr_id: ncrId,
    part_id: 123,
    qty: 50,
    serial_number: "SN-2024-001",
    customer_ref: "CUST-PART-001",
    grn: "GRN-2024-100",
    po: "PO-2024-200"
  };

  this.store.dispatch(new CreateNcrPart(part));
}

// Update part quantity
updatePartQty(partId: number, newQty: number) {
  this.store.dispatch(new UpdateNcrPart(partId, { qty: newQty }));
}

// Remove part from NCR
removePart(partId: number) {
  if (confirm('Remove this part from the NCR?')) {
    this.store.dispatch(new DeleteNcrPart(partId));
  }
}

Generating NCR Report

import { ReportService } from '@barcoding/backend-core';
import { ReportOptionsSchema } from '@barcoding/sdk';

// In component
constructor(private reportService: ReportService) {}

generateNcrPdfReport(ncrId: number, userId: number) {
  const options: ReportOptionsSchema = {
    controller: 'ncr_summary',
    params: {
      ncr_id: ncrId
    },
    options_interface: {
      to: {
        user_id: [userId]
      },
      output: {
        html_content: true,
        file: { pdf: true }
      },
      delivery: {
        instant: true
      }
    }
  };

  this.reportService.generateReport(options).then(
    success => console.log('Report generated'),
    error => console.error('Report failed', error)
  );
}

Troubleshooting

Common Issues

Issue 1: NCR not displaying widgets

Cause: Template dashboard_id is not configured

Solution:

• Check template.dashboard_id is set
• Verify dashboard exists with configured widgets
• Check widget permissions for user role

Issue 2: Team members not receiving email

Cause: EmailQueue service not processing or invalid email addresses

Solution:

• Verify user.email is populated
• Check EmailQueue table for pending emails
• Verify SMTP configuration in API environment

Issue 3: Cannot close NCR

Cause: Missing required fields or permissions

Solution:

• Verify all required corrective action fields are filled
• Check user has permission to close NCRs
• Ensure NCR status is currently Open (status=1)

Issue 4: Parts not showing in NCR

Cause: NcrPart records not created or include filter missing

Solution:

• Check NcrPart table for records with correct ncr_id
• Verify API include filter includes 'parts' relation
• Check part_id foreign key is valid

Issue 5: Filters not working

Cause: Filter state not persisted or incorrect filter syntax

Solution:

• Check URL queryParams for state encoding
• Verify filter field names match database columns
• Check filter operator (eq, like, neq, etc.)

Performance Considerations

Pagination

• NCR list uses server-side pagination (skip/limit)
• Default page size: 25
• Maximum recommended: 500
• Use filtering to reduce data set before increasing page size

Eager Loading

• Always use include filters to avoid N+1 queries
• Standard include pattern loads 9 relations
• Each additional relation adds query overhead
• Consider loading only required relations for list views

Filtering Performance

• Indexed fields: id, type_id, status, partner_id, site_id, user_created_id
• Text search (LIKE) on name, external_ref is slower
• Combine filters with AND logic when possible
• Date range filters are efficient

Caching

• NCR types, templates, stages, categories are relatively static
• Consider caching these lookups in component
• Refresh cache on settings changes

Security Considerations

Access Control

• NCR viewing should be role-based
• Team members should have access to assigned NCRs
• Partner-specific NCRs should be restricted by partner relationship
• Site-based access control for multi-site organizations

Data Sensitivity

• Customer complaints may contain sensitive information
• External references should be protected
• Email notifications should use secure SMTP
• Audit trail for NCR changes (via date_created, user_created_id)

Validation

• Sanitize HTML content in description fields (using Quill editor)
• Validate file uploads for attachments
• Prevent SQL injection via parameterized queries (handled by LoopBack)
• XSS prevention via Angular's built-in sanitization

Future Enhancements

Potential improvements to the NCR module:

1. Workflow Automation: Auto-advance stages based on field completion
2. SPC Integration: Statistical Process Control charts for NCR trends
3. Cost Tracking: Track costs associated with NCRs (labor, materials, customer credits)
4. Mobile App: Field inspection and NCR creation from mobile devices
5. OCR Integration: Scan and parse customer complaint documents
6. AI-Assisted Root Cause: Suggest root causes based on historical data
7. Supplier Portal: Allow suppliers to respond to NCRs directly
8. Real-time Notifications: WebSocket-based real-time updates
9. Advanced Analytics: Pareto analysis, trend charts, predictive analytics
10. Integration with MES: Link NCRs to machine data and process parameters

Related Documentation

• Widget System Documentation
• NGXS State Management
• API SDK Usage
• Report Generation
• Email Queue System
• Partner Management
• Part Management
• Internal Audit Module

Changelog

Date	Version	Changes
2024-12-23	1.0.0	Initial documentation created

---

Document Information

• Module: NCR (Non-Conformance Report)
• Location: web/projects/packages/@barcoding/modules/ncr/
• Database Tables: Ncr, NcrPart, NcrType, NcrTemplate, NcrStage, NcrRootCategory, NcrLiability, NcrInternalAuditCategory
• State Management: NcrState (@barcoding/module-ncr)
• API Controllers: NcrController, NcrPartController, NcrTypeController, NcrTemplateController, NcrStageController
• Maintained By: Quality Assurance Team