periscope/docs/piano-pcb-review.md

# Piano — PCB review (controllo placement + routing)

Documento **solo di piano**. Non è un implementazione sprint e **non** è un auto-placer.

Prodotto: **Periscope Layout review** — esaminare un board KiCad già sbrogliato (o parzialmente sbrogliato) e dire *dove* placement e routing violano geometria + datasheet.

Contratto rispetto a [`docs/piano-implementazione.md`](piano-implementazione.md):

| | Schema (già in produzione) | PCB review (questo piano) | Placement F2 pack (fuori da questo piano) |
| --- | --- | --- | --- |
| Promessa | Lo schema rispetta il datasheet | Il rame e le posizioni **esistenti** rispettano datasheet + geometria | Proporre xy nuovi |
| Trigger | BOM + netlist / `.kicad_sch` | + `.kicad_pcb` | PCB + `layout_rules` numerici |
| Output | Finding pin/net, derating, review LLM | Finding mm / net / Z0 / skew / via EP, `rule_id` `PE-PLC*` / `PE-SI*` / `PE-LAY*` | `placement_pack.json` proposte |
| Job | `MODE=run` (`status`) | Job parallelo `MODE=pcb` (`pcb_status`) | già `MODE=placement` (`placement_status`) |

Senza `.kicad_pcb` il progetto resta un Periscope schema **completo**. Il report schema **non** si riempie di `PE-PLC` / `PE-SI`.

---

## 0. Postura: esame, non progettazione

### Placement = verifica

Si misura ciò che è **già** sul board:

- distanza footprint/pad (euclidea e shortest-path sui segmenti);
- layer (F.Cu vs B.Cu) vs `same_layer`;
- via nel courtyard del pad termico vs `min_via_count`;
- keepout: net estraneo nel courtyard;
- crystal: load cap vs pin XIN/XOUT con la stessa metrica.

Non si spostano footprint. Non si scrive `.kicad_pcb`. Non si usa `placement_pack` / `build_placement_pack` come obiettivo di questo piano.

`placement_check` (`backend/periscopex/placement_check.py`, `PE-PLC-001`…`004`) è già questa postura. Resta il nucleo placement del job PCB.

La pipeline Placement esistente (`POST …/placement/start`, `placement_plan.json`) è **topologia routing-first** (domini, satelliti, `role_hint`). Utile come contesto (“questo C è decoupling di U1”) ma **non** è auto-placement. F2 packing (`placement_pack.json`, collisioni, export pcbnew) resta **parcheggiato**.

### Routing = la stessa postura

Si misura ciò che è **già** in rame:

- lunghezza net / coppia / bus (somma segmenti, non folklore USB);
- intra-pair skew vs `layout_rules.kind=length_match` **solo se** c’è un mm nel datasheet (`si_check`, `PE-SI-001`);
- Z0 sulle tracce dove stackup + larghezza esistono (`impedance_traces.py` + ImpedanceFinder);
- mismatch pad PCB vs pin schema (net name su pad vs `DesignGraph.pin_net`);
- elenco tracce / bus per il report (inventario, poi check).

Non si sbroglia. Non si cambia larghezza. Non si inventano 3W, creepage IEC, o target 50 Ω se il datasheet/stackup non li danno.

### Datasheet compliance (layout)

Solo vincoli **strutturati** già estratti in `ComponentConstraints.layout_rules` (skill C4, `layout_rules.py`):

| `kind` | Check PCB | Skip se |
| --- | --- | --- |
| `decoupling_proximity` | distanza / path vs `max_distance_mm`; crystal stesso | `max_distance_mm` null |
| `thermal_via` | via in courtyard vs `min_via_count` | courtyard o count assenti |
| `keepout` | endpoint net estraneo in courtyard | courtyard assente |
| `length_match` | skew coppia vs `max_distance_mm` | mm assente |

Niente default 3 mm. Niente “foto del layout TI vs gerber”. Citazione: `source_page` sul finding, come oggi.

---

## 1. Come sta in parallelo alla pipeline schema

Oggi i check layout (`placement_check`, `si_check`) girano **dentro** la review schema (`backend/services/validation.py` → `_run_deterministic_checks`) se esiste `layout_graph.json`. Funziona, ma mescola due prodotti nello stesso `report.json` e nello stesso `status`.

Target:

```
                    ┌─ MODE=run        → status              → report.json (schema)
  Project files  ───┼─ MODE=placement  → placement_status    → placement_plan.json
                    └─ MODE=pcb        → pcb_status          → pcb_report.json
```

Stesso pattern job/stage/findings della Placement sibling, **non** un secondo auto-placer.

### Riuso obbligatorio (non reinventare)

