Cutsheet trace mode and mismatch alerts
Lint / Python (flake8) (push) Successful in 1m8s
Security / Python Security (bandit) (push) Successful in 56s
Test / Python Tests (pytest) (push) Successful in 43s
Lint / Python (flake8) (pull_request) Successful in 50s
Lint / JS (eslint) (pull_request) Successful in 30s
Lint / Notify on failure (pull_request) Skipped
Lint / Deploy (pull_request) Skipped
Security / Python Security (bandit) (pull_request) Successful in 55s
Test / Python Tests (pytest) (pull_request) Successful in 50s
Lint / JS (eslint) (push) Successful in 16m17s
Lint / Notify on failure (push) Skipped
Lint / Deploy (push) Skipped

Trace a cord: pick a panel port, press Start, and unplug the cord at the
panel. The page polls a new admin-only endpoint that reads every switch
port's state from UniFi (cached 2 s), shows the one port that dropped
with a button to record the cable, and confirms when it's plugged back
in. Several ports dropping at once, or none within 3 minutes, is
explained rather than guessed at.

Mismatch alerts: the monitor runs the cutsheet check every poll. Each
mismatched installed run (wrong neighbor, no link, missing port, port
conflict) keeps one cable_mismatch event on its switch, resolved when
fixed, and opens a P4 ticket after cutsheet.mismatch_ticket_hours
(default 24, 0 never). Suppressing the switch or port stops the ticket.

Also fixes buttons with the hidden attribute still showing, which left a
Delete button on the new-cable form.

Closes #12

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
jaredandClaude Opus 5.5 committed 2026-11-10 16:54:57 -05:00
1 parent cd602fdacf
commit 86aa29b378
11 files changed
+446 -1

No files matched your search

