quality_app-v2/documentation/TRACEABILITY_WORKFLOW_ANALYSIS.md

# CP Traceability Workflow - Current State & Implementation Strategy

## Current Database Schema Analysis

### ✅ What EXISTS

**1. boxes_crates table**
```sql
- id (BIGINT, PK)
- box_number (VARCHAR(20), UNIQUE) ✅ BOX tracking
- status (ENUM: 'open', 'closed') ✅ Box state
- location_id (BIGINT, FK) ✅ Box location reference
- created_at (TIMESTAMP)
- updated_at (TIMESTAMP)
- created_by (INT, FK) ✅ User who created box
```

**2. warehouse_locations table**
```sql
- id (BIGINT, PK)
- location_code (VARCHAR(12), UNIQUE) ✅ FG_INCOMING, TRUCK_LOADING, etc
- size (INT)
- description (VARCHAR(250))
- created_at, updated_at (TIMESTAMP)
```

**3. scanfg_orders table**
```sql
- Id (INT, PK)
- operator_code (VARCHAR(50))
- CP_full_code (VARCHAR(50)) ✅ CP identifier
- OC1_code, OC2_code, quality_code (VARCHAR)
- approved_quantity, rejected_quantity (INT)
- date, time (DATE, TIME)
- created_at (TIMESTAMP)
```

**4. warehouse_boxes table** (Legacy/Unused)
```sql
- Similar to boxes_crates - appears to be duplicate
```

### ❌ What's MISSING

**1. box_contents table - NOT CREATED**
- Code creates it dynamically but it's never persisted
- Should link CP codes to boxes with quantity tracking

**2. scanfg_orders lacks CP-to-Box linkage**
- No `box_id` field to link scanned CP to its box
- No `location_id` field for scanned item location
- Breaks complete traceability chain

**3. No table for CP tracking history**
- Can't track CP movement between locations
- No audit trail for CP-to-box assignments

## Required Traceability Workflow

### Current Requirement:
```
CP Scan → Box Assignment → Location Assignment → Traceability
```

### Step-by-step required workflow:

1. **CP Scanned** (via FG Scan page)
   - CP data saved to `scanfg_orders`
   - Currently: ❌ NO link to box

2. **Box Created** (via Quick Box)
   - Box created in `boxes_crates` with BOX00000001
   - Currently: ✅ WORKING
   - But: ❌ NOT automatically assigned to FG_INCOMING

3. **CP Assigned to Box**
   - CP added to `box_contents` linking CP to box_id
   - Currently: ⚠️ PARTIALLY WORKING (table created dynamically)
   - But: ❌ Not persisted in initialization script

4. **Box Assigned to Location**
   - boxes_crates.location_id set to warehouse_locations.id
   - Currently: ❌ NOT implemented in quick-box workflow

5. **Location Tracking**
   - Box moves from FG_INCOMING → (other locations)
   - Currently: ❌ NO movement history tracking

## Implementation Strategy

### PHASE 1: Database Fixes (CRITICAL)

**1A. Create persistent box_contents table in initialize_db.py**
```sql
CREATE TABLE box_contents (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    box_id BIGINT NOT NULL,
    cp_code VARCHAR(50) NOT NULL,
    quantity INT DEFAULT 1,
    added_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (box_id) REFERENCES boxes_crates(id) ON DELETE CASCADE,
    INDEX idx_box_id (box_id),
    INDEX idx_cp_code (cp_code)
)
```

**1B. Enhance scanfg_orders table with traceability fields**
```sql
ALTER TABLE scanfg_orders ADD COLUMN:
- box_id (BIGINT, FK to boxes_crates) - NULL by default, set when scanned in box mode
- location_id (BIGINT, FK to warehouse_locations) - Current location of this CP
- scanned_at (TIMESTAMP) - When this CP was scanned
```

**1C. Create cp_location_history table for audit trail**
```sql
CREATE TABLE cp_location_history (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    cp_code VARCHAR(50) NOT NULL,
    box_id BIGINT NOT NULL,
    from_location_id BIGINT,
    to_location_id BIGINT,
    moved_by INT,
    moved_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    reason VARCHAR(100),
    FOREIGN KEY (box_id) REFERENCES boxes_crates(id),
    FOREIGN KEY (from_location_id) REFERENCES warehouse_locations(id),
    FOREIGN KEY (to_location_id) REFERENCES warehouse_locations(id),
    FOREIGN KEY (moved_by) REFERENCES users(id)
)
```

**1D. Ensure warehouse_boxes is retired or removed**
- Currently has same structure as boxes_crates
- Causes confusion
- Decision: REMOVE or consolidate

### PHASE 2: Backend API Updates

**2A. Modify `/api/create-quick-box`**
```
Current: Creates box, NO location assignment
New: Creates box AND assigns to FG_INCOMING location
- Query: SELECT id FROM warehouse_locations WHERE location_code = 'FG_INCOMING'
- Update: SET location_id = fg_incoming_id
```

**2B. Modify `/api/assign-cp-to-box`**
```
Current: Assigns CP to box only
New: 
1. Assign CP to box
2. Update scanfg_orders.box_id = box_id
3. Update scanfg_orders.location_id = box's location_id
4. Create entry in cp_location_history (from NULL to FG_INCOMING)
```

**2C. Create new `/api/move-box-location`**
```
Input: box_id, from_location_id, to_location_id, reason
Output: Success or error
Actions:
1. Validate box exists
2. Update boxes_crates.location_id
3. Create audit trail in cp_location_history
4. Update all CP entries' location_id (via scanfg_orders)
```

