# Dolibarr Module: ncr (Non-Conformance Report)

## GOAL

Build a lightweight Non-Conformance Report (NCR) module inside Dolibarr to register,
track, and close quality non-conformances — internal, customer complaints, and supplier issues.
Integrated with manufacturing (MO, workstations, products), DocControl, and Scrap modules.

---

## SCOPE (MVP - ETAP 1)

Implement a minimal but usable NCR system:

* NCR registry (create, list, view, close)
* NCR types: Internal / Customer Complaint / Supplier
* Status flow: Open → In Progress → Closed / Rejected
* Disposition: Use As Is / Rework / Scrap / Return to Supplier
* Containment actions (immediate response)
* Root cause (simple text field, ETAP 1)
* Links to: Product, MO, Workstation, Customer/Supplier
* Affected quantity tracking
* Permissions: read / write / close
* Simple dashboard

DO NOT implement in ETAP 1:

* 8D report
* CAPA module
* Cost of poor quality
* Pareto charts
* Customer portal

---

## MODULE INFO

* Name: ncr
* Technical name: modNcr
* Folder: htdocs/custom/ncr/
* Rights class: ncr
* Menu: Quality (under Quality top menu, same as Scrap)

---

## DIRECTORY STRUCTURE

htdocs/custom/ncr/

* class/
  * ncr.class.php
* core/modules/
  * modNcr.class.php
* sql/
  * install.sql
  * uninstall.sql
* css/
  * ncr.css
* js/
  * ncr.js
* pages/
  * index.php          (dashboard)
  * ncr_list.php       (list all NCRs)
  * ncr_card.php       (create / view / edit single NCR)
  * ncr_close.php      (close / disposition form)

---

## DATABASE SCHEMA

### TABLE: llx_ncr_ncr

| Column | Type | Description |
|--------|------|-------------|
| rowid | INT PK | |
| ref | VARCHAR(50) | Auto-generated: NCR-2026-0001 |
| ncr_type | VARCHAR(20) | Internal / Customer / Supplier |
| title | VARCHAR(255) | Short description |
| description | TEXT | Full problem description |
| status | VARCHAR(20) | Open / InProgress / Closed / Rejected |
| disposition | VARCHAR(30) | UseAsIs / Rework / Scrap / Return |
| qty_affected | DOUBLE | Affected quantity |
| fk_product | INT | Linked product |
| fk_mo | INT | Linked MO (optional) |
| fk_workstation | INT | Detected at workstation (optional) |
| fk_societe | INT | Customer or supplier (optional) |
| fk_user_creat | INT | |
| fk_user_assigned | INT | Responsible person |
| fk_user_closed | INT | |
| date_detected | DATE | |
| date_due | DATE | Target close date |
| date_closed | DATETIME | |
| root_cause | TEXT | Simple root cause description |
| containment | TEXT | Immediate containment action taken |
| entity | INT | |
| tms | TIMESTAMP | |

---

### TABLE: llx_ncr_action

Corrective / containment actions attached to an NCR.

| Column | Type | Description |
|--------|------|-------------|
| rowid | INT PK | |
| fk_ncr | INT | FK to llx_ncr_ncr |
| action_type | VARCHAR(20) | Containment / Corrective / Preventive |
| description | TEXT | |
| fk_user_assigned | INT | |
| due_date | DATE | |
| completed_at | DATETIME | |
| status | VARCHAR(20) | Open / Done |
| fk_user_creat | INT | |
| tms | TIMESTAMP | |

---

### TABLE: llx_ncr_link

Links NCR to other Dolibarr objects.

| Column | Type | Description |
|--------|------|-------------|
| rowid | INT PK | |
| fk_ncr | INT | |
| link_type | VARCHAR(50) | product / mo / workstation / document / scrap |
| link_id | INT | rowid of linked object |

---

## CORE LOGIC

### REF AUTO-GENERATION

Format: `NCR-{YYYY}-{sequence 4 digits}`
Example: `NCR-2026-0001`

Sequence: SELECT MAX(rowid) from llx_ncr_ncr per entity + year, or use Dolibarr
`getNextValue()` pattern with a mask.

---

### STATUS FLOW

```
Open → InProgress → Closed
                 → Rejected
```

* **Open**: just created, no action yet
* **InProgress**: containment applied, root cause being investigated
* **Closed**: disposition confirmed, actions completed
* **Rejected**: duplicate or invalid NCR

Transitions enforced in `ncr_card.php` / `ncr_close.php`.

---

### DISPOSITION

| Code | Meaning |
|------|---------|
| `USE_AS_IS` | Deviation accepted, no rework |
| `REWORK` | Part reworked to spec |
| `SCRAP` | Part scrapped (optionally link to llx_scrap) |
| `RETURN` | Returned to supplier |

---

### LINK TO SCRAP MODULE

When disposition = `SCRAP`:
* Optionally create a record in `llx_scrap` automatically
* Link via `llx_ncr_link` with `link_type = 'scrap'`

---

### LINK TO DOCCONTROL

