Add reversible Maximo/WINC machine-adoption import

Machine data arrives as a Maximo asset export (validated against the WINC
site) that must update existing machines in place, not create canonical
per-table rows, so it does not fit the ShopDB-native/Azure/Thor CSV adapter
path. Bulk edits to live machines also need an escape hatch, so the whole
commit is journaled and can be undone as one batch.

Add a dedicated dry-run analyzer, approval packet, resolver/suggest helpers,
and a reversible writer/undo backed by a new importbatches/importjournalentries
schema (with migration). Expose preview/commit/batches/undo settings routes and
a matching frontend source card and panel, and surface the batch/journal
contract through shopdb.api for plugins.

shopdb/core/services/wincimport.py

@@ -0,0 +1,138 @@
+"""WINC machine-adoption import service (preview / commit / undo / list).
+
+Web-facing wrapper over the validated WINC CLI helpers. The CLI in
+scripts/site_imports/winc drives the same analyzer, writer, and journal; this
+module adapts them to a Flask request: it works on the request-scoped
+db.session connection (so the route owns the transaction and commit) and returns
+plain JSON-serialisable dicts for the API.
+
+WINC is NOT a source adapter like Azure/Thor. It never creates assets - it
+updates existing machines only, requires acknowledgment before creating business
+units, and records every change to the reversible import journal. That contract
+lives here and in the writer, not in the generic canonical-CSV importer.
+"""
+
+from shopdb.extensions import db
+from scripts.site_imports import journal
+from scripts.site_imports.approval import build_packet
+from scripts.site_imports.winc import writer as winc_writer
+from scripts.site_imports.winc.dry_run import analyze_rows, parse_export_text
+
+
+class WincImportError(Exception):
+    """An uploaded export could not be analyzed or applied as WINC."""
+
+
+def _connection():
+    return db.session.connection()
+
+
+def _plan_and_packet(export_text):
+    """Parse an uploaded export, build the plan and the approval packet."""
+    rows = parse_export_text(export_text)
+    if not rows:
+        raise WincImportError('the uploaded file had no rows')
+    if 'assetnum' not in rows[0]:
+        raise WincImportError(
+            'this does not look like a WINC asset export (no assetnum column)')
+
+    plan, summary, _lookups = analyze_rows(_connection(), rows)
+    packet = build_packet('winc-machine-adoption', plan, summary,
+                          winc_writer._PACKET_GROUPS)
+    return plan, summary, packet
+
+
+def _report(summary, packet):
+    """Shape the packet + summary into the JSON the UI renders."""
+    return {
+        'kind': packet['kind'],
+        'planhash': packet['planhash'],
+        'rowcount': packet['rowcount'],
+        'summary': dict(summary),
+        'needscreate': {group: dict(items)
+                        for group, items in packet.get('needscreate', {}).items()},
+        'unresolved': {group: dict(items)
+                       for group, items in packet.get('unresolved', {}).items()},
+        'blocking': packet.get('blocking', False),
+    }
+
+
+def preview(export_text):
+    """Read-only: analyze the export and return the report the UI shows.
+
+    Writes nothing. The whole point is to surface what a commit WOULD do -
+    counts, the business units it would create (needs acknowledgment), and any
+    unresolved values that block the import.
+    """
+    _plan, summary, packet = _plan_and_packet(export_text)
+    report = _report(summary, packet)
+    report['committed'] = False
+    return report
+
+
+def commit(export_text, acknowledge=None, createdby=None):
+    """Apply the plan reversibly inside the request transaction.
+
+    Rebuilds the plan from the same upload, re-checks it against a freshly built
+    packet (drift, blocking, acknowledgment) and writes through the journal. The
+    caller owns the commit/rollback of db.session. Returns the report plus the
+    batchid on success.
+
+    Raises WincImportError (mapped to a 400 by the route) when the plan is
+    blocking or a needs-create group was not acknowledged.
+    """
+    plan, summary, packet = _plan_and_packet(export_text)
+    try:
+        batchid = winc_writer.apply_plan(
+            _connection(), plan, packet,
+            acknowledge=acknowledge, createdby=createdby)
+    except winc_writer.WriterError as exc:
+        raise WincImportError(str(exc))
+
+    report = _report(summary, packet)
+    report['committed'] = True
+    report['batchid'] = batchid
+    return report
+
+
+def undo(batchid):
+    """Reverse an applied batch. Caller owns the transaction. Returns a dict."""
+    result = journal.undo_batch(_connection(), batchid,
+                                references=winc_writer._UNDO_REFERENCES)
+    return {
+        'batchid': result.batchid,
+        'reverted': result.reverted,
+        'conflicts': [
+            {'operation': conflict.operation, 'table': conflict.table,
+             'targetid': conflict.targetid, 'column': conflict.column,
+             'reason': conflict.reason}
+            for conflict in result.conflicts
+        ],
+    }
+
+
+def list_batches(limit=50):
+    """Applied/undone WINC batches, newest first, for the UI's undo list."""
+    from sqlalchemy import text
+
+    def _iso(value):
+        # PyMySQL hands back datetime objects; SQLite (tests) hands back the
+        # stored ISO string. Normalise both to an ISO string with a Z suffix.
+        if value is None:
+            return None
+        if hasattr(value, 'isoformat'):
+            return value.isoformat() + 'Z'
+        return str(value)
+
+    rows = _connection().execute(text(
+        'SELECT batchid, kind, rowcount, createdat, createdby, status, '
+        'undoneat FROM importbatches WHERE kind = :kind '
+        'ORDER BY createdat DESC LIMIT :limit'),
+        {'kind': 'winc-machine-adoption', 'limit': limit}).fetchall()
+    return [
+        {'batchid': r[0], 'kind': r[1], 'rowcount': r[2],
+         'createdat': _iso(r[3]),
+         'createdby': r[4], 'status': r[5],
+         'undoneat': _iso(r[6])}
+        for r in rows
+    ]