| Pezzo | Path | Ruolo nel job PCB |
| --- | --- | --- |
| Workspace / SSE broker | `backend/services/pipeline.py` (`PipelineWorkspace`, `broker`) | Download upload, `layout_graph.json`, eventi |
| Job dispatch | `backend/services/job_runner.py`, `backend/pipeline_worker.py` | Nuovo `MODE=pcb` accanto a `run` / `regen` / `placement` |
| API sibling | `backend/routers/pipeline.py` (`placement/start|cancel|events`) | `pcb/start`, `pcb/cancel`, `pcb/events` |
| Meta progetto | `backend/services/projects.py` (`placement_status*`) | `pcb_status`, `pcb_state`, `pcb_execution_name`, `pcb_cancel_requested` |
| Parser board | `backend/periscopex/parsers_kicad_pcb.py` | `LayoutGraph` (footprint, pad net, segmenti, via, zone, stackup) |
| Grafo schema | `design_graph.json` / `build_graph(..., pcb_path=)` | Pin↔net; `capacitors_on_net`; CAD index |
| Placement verify | `placement_check.py` | PE-PLC-* |
| SI verify | `si_check.py` | PE-SI-001 |
| BOM/schema | `bom_match_check.py` | Resta **schema**. Sul PCB: analogo **pad-net match** (nuovo check piccolo, stesso schema `Finding`) |
| Cad bridge | `cad_bridge.py` (`target: pcb` per `PE-PLC`/`PE-SI`/`PE-LAY`) | Plugin pcbnew focus |
| Validation helpers | `assign_finding_ids`, fail-soft per check, `annotate_findings_cad` | IDs + CAD |
| Impedenza tracce | `impedance_traces.py`, `routers/impedance.py`, `impedance_nets.json` | Inventario Z0; finding solo se target numerico esiste |
| UI | `finding-card`, report filters, `types.ts` / `api.ts`, `pcb-upload.tsx`, pagine/hooks placement come stampo | Tab Layout + findings nel report |
| Test | `tests/test_kicad_pcb.py`, `test_placement_check.py`, `test_si_check.py`, `test_placement_pipeline.py` | Fixtures + job smoke |

### Contratto job (come Placement)

- **Non** tocca `ProjectMeta.status` dell’analisi schema.
- Soft-cancel: flag `pcb_cancel_requested` (come `placement_cancel_requested`).
- Mutex: non partire se analisi `queued|running` **o** placement `queued|running` **o** pcb già attivo (l’event log è condiviso e Placement fa `clear_history`).
- SSE: eventi `pcb_step_update` / `pcb_complete` / `pcb_error` / `pcb_cancelled`. Lo stream schema ignora `pcb_*` (come già ignora `placement_*`).
- Locale: `enqueue` con `proc_key=pcb:{id}`, `execution_name=local/pcb/{id}` (stesso trick di `local/placement/`).
- Heal zombie: `heal_if_pcb_stuck` speculare a `heal_if_placement_stuck` (evento terminale, o artefatto `pcb_report.json` se il worker è morto dopo la scrittura).
- Billing: job **free** (come placement). Nessun LLM in v1.

### Stages del job PCB (v1)

1. **`ensure_graph`** — riusa `design_graph.json`; se manca, `graph_build` da BOM+netlist (stesso helper Placement). Senza grafo: 400, non inventare connettività dal solo PCB.
2. **`parse_pcb`** — riusa `layout_graph.json` o `parse_kicad_pcb(uploads/pcb.kicad_pcb)` e upload. Fail → `pcb_status=error` (a differenza dello schema, qui il PCB è l’ingresso).
3. **`inventory`** — lista net con rame, lunghezze, coppie `_DP/_DM` `_P/_N`, bus omonimi, Z0 dove stackup+width ci sono. Artefatto `pcb_inventory.json` (leggibile in UI). Nessun finding da soli numeri.
4. **`checks`** — funzioni pure in `periscopex/` (fail-soft per check). Vedi §3.
5. **`write_report`** — `pcb_report.json` (`ValidationReport`), cad-bridge merge, IDs `PCB-{designator}-{001}` per non collidere con lo schema.

Senza datasheet / `layout_rules`: l’inventory c’è comunque; i finding datasheet-gated sono lista vuota, non errore.

---

## 2. Ingressi

| Ingresso | Dove | Obbligatorio v1 |
| --- | --- | --- |
| `.kicad_pcb` | `uploads/pcb.kicad_pcb`, `has_pcb` | Sì |
| Design graph | `design_graph.json` (da BOM+netlist / KiCad sch flatten) | Sì (per pin↔net e MPN) |
| Estrazioni IC | `extracted/` + library | Per `layout_rules` / pintable pin names |
| Datasheet PDF | library blobs | Solo per `source_page` in UI; i check v1 sono deterministici |
| Stackup nel PCB | `LayoutGraph.stackup` (εr, h, t, layer names) | Per Z0; skip se assente |
| `layout_rules` | JSON MPN, `KNOWN_KINDS` | Per PE-PLC / PE-SI; skip se mm/count null |

