# CNC24 Order Tracking — How It Works

> **For:** anyone at CNC24 who interacts with the tool, no technical background required.
> **TL;DR:** A robot watches every supplier order, drafts emails when something needs attention, and waits for a human to click Send. Nothing goes out automatically.

[TOC]

---

## 1. What this tool is

The tracking system is a **draft-writing assistant**. It does three things, all day, every day:

1. **Watches** every open supplier order — what's been shipped, what's confirmed, what's late.
2. **Drafts** the email that should be sent — to a supplier, to a customer, or as an internal task.
3. **Waits for you to approve.** Every email is reviewed by a human first.

Nothing — *nothing* — gets sent to a supplier or customer without someone clicking **Approve & Send**. This is by design.

---

## 2. The big picture in one diagram

flowchart LR
    A[Supplier replies<br>or SF updates] --> B[AI reads<br>and classifies]
    B --> C[System drafts<br>the next action]
    C --> D[Human reviews<br>on /drafts page]
    D -->|Approve & Send| E[Email goes out<br>SF updated]
    D -->|Edit & Send| E
    D -->|Reject + reason| F[Discarded<br>feedback logged]
    F -.learns.-> B

You spend your time on the **/drafts** page. The system handles steps A → C automatically.

---

## 3. What you do day-to-day

### The /drafts page

This is the only screen you really need. Drafts arrive throughout the day, grouped by type:

| Draft type | What it means |
|---|---|
| **Supplier Follow-up** | Chase a supplier — "where are we on this order?" |
| **Reply** | Respond to a supplier email that came in |
| **Customer Notification** | Tell a customer their delivery date moved |
| **Customer Status Reply** | Answer a customer "where's my order?" question |
| **Supplier Expedite** | Ask a supplier to deliver earlier (customer requested) |
| **Customer Expedite Reply** | Tell the customer the result of an expedite request |
| **Manual Action** | Flag something for human judgment — no email is sent |
| **Tracking Check** | Internal alert: a shipment looks stuck |
| **Delivery Risk Check** | Internal alert: an order shipped but customer date is close |

For every draft you have four buttons:

- **Approve & Send** — send as-is
- **Edit & Send** — change the text first, then send
- **Reject** — discard, optionally with a reason ("wrong date", "complaint, not tracking", etc.)
- **Re-Check** — ask the system to re-evaluate with current data

After approve/reject, you can give a **1-5 star rating** so we can track draft quality over time.

:::info
**Why ratings matter.** When 5+ drafts get rejected with the same complaint ("complaint orders shouldn't trigger this", "German suppliers contacted too early"), engineering ships a code change. The tool has improved through ~200 such fixes in the last month.
:::

---

## 4. What the system does automatically (in the background)

These run on schedules. You see the *output* on /drafts; you don't trigger them yourself.

| When | What runs | What it does |
|---|---|---|
| Every hour, business days | **Hourly classification** | Pulls every open order from Salesforce and updates statuses. The heartbeat — everything else builds on this. |
| Every 30 min, business hours | **Case email check** | Reads new supplier emails. AI classifies them (shipped, new date, etc.). Updates dates. Drafts a reply. |
| Every 30 min, business hours | **Customer email check** | Reads new customer emails. Routes to the right team (status question → us; complaint → Complaints team). |
| Continuous | **Proactive supplier outreach (Phase A)** | For each supplier with orders nearing delivery, drafts ONE consolidated check-in email covering all their open orders. |
| Mon/Thu mornings | **Consolidated supplier check** | Same as Phase A but a structured table-format weekly check. |
| Mon-Sat 09:00 Berlin | **Daily imminent check** | High-urgency check on orders due in the next few days, plus all overdue. |
| Every 2 hours, 24/7 | **Tracking poll** | Checks DHL and 17TRACK for shipment updates. Detects stuck shipments. |
| Every weekday 10:00 Berlin | **Daily digest** | Summary of pending drafts grouped by age — helps you spot stale items. |
| Sundays 03:00 | **ML training** | Re-trains the supplier-reliability and draft-quality predictions. |

---

## 5. How long the system waits before contacting suppliers

The system asks suppliers **earlier** when transit is longer:

| Where the supplier is | When we first reach out |
|---|---|
| Germany / EU (short transit) | **7 days** before delivery date |
| Non-EU (China, India, USA, etc.) | **21 days** before delivery date |

If the supplier doesn't reply within 48 hours, a reminder draft appears. After 72 hours of silence, an escalation flag goes up for human judgment.

---

## 6. How customer notifications get drafted

When a delivery date slips, the system drafts a notification email for the customer. The **tone of the email scales with how bad the delay is:**

| Delay | Tone | What the email looks like |
|---|---|---|
| < 3 days | Professional | Short, factual: "Date moved from X to Y." |
| 3-9 days | Empathetic | Acknowledges inconvenience, apologizes politely. |
| ≥ 10 days | **Severe** | Genuine personal apology, acknowledges customer impact, briefly explains why if the supplier told us a reason, commits to expediting where possible. |

If the supplier told us *why* they're late (machine breakdown, material shortage, rework, quality check), the customer notification includes a brief, customer-friendly explanation — without naming the supplier or revealing internal details.