When NCR is linked to a Work Instruction or Manufacturing Method:
* Store in `llx_ncr_link` with `link_type = 'document'`
* DocControl ETAP 3 shows "Referenced in X NCRs" on document card

---

## PERMISSIONS

| Right | Description |
|-------|-------------|
| `read` | View NCR list and cards |
| `write` | Create and edit NCRs |
| `close` | Close or reject NCRs |

---

## UI / PAGES

### 1. Dashboard (index.php)

* Open NCRs count (by type: Internal / Customer / Supplier)
* Overdue NCRs (date_due < today and status != Closed)
* NCRs closed this month
* Top 5 products with most NCRs (last 90 days)
* Link to full list

---

### 2. NCR List (ncr_list.php)

Table columns:
* Ref | Type | Title | Product | Status | Disposition | Assigned | Due date | Actions

Filters:
* Type, Status, Product, Assigned user, Date range

---

### 3. NCR Card (ncr_card.php)

Sections:
* Header: ref, type, status badge, title
* Details: description, product, MO, workstation, qty affected, detected date
* Customer/Supplier (if type = Customer or Supplier)
* Containment action (text)
* Root cause (text)
* Actions table (llx_ncr_action)
* Linked objects (product, MO, WI document, scrap record)
* Audit trail: created by, assigned to, closed by + dates

Buttons (permission-gated):
* Edit | Add Action | Close NCR | Reject

---

### 4. Close Form (ncr_close.php)

* Select disposition
* Enter closing notes
* Set effective_date
* Confirm close → update status + date_closed + fk_user_closed

---

## MENU STRUCTURE

Under Quality top menu (same as Scrap module):

```
Quality
  └── NCR
        ├── Dashboard         → pages/index.php
        ├── All NCRs          → pages/ncr_list.php
        ├── Internal          → pages/ncr_list.php?type=Internal
        ├── Customer          → pages/ncr_list.php?type=Customer
        └── Supplier          → pages/ncr_list.php?type=Supplier
```

---

## ETAP 1 checklist

- [ ] modNcr.class.php — module descriptor
- [ ] install.sql — create llx_ncr_ncr, llx_ncr_action, llx_ncr_link
- [ ] uninstall.sql
- [ ] pages/index.php — dashboard
- [ ] pages/ncr_list.php — list with filters
- [ ] pages/ncr_card.php — create / view / edit
- [ ] pages/ncr_close.php — close / disposition
- [ ] Auto-ref generation (NCR-YYYY-XXXX)
- [ ] Status transitions + permission checks
- [ ] Link to product, MO, workstation
- [ ] Actions table (llx_ncr_action) CRUD in card
- [ ] CSS + basic JS

---

## ETAP 2 — 8D Report + CAPA

### 8D Report

Structured 8-step problem solving attached to an NCR.

New table `llx_ncr_8d`:
* D1: Team
* D2: Problem description
* D3: Containment actions
* D4: Root cause (Ishikawa / 5-Why)
* D5: Corrective actions chosen
* D6: Corrective actions implemented + verified
* D7: Preventive actions
* D8: Team recognition / closure

Page: `pages/ncr_8d.php` — dedicated 8D form, printable.

### CAPA Link

When 8D D7 preventive actions are defined → optionally create a CAPA record
(requires CAPA module — future).

### Supplier NCR flow

* Send NCR notification email to supplier contact
* Track supplier response (8D from supplier)
* Log supplier response text + date
* Auto-create purchase return (Dolibarr `expedition retour`) optionally

---

## ETAP 2 checklist

- [ ] llx_ncr_8d table + pages/ncr_8d.php
- [ ] 8D printable PDF view
- [ ] Supplier email notification (via Dolibarr mail)
- [ ] Supplier response tracking
- [ ] CAPA placeholder link

---

## ETAP 3 — Analytics + Cost of Poor Quality

### Pareto Chart
* Top non-conformance causes (last N days)
* Top products / workstations with most NCRs
* Rendered with Chart.js (already used in Dolibarr)

### Cost of Poor Quality (COPQ)
* Add `cost_internal` and `cost_external` fields to llx_ncr_ncr
* Dashboard: total COPQ per month / type / product

### Trend Reports
* NCR count over time (monthly chart)
* Closure rate (% closed on time)
* Repeat NCR detection (same product + root cause within 90 days)

### ETAP 3 checklist

- [ ] Pareto chart page
- [ ] COPQ fields + reporting
- [ ] Monthly trend chart
- [ ] Repeat NCR detection + alert
- [ ] MDI-style NCR export (PDF/CSV) for audits

---

## INTEGRATION SUMMARY

| Module | How it connects |
|--------|----------------|
| Scrap | Disposition=Scrap → auto-create scrap record |
| DocControl | NCR links to violated Work Instruction / MFG Method |
| MRP (MO) | NCR links to production order |
| Products | NCR links to product, shows NCR count on product card |
| Societe | Customer complaint / supplier NCR links to third party |
| Workstation | NCR detected at workstation |

---

## GIT

```
git add -A
git commit -m "feat(ncr): initial NCR module scaffold"
git push origin master
```