Non in v1: Gerber come ingresso, EasyEDA JSON, PADS dump come layout, zip gerarchico PCB (il board non è gerarchico).

Allineamento net: i nomi net del PCB devono combaciare con lo schema **dopo** flatten gerarchico (`U1.4` ↔ pad). Un mismatch è un finding (`PE-LAY-001`), non un crash.

---

## 3. Cosa elenca e cosa controlla questa stage

Due uscite distinte: **inventario** (sempre, se il parse riesce) e **findings** (solo regola + numero).

### 3.1 Inventario (report Layout, non finding)

Per ogni net con rame:

- nome, `NetType` dallo schema se noto;
- lunghezza mm (somma segmenti, come `si_check.net_length_mm`);
- layer usati, min/max width, n. via;
- coppia differenziale se suffisso noto;
- Z0 stimata se stackup+width (riuso `impedance_traces.analyze_where_needed` / `impedance_nets.json`);
- appartenenza a bus (prefisso comune: `D[0-7]`, `A[0-15]`, `USB_DP/DM`) — lunghezze affiancate, **senza** soglia inventata.

UI: tabella “Traces / buses” sulla pagina PCB o tab Layout. Serve a *vedere* il board prima dei finding.

### 3.2 Check deterministici (findings, stesso modello `Finding`)

Registrati in un unico `run_pcb_checks(graph, constraints_map, layout)` (nuovo wrapper sottile; **non** SDK LLM in `periscopex/`).

| ID | Source | Cosa | Gate |
| --- | --- | --- | --- |
| `PE-LAY-001` | nuovo `pcb_net_match` (specchio di `bom_match_check`) | Pad net ≠ pin net schema, stesso ref+pin | Pad ha `net` e lo schema ha `pin_net` |
| `PE-LAY-002` | stesso modulo | Ref in schema senza footprint PCB (o viceversa, skip `#PWR`) | Graph + footprints |
| `PE-PLC-001` | `placement_check` | Decoupling / crystal oltre `max_distance_mm` (path se esiste, senno euclidea) | regola + mm |
| `PE-PLC-002` | idem | Via termiche < `min_via_count` | courtyard + count |
| `PE-PLC-003` | idem | `same_layer: true` e cap sull’altro lato senza via sotto il pin | boolean regola + layer footprint |
| `PE-PLC-004` | idem | Keepout: net estraneo in courtyard | courtyard |
| `PE-SI-001` | `si_check` | Intra-pair skew > `length_match` mm | coppia nominale **e** mm datasheet |
| `PE-Z0-001` (fase 2) | da `impedance_traces` | Z0 fuori target | target in `layout_rules` **o** netclass KiCad esplicita; mai 50 Ω di default |

Campi finding (già sul modello): `rule_id`, `net`, `pins[]`, `source`, `cad_sheet` / `cad_uuid` se in `cad_index`, `status` ERROR/WARNING, `source_page` dalla regola.

Normalization: **downgrade-only** se un giorno si aggiunge un pass; v1 non alza severità.

### 3.3 Fuori dai finding (skip esplicito, log)

- 3W / crosstalk senza distanza datasheet o calcolatore.
- Creepage/clearance IEC 62368 senza V/mm nel datasheet.
- Isolation barrier / HV courtyard senza keepout HV.
- CPWG se il vendor ImpedanceFinder non lo dà.
- Length-match “USB spec” / 150 mil folklore.
- Confronto visivo application-circuit vs PCB.

Queste restano Wave G residue in `piano-implementazione.md`, non questo job.

---

## 4. UI

Gating: `hasPcb`. Senza PCB, nessun bottone “Run PCB review”, nessun finding layout nel report schema.

| Superficie | Comportamento |
| --- | --- |
| Project hub | Accanto a “Build placement plan”: **Run PCB review** (verify). Upload già `PcbUploadButton`. |
| `/project/[id]/pcb` | Stampo di `/placement`: stepper SSE (`ensure_graph` → `parse_pcb` → `inventory` → `checks` → `write_report`), cancel, errore, link al report. |
| Sidebar | Voce **Layout** (`/pcb` o `report?domain=layout`). Nested route = `forceDocument` come placement. |
| Report | `GET /report/{id}` **merge** `report.json` + `pcb_report.json`. Filtro URL `?domain=schema\|layout\|all`. Finding card: badge “Layout” + `rule_id` (`PE-PLC-001`) oltre “Automated check”. |
| Inventory | Tabella tracce/bus/Z0 sulla pagina PCB (dati `pcb_inventory.json` / `impedance_nets.json`). |
| Plugin | `periscope-findings.json` include finding `target: pcb` dopo il job PCB (cad-bridge già distingue prefissi). |