**2D. Create new `/api/get-cp-traceability`**
```
Input: cp_code
Output: Full CP journey
- Original scan data (from scanfg_orders)
- Current box assignment (box_number, status)
- Current location (warehouse_locations)
- Full movement history (from cp_location_history)
- All scanned details (operator, times, quality codes)
```

### PHASE 3: Frontend Updates

**3A. FG Scan - Quick Box Workflow**
```
Current: Create box → Print label → Assign CP
New Flow:
1. Create box (auto FG_INCOMING location)
2. Show confirmation: "Box BOX00000001 created in FG_INCOMING"
3. Print label
4. Assign CP
5. Show: "CP XX-XX-XX assigned to BOX00000001 (FG_INCOMING)"
```

**3B. Create Location Movement Modal**
```
Show modal: "Move Box to New Location"
- Select from_location: FG_INCOMING
- Select to_location: (dropdown of other locations)
- Reason: (dropdown - "Shipped", "Quality Check", "Repack", etc)
- Button: "Confirm Move"
```

**3C. Create CP Traceability View**
```
New page: /quality/cp-traceability
Input: CP Code search
Output:
- CP Details (from scanfg_orders)
- Current Box: BOX00000001
- Current Location: FG_INCOMING (since 2026-01-28 18:42)
- Movement History:
  * 2026-01-28 18:42 - Placed in FG_INCOMING (by Admin)
  * [future movements]
```

### PHASE 4: Reports & Analytics

**4A. Box Inventory Report**
```
Show:
- All active boxes with location
- Number of CPs in each box
- Box creation date
- Last movement date
```

**4B. CP Location Audit Trail**
```
Show:
- CP Code
- All locations visited
- Time in each location
- User who moved it
- Reason for movement
```

## Implementation Priority

| Phase | Component | Impact | Effort | Priority |
|-------|-----------|--------|--------|----------|
| 1A | Create box_contents persistent table | High | Low | 🔴 CRITICAL |
| 1B | Add fields to scanfg_orders | High | Medium | 🔴 CRITICAL |
| 1C | Create cp_location_history audit | High | Medium | 🟡 HIGH |
| 2A | Auto FG_INCOMING on quick box | High | Low | 🔴 CRITICAL |
| 2B | Update assign-cp-to-box logic | High | Medium | 🔴 CRITICAL |
| 2C | New move-box-location API | Medium | Medium | 🟡 HIGH |
| 2D | New get-cp-traceability API | High | Medium | 🟡 HIGH |
| 3A | Update FG Scan UI | Medium | Low | 🟡 HIGH |
| 3B | Location movement modal | Medium | Medium | 🟡 HIGH |
| 3C | CP traceability view | Medium | Medium | 🟡 HIGH |
| 4A | Box inventory report | Low | Low | 🟢 NICE-TO-HAVE |
| 4B | CP audit trail report | Low | Low | 🟢 NICE-TO-HAVE |

## Proposed Implementation Order

1. **Do CRITICAL items first** (1A, 1B, 2A, 2B)
   - Ensures data integrity
   - Makes quick box workflow functional
   - Enables CP-to-box traceability

2. **Then add audit trail** (1C, 2C, 2D)
   - Enables full movement tracking
   - Provides compliance/audit capability

3. **Then update UI** (3A, 3B, 3C)
   - User can see and manage traceability
   - Functional workflows appear in UI

4. **Finally analytics** (4A, 4B)
   - Nice-to-have reports
   - Can be added later

## Current Blockers

❌ **BLOCKER 1**: box_contents table not persistent
- `boxes_crates` exists but `box_contents` is created dynamically
- Risk: Data loss on table recreation
- Fix: Add to initialize_db.py

❌ **BLOCKER 2**: No auto FG_INCOMING assignment
- When quick box created, location_id is NULL
- Box not tracked to any location
- Fix: Query FG_INCOMING ID and set location_id

❌ **BLOCKER 3**: scanfg_orders has no box linkage
- CP scan doesn't know which box it belongs to
- Can't trace "which CPs are in this box"
- Fix: Add box_id, location_id fields

❌ **BLOCKER 4**: No movement history
- Can't answer "where was this CP yesterday?"
- No audit trail for compliance
- Fix: Create cp_location_history table + trigger updates

## Recommendations

### Recommendation 1: Start with Database
```
PHASE 1 should be done FIRST before any frontend changes
Reason: If we change UI before DB is ready, data will be corrupted
Timeline: 30 minutes
Impact: HIGH - enables everything else
```

### Recommendation 2: Make box_contents Persistent
```
Current: Table created in API route - recreated on each app restart
New: Table created once in initialize_db.py - persistent
Benefit: Data survives app restarts
```

### Recommendation 3: Add Audit Trail Table Now
```
Even if not used immediately, having cp_location_history from start
means historical data will be captured automatically
```

### Recommendation 4: Update Routes Incrementally
```
Do 2A + 2B (auto location on quick box)
Then do 2C + 2D (movement tracking)
Then UI updates
```

## SQL Migration Script (READY TO RUN)

See `cp_traceability_migration.sql` (to be generated)

## Success Criteria

When complete:
- ✅ Every CP has a box_id
- ✅ Every box has a location_id
- ✅ Quick box auto-assigns to FG_INCOMING
- ✅ CP can be traced through all locations
- ✅ Movement history is auditable
- ✅ Reports show complete traceability

---

**Next Step**: Confirm this strategy with user, then execute PHASE 1 implementation.