# Guillotine Module — Plan

**Module:** `guillotine`  
**Purpose:** Manage pre-production material cutting operations (guillotine/slitting) before forming.  
**Date:** 2026-04-08

---

## Process Flow

```
Incoming material pack (delivery)
        ↓
Guillotine cut job — cut to target dimensions
        ↓
Cut pieces generated — status: "available"
        ↓
Assign piece(s) to MO (forming)
        ↓
MO starts with pre-cut material (traceability)
```

---

## Database Entities

### `llx_guillotine_pack` — incoming material pack

| Column | Type | Description |
|---|---|---|
| `rowid` | INT | PK |
| `ref` | VARCHAR(64) | e.g. PACK-2026-0042 |
| `fk_product` | INT | product (e.g. ref 61111) |
| `fk_lot` | INT | lot/batch (FK → llx_product_lot) |
| `qty_received` | DOUBLE | total quantity in pack |
| `qty_remaining` | DOUBLE | quantity remaining to cut |
| `date_received` | DATETIME | delivery date |
| `fk_user` | INT | user who received |
| `note` | TEXT | remarks |
| `status` | TINYINT | 0=draft, 1=open, 2=closed |
| `entity` | INT | Dolibarr entity |

### `llx_guillotine_cut` — cut job

| Column | Type | Description |
|---|---|---|
| `rowid` | INT | PK |
| `ref` | VARCHAR(64) | e.g. CUT-2026-0001 |
| `fk_pack` | INT | FK → guillotine_pack |
| `fk_mo` | INT | target MO (optional) |
| `qty_in` | DOUBLE | material quantity consumed |
| `qty_pieces` | INT | number of pieces produced |
| `qty_waste` | DOUBLE | offcut / waste quantity |
| `target_width` | DOUBLE | target width (mm) |
| `target_length` | DOUBLE | target length (mm) |
| `date_cut` | DATETIME | when the cut was performed |
| `fk_user` | INT | operator |
| `fk_ws` | INT | workstation (optional) |
| `note` | TEXT | remarks |
| `status` | TINYINT | 0=planned, 1=done |
| `entity` | INT | Dolibarr entity |

### `llx_guillotine_piece` — individual cut piece

| Column | Type | Description |
|---|---|---|
| `rowid` | INT | PK |
| `ref` | VARCHAR(64) | e.g. PCE-2026-0001 (scannable QR ref) |
| `fk_cut` | INT | FK → guillotine_cut |
| `fk_mo` | INT | assigned MO (NULL = free/available) |
| `width` | DOUBLE | actual width (mm) |
| `length` | DOUBLE | actual length (mm) |
| `status` | TINYINT | 0=available, 1=assigned, 2=used, 3=scrapped |
| `entity` | INT | Dolibarr entity |

---

## Module Structure

```
custom/guillotine/
├── core/modules/modGuillotine.class.php   ← module registration, family='Development'
├── sql/
│   ├── llx_guillotine_pack.sql
│   ├── llx_guillotine_cut.sql
│   └── llx_guillotine_piece.sql
├── class/
│   ├── GuillotinePack.class.php
│   └── GuillotineCut.class.php
├── admin/
│   └── guillotine_setup.php
├── pack_list.php          ← list of packs
├── pack_card.php          ← pack card + cut jobs list
├── cut_card.php           ← cut job form + generate pieces
├── piece_list.php         ← list of available pieces (assign to MO)
├── langs/en_US/guillotine.lang
├── css/guillotine.css
├── docs/
│   └── MODULE_PLAN.md     ← this file
└── README.md
```

**Module number:** `130000` (verify free range in Admin → Modules)

---

## UI Workflow

1. **Pack reception** → `pack_card.php` — enter product, qty, lot → status open
2. **Create cut job** → from pack card → `cut_card.php` — set dimensions, qty pieces, waste
3. **Confirm cut** → generates `guillotine_piece` records (QR label per piece printable)
4. **Assign to MO** → from `piece_list.php` or MO card (hook) — piece.status=1, fk_mo=X
5. **MO starts** → operator knows which piece to take (ref/QR visible on MO card)

---

## Decisions (confirmed 2026-04-08)

1. **Dimensions** — width + length only. Thickness is constant (not tracked per piece).
2. **QR labels** — implement QR label printing per piece after cut confirmation.
3. **Piece ref** — each cut produces pieces with new unique scannable refs (`PCE-YYYY-NNNN`). Assignment to MO is traceability/informational; MO is not blocked by missing piece assignment.
4. **Stock / confirmation** — cut confirmation is a deliberate action (like scrap confirmation). On confirm: qty deducted from pack, pieces created in `available` status.
5. **Module number** — `130000` confirmed free (checked against all custom modules).

---

## Git repository

`https://github.com/ciachoo/guillotine.git`