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

- 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

- 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

- 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)

- 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

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

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

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.