---

## 7. What the tool will NOT do

The tool stays out of these areas — they belong to other teams or workflows:

- **Customer complaints** → handled by the **Complaints team** via Salesforce
- **Finance / Mahnung / dunning emails** → handled by **Accounts Receivable**
- **Technical clarifications / drawing questions** → handled by **Sales / Engineering**
- **Pricing or commercial decisions** → never the system
- **Sending an email without human approval** — never. Period.

When customer complaints / finance / general inquiries arrive, the system **logs them visibly** under "Blocked Actions" but doesn't create draft noise in your queue.

---

## 8. Where to find things

| You want to… | Go to… |
|---|---|
| Review drafts and approve/send | **/drafts** |
| Find a specific order | **/orders** → search or filter |
| See all activity for one customer order | **/orders/customer/[id]** |
| See why a draft was NOT created | **/automation** → Blocked Actions tab |
| Tune thresholds (outreach windows, tone, etc.) | **/automation** → Settings tab |
| Check when each automated job last ran | **/jobs** |
| Trigger a job manually | **/jobs** → click "Trigger" |
| Submit feedback or report a bug | The 💬 widget on every page |

:::warning
**If a specific order has zero drafts and you think it should have some**, check in this order:
1. Is the order in a state the tool ignores? (Cancelled, Rejected, Delivered)
2. Is there a Blocked Action explaining why?
3. Has the supplier already replied recently? (System waits before chasing again.)
4. Is it inside the outreach window? (EU = within 7 days, non-EU = within 21 days)

If none of these explain it, file a bug via the 💬 widget — engineering will trace it.
:::

---

## 9. How emails get classified

Suppliers send replies in many shapes. The AI buckets each one:

| Category | What it means | What the system does |
|---|---|---|
| **Shipped with tracking** | They shipped + gave a tracking number | Saves the tracking, drafts a thank-you |
| **Shipped without tracking** | They shipped, no tracking yet | Drafts a reply asking for the tracking number |
| **New delivery date** | They committed to a new arrival date | Updates the date, drafts an acknowledgment, may notify customer if delay is significant |
| **No delivery date** | Vague / question / partial info | Drafts a reply asking for the missing info |

It also extracts:
- Tracking numbers + which carrier
- Ship date vs arrival date (different transit math)
- Transport mode — truck (no tracking number expected) vs courier
- Delay reasons (used in customer notifications)

If the AI is less than 70% confident, it routes to a **manual_action** draft so a human can decide.

---

## 10. Key Salesforce concepts the system uses

You don't need to know SF deeply, but two concepts come up:

- **Production Order (`Order__c`, also called PO)** — the customer's order. One customer order can split into multiple supplier orders.
- **Supplier Order (`SupplierOrder__c`, called SO or FSO)** — one piece going to one supplier. Has its own date, status, and case history.

When the system says "PO-046403-1" that's a customer order. "SO-046403-1-2" is the second supplier order on that customer order.

The system also reads the SF-Flow auto-generated "Delivery Date Changed For SO-X" cases that fire when a supplier confirms a new date through the supplier portal.

---

## 11. How feedback shapes the system

The system has **shipped ~200 specific fixes** over the last month, almost all driven by Reject feedback. Examples:

| Your feedback | What changed |
|---|---|
| "Wrong recipient — supplier email went to a customer" | All outbound now validated against the SF case before send |
| "German suppliers irritated by 14-day-early outreach" | EU window narrowed to 7 days |
| "Customer needs a reason for repeated delays, not just a date" | Customer notifications now include AI-extracted delay reason |
| "Drafts created for cancelled / rejected orders" | All drafts blocked when SF status is truly terminal |
| "Complaint orders shouldn't trigger tracking drafts" | Complaint-sibling check added |
| "Already shipped on 09.04, but draft says delivery risk" | Stale-shipment heuristic skips orders shipped >14 days ago |

The faster you give feedback (with a one-line reason), the faster the system improves.

---

## 12. Quick glossary

| Term | Plain meaning |
|---|---|
| **Draft** | An email or task the system has prepared for human review |
| **PO** | Production Order — the customer's order |
| **SO / FSO** | Supplier Order — what one specific supplier is producing |
| **Phase A / B / C** | Internal naming: A = first outreach, B = reminder, C = customer notification |
| **Preview mode** | Drafts that exist but can't be sent yet (used during rollout testing) |
| **Blocked Action** | The system *would have* created a draft but a guard stopped it; visible under /automation |
| **EU vs non-EU** | Country group — affects shipping transit math and outreach timing |
| **Salesforce Case** | The thread on the supplier/customer side where emails live in SF |

---

## 13. Who to ask

| Question | Where to ask |
|---|---|
| The tool did something weird | 💬 feedback widget on the page (or `[e-mail]`) |
| I want to change a threshold or toggle | `/automation` → Settings (you can change it yourself) |
| Engineering question or feature request | `[e-mail]` |
| The whole system is down | Check `/api/v1/health` first; then ping engineering |

---

*Last updated: 2026-05-05. The system has 6 phases of architectural work shipped, ~200 fixes informed by user feedback, and continues to improve as you click that Reject button with a reason.*