+137
View File
@@ -329,6 +329,7 @@ function render() {
renderItems();
renderHistory();
renderDatalists();
renderTracePanels();
}
async function load() {
@@ -500,6 +501,136 @@ async function importCsv(e, dryRun) {
await load();
}
// ── Trace mode ──────────────────────────────────────────────────────────
// Snapshot which switch ports are up, then watch for the one that drops when a
// cord is unplugged at the panel. UniFi takes a few seconds to notice.
const TRACE_POLL_MS = 3000;
const TRACE_TIMEOUT_MS = 180000;
let _trace = null;
function renderTracePanels() {
const select = document.getElementById('cs-trace-panel');
if (!select) return;
const panels = _cs.items.filter(i => i.kind === 'patch_panel').sort((a, b) => natural(a.name, b.name));
const keep = select.value;
select.innerHTML = panels.map(p => `<option value="${esc(p.name)}">${esc(p.name)}</option>`).join('');
if (panels.some(p => p.name === keep)) select.value = keep;
document.querySelector('[data-action="trace-start"]').disabled = !panels.length || !!_trace;
if (!panels.length) traceStatus('Add a patch panel first.');
}
function traceStatus(html) {
const el = document.getElementById('cs-trace-status');
if (el) el.innerHTML = html;
}
function portKey(sw, idx) { return JSON.stringify([sw, String(idx)]); }
function upPorts(switches) {
const up = new Set();
for (const [sw, ports] of Object.entries(switches || {})) {
for (const [idx, p] of Object.entries(ports)) if (p.up) up.add(portKey(sw, idx));
}
return up;
}
function traceButtons(running) {
document.querySelector('[data-action="trace-start"]').hidden = running;
document.querySelector('[data-action="trace-stop"]').hidden = !running;
}
function stopTrace() {
if (_trace && _trace.timer) clearTimeout(_trace.timer);
_trace = null;
traceButtons(false);
renderTracePanels();
}
async function startTrace() {
const panel = document.getElementById('cs-trace-panel').value;
const port = String(parseInt(document.getElementById('cs-trace-port').value, 10) || '');
const item = itemByName(panel);
if (!item || !port || Number(port) < 1 || Number(port) > (item.port_count || 0)) {
traceStatus(`<span class="val-crit">Choose a port between 1 and ${esc(item ? item.port_count : '?')}.</span>`);
return;
}
traceButtons(true);
traceStatus('Reading switch ports…');
let live;
try {
live = (await lt.api.get('/api/cutsheet/live-ports')).switches;
} catch (err) {
traceStatus(`<span class="val-crit">${esc(err.message)}</span>`);
traceButtons(false);
return;
}
_trace = { panel, port, baseline: upPorts(live), started: Date.now(), found: null, timer: null };
traceStatus(`Ready. <b>Unplug the cord from ${esc(panel)} port ${esc(port)} now.</b>
Watching ${_trace.baseline.size} linked switch ports… UniFi can take up to about 30 seconds to notice.`);
_trace.timer = setTimeout(pollTrace, TRACE_POLL_MS);
}
async function pollTrace() {
const t = _trace;
if (!t) return;
let live;
try {
live = (await lt.api.get('/api/cutsheet/live-ports')).switches;
} catch (err) {
if (_trace === t) t.timer = setTimeout(pollTrace, TRACE_POLL_MS);
return;
}
if (_trace !== t) return;
const up = upPorts(live);
if (t.found) {
if (up.has(t.found.key)) {
showTraceResult(t, true);
stopTrace();
} else {
t.timer = setTimeout(pollTrace, TRACE_POLL_MS);
}
return;
}
const dropped = [...t.baseline].filter(k => !up.has(k)).map(k => JSON.parse(k));
if (dropped.length === 1) {
const [sw, idx] = dropped[0];
t.found = { key: portKey(sw, idx), sw, idx, name: ((live[sw] || {})[idx] || {}).name || '' };
showTraceResult(t, false);
t.timer = setTimeout(pollTrace, TRACE_POLL_MS);
} else if (dropped.length > 1) {
traceStatus(`<span class="val-warn">Several ports dropped at once, so the cord can't be told apart:</span>
${dropped.map(([sw, idx]) => `${esc(sw)} port ${esc(idx)}`).join(', ')}. Plug everything back in and try again.`);
stopTrace();
} else if (Date.now() - t.started > TRACE_TIMEOUT_MS) {
traceStatus(`No switch port dropped in 3 minutes. If nothing is plugged in at the far end of
${esc(t.panel)} port ${esc(t.port)}, its switch port was never linked; trace that one by hand.`);
stopTrace();
} else {
t.timer = setTimeout(pollTrace, TRACE_POLL_MS);
}
}
function showTraceResult(t, replugged) {
const f = t.found;
const existing = cableAt(f.sw, f.idx, '');
const panelCable = cableAt(t.panel, t.port, 'front');
let action;
if (existing && panelCable && existing.id === panelCable.id) {
action = `<span class="val-good">Matches ${esc(existing.label || 'the cutsheet')}.</span>`;
} else if (existing) {
action = `That switch port is documented as <a class="cs-id" href="#cable-${esc(existing.id)}">${esc(existing.label || 'an unlabeled cable')}</a>
to ${esc(existing.a_device === f.sw ? existing.b_text : existing.a_text)}.
<button type="button" class="lt-btn lt-btn-secondary lt-btn-sm" data-action="edit-cable" data-id="${esc(existing.id)}">Edit it</button>`;
} else {
action = `<button type="button" class="lt-btn lt-btn-primary lt-btn-sm" data-action="trace-record"
data-sw="${esc(f.sw)}" data-idx="${esc(f.idx)}" data-panel="${esc(t.panel)}" data-port="${esc(t.port)}">Record cable</button>`;
}
traceStatus(`
<div class="cs-trace-found">${esc(t.panel)} port ${esc(t.port)} → <b>${esc(f.sw)} port ${esc(f.idx)}</b>${f.name ? ` (${esc(f.name)})` : ''}</div>
<div>${action}</div>
<div class="cs-hint">${replugged ? '<span class="val-good">Plugged back in, link is up again.</span>' : 'Plug the cord back in now.'}</div>`);
}
// ── Wiring ──────────────────────────────────────────────────────────────
document.addEventListener('click', e => {
const btn = e.target.closest('[data-action]');
@@ -511,6 +642,12 @@ document.addEventListener('click', e => {
else if (action === 'edit-item') openItem(_cs.items.find(i => String(i.id) === btn.dataset.id));
else if (action === 'edit-port-label') openPortLabel(btn.dataset.item, btn.dataset.port);
else if (action === 'print-labels') printLabels();
else if (action === 'trace-start') startTrace();
else if (action === 'trace-stop') { stopTrace(); traceStatus('Stopped.'); }
else if (action === 'trace-record') {
openCable(null, { a_device: btn.dataset.sw, a_port: btn.dataset.idx, b_device: btn.dataset.panel,
b_port: btn.dataset.port, b_side: 'front' });
}
else if (action === 'use-next-label') document.getElementById('cs-label').value = _cs.next_label;
else if (action === 'toggle-suggestions') { _showAllSuggestions = !_showAllSuggestions; renderSuggestions(); }
else if (action === 'import-check') importCsv(null, true);