Commenti / review_states restano keyed by `finding_id` su `report.json` (o dict parallelo); il merge in GET non deve perdere commenti schema. IDs prefissati `PCB-` evitano collisioni `U3-001`.

Re-run schema **non** cancella `pcb_report.json`. Re-run PCB **non** tocca findings LLM.

---

## 5. Fasi

Ordine: non parallelizzare con auto-pack. Non mischiare changelog Core vs Layout.

### Fase 0 — Confine (doc + split)

- Questo documento = contratto.
- Togliere `placement_check` / `si_check` da `_run_deterministic_checks` della review schema (restano no-op senza layout; lo split evita PE-PLC nello schema).
- Eval harness schema (`eval_report.py`) continua a chiamarli con `layout=None` (no-op) **oppure** li sposta in eval PCB dedicato.

**Done when:** run schema senza PCB = zero `PE-PLC`/`PE-SI` nel report.

### Fase 1 — Job parallelo + inventory + check già esistenti (slice usabile)

- Meta `pcb_*`, `enqueue` `MODE=pcb`, router start/cancel/events, worker.
- Stages §1; artefatti `layout_graph.json`, `pcb_inventory.json`, `pcb_report.json`.
- Check: `pcb_net_match` + `check_placement` + `check_si`.
- UI: start, progress, merge findings nel report, filtro Layout, `rule_id` sulla card.
- Test: wrapper `run_pcb_checks` su fixture (decoupling 15 mm → `PE-PLC-001`; 1 mm → niente); pad net mismatch → `PE-LAY-001`; job busy helpers come `test_placement_pipeline.py`; pytest API start 400 senza PCB.

**Done when:** upload `.kicad_pcb` → start PCB → finding visibili nel report; schema invariato.

### Fase 2 — Inventario ricco (tracce, bus, Z0)

- Tabella lunghezze + coppie + bus.
- Z0 per net signal con stackup (già `impedance_traces`); finding `PE-Z0-001` **solo** con target numerico (regola o netclass).
- Collegare `impedance_nets.json` al job PCB (oggi è side-effect dello schema `graph_build`).

**Done when:** board con stackup mostra Z0 in UI; senza stackup, skip loggato, zero finding inventati.

### Fase 3 — Plugin + eval PCB

- Cad-bridge dopo `write_report`; click finding centra footprint in pcbnew (`plugins/kicad/periscope_plugin.py`).
- Golden keys su fixture (USB skew voluta → `PE-SI-001`; simple_project senza PCB → vuoto).
- Changelog Layout (voce distinta, non “un po’ di Periscope in più”).

### Fase 4 — Non fare (parcheggio)

- `placement_pack` / collisioni courtyard / export xy / muovere rame.
- Auto-place antenna in `.kicad_pcb`.
- 3W, creepage IEC, CPWG, isolation HV senza numero.
- LLM che “legge” il layout come review schema.
- Secondo ingresso Gerber/EasyEDA.

---

## 6. Fuori scope (esplicito)

- Auto-placement, packing mm, write-back pcbnew, “migliora il floorplan”.
- Autore di sbroglio / change width / length-tune.
- Simulazione SPICE / IBIS / EM / VSWR.
- Inventare millimetri, Ω, o V/mm.
- Plugin EasyEDA; parser JSON EasyEDA.
- Layout da `!PADS-POWERPCB`.
- Unire forzatamente job PCB nella run schema.
- Toccare ssh / keys / `sshd` (irrilevante a questo piano).

---

## 7. Come si misura il “done”

Fixture minima (non un USB inventato in produzione, ma un `.kicad_pcb` di test in `tests/`):

1. C di decoupling a 15 mm da VDD con regola 2 mm → `PE-PLC-001`.
2. Stesso C a 1 mm → nessun finding proximity.
3. Coppia `USB_DP`/`USB_DM` con skew > `length_match` → `PE-SI-001`.
4. Pad `U1.1` net `+3V3` vs schema `GND` → `PE-LAY-001`.
5. Progetto senza PCB: job PCB rifiutato; report schema pulito.

Niente LLM. Niente coordinate proposte.

---

## 8. Relazione col piano esistente

`piano-implementazione.md` Wave G (G0 ingest, G1 SI gated, G2 placement vs datasheet) è **questo** prodotto, riletto come job parallelo di **esame**.

La roadmap Placement F2 (pack v1/v2/export) **non** entra in queste fasi. `placement_check` resta verifica; `placement_pack` resta skeleton gated e non si estende qui.

Chats Cursor precedenti: nessuna decisione di “PCB error pipeline” come job; solo note RF (“auto-place rame nel PCB = dopo”). Questo piano è la decisione: **review**, non place.