ShipStation tracking pull, status tracking, dashboard rework

app/models.py

@@ -1,11 +1,11 @@
 """
 Database models.
 
-Order is intentionally source-agnostic: JIRA tickets, ShipStation
-orders, and Odoo sale orders all get normalized into this shape on the
-way in (see app/services/*). The `source` + `external_id` pair tells
-you where a row came from, and `raw_data` keeps the original payload
-in case a later feature needs a field we didn't think to pull out yet.
+One row per JIRA ticket. ShipStation is purely a label-generation step
+for these tickets (order numbers there match the JIRA ticket number 1:1,
+and it's not used for anything else), so it doesn't get its own rows -
+it enriches the matching row here with tracking_numbers instead. See
+app/workers.py for how that merge happens.
 """
 from __future__ import annotations
 
@@ -33,25 +33,30 @@ class Order(Base):
 
     id = Column(Integer, primary_key=True)
 
-    # Where this order came from and its ID in that system.
-    # e.g. source="jira", external_id="AR-1234"; source="shipstation", external_id="se-9988"
+    # "source" is kept for schema stability / possible future sources,
+    # but in practice this is always "jira" today - see module docstring.
     source = Column(String(32), nullable=False, index=True)
     external_id = Column(String(128), nullable=False, index=True)
 
-    # The AR-###### style ticket number. Present on both JIRA and
-    # ShipStation orders once the ticket number carries through - this is
-    # the field that lets the dashboard correlate the same real-world
-    # order across both sources.
+    # The AR-###### style ticket number - same as external_id for JIRA
+    # rows, kept as its own column since it's also how ShipStation
+    # tracking numbers get matched back to this row.
     ticket_number = Column(String(64), nullable=True, index=True)
 
-    # Signify Health / Oak Street Health / Unknown - derived from SKU
-    # prefix (JIRA) or store ID (ShipStation). See app/companies.py.
+    # Signify Health / Oak Street Health / Unknown - derived from the
+    # SKU prefix. See app/companies.py.
     company = Column(String(100), nullable=False, default="Unknown", index=True)
 
     # SKUs found on this order/ticket. A ticket can have several, but
     # per business rule they never mix companies on one ticket.
     skus = Column(JSON, nullable=True)
 
+    # Tracking numbers pulled from ShipStation and merged onto this
+    # ticket - e.g. [{"number": "782758401696", "carrier": "ups",
+    # "is_return": false}]. Populated by the "Pull Tracking Numbers"
+    # action, separately from the JIRA import.
+    tracking_numbers = Column(JSON, nullable=True)
+
     summary = Column(String(500), nullable=False, default="")
     status = Column(String(100), nullable=False, default="")
 
@@ -60,11 +65,11 @@ class Order(Base):
     # When we pulled it into this app
     imported_at = Column(DateTime, nullable=False, default=dt.datetime.utcnow)
 
-    # Downstream pipeline flags - useful once ShipStation/Odoo steps exist
+    # Downstream pipeline flags - useful once Odoo export is fully wired up
     fulfilled = Column(Boolean, nullable=False, default=False)
 
-    # Full original payload from the source system, for anything not
-    # modeled explicitly above.
+    # Full original payload from JIRA, for anything not modeled explicitly
+    # above.
     raw_data = Column(JSON, nullable=True)
 
     def __repr__(self) -> str:  # pragma: no cover - debugging aid