periscope/docs/piano-implementazione.md

# Piano di implementazione — Pinscope

Documento di lavoro **prima dello sviluppo**. La lista dell’utente è il minimo; sotto c’è anche ciò che serve perché quella lista non resti un insieme di moduli scollegati.

**Questo piano copre due prodotti.** Pinscope originale resta il primo. Layout/plugin/placement mm sono il secondo. Non mescolare i changelog né vendere il secondo come “un po’ di Pinscope in più”.

Stato del codice di riferimento: branch `cursor/deepseek-71c5` (post DeepSeek V4.1, costi USD, replace BOM/netlist, parser KiCad, fingerprint review).

---

## 0. Due prodotti (stesso repo, due promesse)

| | **Pinscope** (oggi + wave A–B, C schema, F/H leggere) | **Pinscope Layout** (wave D parziale, G, C4+G2, plugin pcbnew) |
| --- | --- | --- |
| Promessa | Lo schema rispetta il datasheet | Il rame rispetta datasheet + geometria |
| File | BOM, netlist, `.kicad_sch` gerarchico | + `.kicad_pcb` |
| Output | Finding su pin/net, derating, power tree | Distanze mm, 3W, creepage, skew, via EP |
| Utente | Chi chiude lo schema | Chi sbroglia |

Farli nello stesso codebase (`pinscopex` + `LayoutGraph`) è ragionevole. Farli **nella stessa run obbligatoria** no: senza PCB il progetto deve restare un Pinscope completo, non “incompleto perché manca il gerber”.

Nome in UI: tab **Layout** o prodotto “Layout checks” gated dal file `.kicad_pcb`. Il report schema non deve riempirsi di `PS-PLC` se il PCB non c’è.

Non serve un fork oggi. Serve disciplina: ogni PR dichiara se è Core o Layout.

---

## 0. Contratto di prodotto (non negoziabile)

Pinscope oggi è un **validatore di schema**: BOM + netlist → grafo bipartito → check deterministici + review LLM con citazione datasheet. Non legge il PCB.

Molti punti della lista (larghezza traccia, 3W, creepage, CPW clearance, length matching) **non esistono senza geometria**. Il piano li tiene, ma li mette **dopo** un ingest layout. Se li si forza sullo schema si producono finding inventati.

### Ingresso ufficiale: progetto KiCad (non EasyEDA)

Coppia da chiedere all’utente (e da salvare insieme):

| File | Ruolo |
| --- | --- |
| **Root `.kicad_sch`** (+ fogli figli) | Connettività, ref, uuid simbolo/pin, MPN nei property |
| **`.kicad_pcb`** | Rame, net, coppie, courtyard, stackup |

BOM CSV resta utile se i property MPN nello schema sono vuoti; se lo schema è completo, la BOM è opzionale.

**EasyEDA è fuori scope.** Niente plugin, niente parser JSON EasyEDA, niente DRC sull’editor cloud. Chi arriva da EasyEDA resta sul percorso già documentato (export PADS), senza lavoro nuovo.

**Gerber** non è l’ingresso primario: con `.kicad_pcb` i net ci sono già. I Gerber restano un eventuale piano B, non lo sprint 1 del layout.

### Schema gerarchico (più file) — attenzione

Oggi `parse_kicad_sch` legge **un solo foglio**. I `(sheet …)` che puntano ad altri `.kicad_sch` **non vengono seguiti**. L’errore attuale chiede di esportare la netlist.

Da fare (Wave A1), in ordine:

1. Upload: cartella progetto o zip, **oppure** il `.kicad_pro` + root schematic. Non un solo foglio figlio.
2. Dal root: camminare ogni `(sheet (property "Sheetfile" "power.kicad_sch") …)` (KiCad 6–10: `Sheetfile` / path relativo al foglio padre).
3. Path traversal: solo file sotto la root del progetto; rifiutare `../`.
4. Unire la connettività:
   - **local label** restano nel foglio;
   - **hierarchical_label** sul figlio ↔ **sheet pin** sul padre (stesso nome);
   - **global_label** e power symbol (`#PWR`) sono globali su tutto il progetto.
5. Path gerarchico KiCad (`/power/U1` vs `U1`): normalizzare i **Reference** come li vede il PCB (di solito già unici; se duplicati, è un errore dello schema).
6. Uuid: `(uuid …)` su symbol e pin, più `sheet` uuid, per il plugin (pan-and-zoom sul foglio giusto).
7. Fixture di test: root + 2 figli (alimentazione + analog), label gerarchiche su un net, power flag GND condiviso. Deve coincidere col netlist XML esportato da KiCad 9.

**Done when:** progetto a 3 fogli senza export netlist produce gli stessi `(ref, pin, net)` del file `*.xml` di KiCad.

`.kicad_pcb` è un file solo (il board non è gerarchico come lo schema). I net name nel PCB devono matchare i net risolti dallo schema dopo il flatten gerarchico.

Regole:

1. Ogni nuovo check è una funzione pura in `backend/pinscopex/` che legge `DesignGraph` (+ opzionale layout). Niente SDK LLM dentro `pinscopex/`.
2. I finding usano lo stesso schema (`Finding` in `models.py` / `frontend/src/lib/types.ts`). Campo `source` già distingue check automatici vs review.
3. Finding normalization resta **downgrade-only**.
4. Libreria condivisa: MPN exact-match. Niente fuzzy sul die.
5. Plugin CAD **consumano** il report; non duplicano la pipeline.

### Estensione schema finding (fare per prima, una volta)

Oggi: `designator`, `mpn`, `aspect`, `finding`, `why`, `status`, `source_page`, `recommendation`, `source`.

Aggiungere (backward compatible):

| Campo | Serve a |
| --- | --- |
| `net` | Telemetry CAD, filtri, SI |
| `pins[]` | Pan-and-zoom su U1.4 |
| `rule_id` | Plugin DRC (`PS-DEC-001`) |
| `cad_sheet` / `cad_uuid` | Sync plugin KiCad |
| `variant` | DNP / ECO |
| `severity_calibrated` | già implicito; non alzare in post |

Passi:

1. Estendere `Finding` in `backend/pinscopex/models.py` e `frontend/src/lib/types.ts`.
2. Aggiornare `assign_finding_ids`, export Excel, report UI (campi opzionali nascosti se null).
3. Test su `simple_project/` che i check esistenti ancora serializzano.

**Done when:** un finding di decoupling ha `rule_id` + `pins` e il report non rompe i finding LLM vecchi.

---

## Mappa lista ↔ codice attuale

| Blocco utente | Già c’è | Buco |
| --- | --- | --- |
| 1 Plugin / telemetry / BOM match | Parser KiCad XML/sexp/`.kicad_sch` **singolo foglio**; wizard BOM | Hierarchie multi-file; uuid; plugin; **EasyEDA fuori scope** |
| 2 Datasheet / errata / OCR blocchi | Pintable+abs-max, PDF text+vision, excerpt per topic, quote_verify | Nessun RAG vendor; niente errata; vision non estrae clamp/ESD dal block diagram in schema strutturato |
| 3 Impedenze / stackup | — | Motore assente; niente PCB |
| 4 Filtri | Review LLM può parlarne | Nessun matcher topologico, niente \(f_c\) |
| 5 Capacità PI | Decoupling check **sulla net**; derating V | No DC bias; ESR/ESL; Cin/Cout; **niente distanza cap↔pin sul PCB** |
| 6 Elettrico | Pin mux; I2C/reset pull-up; power tree UI; LED current | Sequencing assente; pull-up non dimensionati (solo presenza); drop IR assente |
| 7 RF | Review “ruolo parte” / bias-T | Nessun matching 50 Ω, niente clearance |
| 8 HV / isolation | — | Serve layout + profilo normativo |
| 9 Termico | Excerpt topic thermal | Nessun \(T_j\), niente P=I²R resistori |
| 10 SI / DNP | Fingerprint skip IC; skipped/not_reviewed | DNP non è un modello; niente length/crosstalk |
| 11 Lifecycle | DigiKey/LCSC/Mouser per datasheet e passivi | Nessun EOL/NRND/RoHS in report |
| 13 Placement da datasheet | Review può citare “place close to pin”; vision su application pages | Nessuna misura mm sul `.kicad_pcb`; nessuna struttura `layout_rules` estratta |

---

## Extra obbligatori (non nella lista, ma bloccanti)

Senza questi i moduli 1–12 non si misurano e i plugin mentono.

**E0. Eval harness.** Golden findings su `simple_project/` + 1–2 board interni. Precision/recall, % Unverified, citation hit-rate (`quote_verify`). Ogni check nuovo deve aggiungere fixture.

**E1. KiCad gerarchico GA.** Obbligatorio. Vedi “Schema gerarchico” sopra. Senza flatten dei fogli il plugin e il `.kicad_pcb` non allineano i net.

**E2. Protocollo plugin KiCad** (`pinscope-cad-bridge` JSON). Un file per progetto:

```json
{
  "version": 1,
  "project_id": "...",
  "findings": [
    {
      "rule_id": "PS-MUX-001",
      "ref": "U3",
      "pins": ["12"],
      "sheet": "...",
      "uuid": "...",
      "severity": "error",
      "message": "...",
      "url": "https://pinscope.../report?finding=U3-001"
    }
  ]
}
```

Un solo adapter: **KiCad 9/10**. Niente secondo plugin EasyEDA.


**E3. Smoke DeepSeek V4.1** su `simple_project` (vision + finding count vs run precedente). Già in coda P0.

---

## Wave A — Fondamenta CAD e finding (sblocca 1 e 6)

Obiettivo: schema KiCad fidato, finding indirizzabili, sync unidirezionale.

### A1. KiCad nativo “GA” (schema gerarchico)

Passi: quelli in “Schema gerarchico (più file)” + file-guide riscritta (niente “esporta PADS da KiCad” come percorso principale) + `cad_index.json` (ref → uuid → sheetfile).

**Done when:** fixture a più fogli = netlist XML KiCad; upload zip/progetto senza chiedere l’export.

### A3. Bridge KiCad (punto 1)

Passi:

1. Pacchetto `plugins/kicad/` (action plugin Python, KiCad 9/10).
2. `pinscope-findings.json` dal report (E2).
3. Marcatori / focus `uuid` su **eeschema** (foglio figlio corretto) e, per finding layout, su **pcbnew**.
4. Pan-and-zoom: `FocusOnItem` / select symbol; se l’API 10 differisce, adapter sottile.

**Done when:** clic su finding centra U3 sul foglio `power.kicad_sch`, non sul root vuoto.

EasyEDA: **non si fa.**

### A2. BOM-to-schematic matching (punto 1)

Non è uno script a parte: è il grafo.

Passi:

1. Da campi KiCad (`MPN`, `mpn`, `PN`, `lcsc`) già letti in `parsers_kicad.py` / `graph.py`.
2. Tabella conflitti: ref in schema senza MPN, MPN in BOM senza ref, mismatch Value.
3. Finding `source=bom_match` con `rule_id=PS-BOM-001`.
4. UI wizard: riga rossa nel matching, non solo colonne.

**Done when:** U1 in schema e U1 in BOM con MPN diversi → ERROR citabile.

---

## Wave B — Check deterministici schema (sblocca 4, 5, 6, 9, 10 DNP)

Obiettivo: meno LLM, più numeri. Ogni item = modulo `pinscopex` + test su grafo sintetico + riga in eval.

### B1. Power tree & drop (6)

Passi:

1. Riuse UI power tree esistente.
2. Per ogni IC: somma IQ + load stimato da specs se c’è; confronta con `Iout_max` LDO/Buck se estratto.
3. IR drop **solo se** esiste Rseries esplicito (shunt/ferrite) — niente stima di pista.
4. Finding `PS-PWR-001` margin fail.

### B2. Sequencing (6)

Passi:

1. Estrarre da datasheet (skill specs o tabella) `power_sequence` se presente; altrimenti skip.
2. Sul grafo: enable pin, RC delay, PG (power good) concatenati.
3. WARNING se sequenza dichiarata e PG non collega l’enable del rail successivo; niente invenzione di millisecondi.

### B3. Pull-up dimensionamento (6)

Passi:

1. Estendere `check_i2c_pullups`: presenza **e** valore vs Vrail e Cf (formula NXP UM10204, bound largo).
2. Reset: stesso, più pull-down vietato se datasheet dice active-low con pull-up interno assente.

### B4. Mux (6)

Già `pin_mux_check.py`. Passi residui: coprire SPI/UART con gli stessi token; test su MSPM0 del `simple_project`.

### B5. Decoupling audit (5)

Già `check_supply_decoupling`. Passi:

1. Distinguere Cin LDO vs Cout (pin IN/OUT dal pintable, non solo VDD).
2. Contare valore se specs passive ci sono (100 nF vs 10 µF) come WARNING non ERROR se il vendor non è esplicito.

### B6. Derating DC bias (5)

Passi:

1. Tabella empirica C0G/X7R/X5R (loss % vs V/Vrated) in `derating.py` — etichettare “stima”, non misura.
2. UI derating: colonna C_eff.
3. Non spacciare per curva Murata del lotto.

### B7. ESR/ESL parallelo (5)

Passi:

1. Modello grezzo: C + ESL package (0402/0603 lookup) + ESR da specs se c’è.
2. Z(f) somma parallelo 10µF+100nF; confronta con f_sw buck se nota.
3. Senza f_sw: INFO “copertura HF dipende da 100nF vicino al pin” senza fingere un target Ω.

### B8. Filtri (4)

Passi:

1. Matcher topologico sul grafo: RC serie-shunt, LC, ferrite+C, π (C-L-C), T (L-C-L).
2. \(f_c\) per RC (`1/2πRC`) e LC (`1/2π√LC`); Pi/T solo se L e C noti.
3. Confronto con `adc_sample_rate` / `data_rate` **solo se** in specs IC.
4. Insertion loss: WARNING se ferrite DCR alta su rail ADC analog (soglia da datasheet o skip).

### B9. Termico schema (9)

Passi:

1. \(P \approx I_{load} \times (Vin-Vout)\) per LDO se I e V noti; \(T_j \approx T_a + P \theta_{JA}\) con \(T_a=25\) default e campo UI.
2. Resistori: \(P=I^2R\) se I dal LED check o da shunt + V; vs `power_rating_w`.
3. Senza θJA: non inventare; INFO “manca theta_ja”.

### B10. DNP / varianti (10)

Passi:

1. Campo BOM `DNP` / `fitted` / `variant`.
2. Grafo per variante: pin Enable senza pull e senza driver → ERROR.
3. Non è layout.

---

## Wave C — Datasheet intelligence (punto 2)

Restare su DeepSeek Flash vision; niente secondo vendor di default.

### C1. Parsing adattivo (già in parte)

Passi:

1. Eval pintable su 10 PDF: TI, STM, NXP, Espressif, Winbond, GigaDevice, Holtek, Silergy, 3 PEAK.
2. Dove fallisce: skill `extract-pintable` + pagine vision (già keyword). Non RAG vettoriale finché l’eval non lo chiede.
3. Se serve RAG: chunk per pagina in libreria, retrieval per pin/abs-max — **dopo** C1 eval.

### C2. Errata

Passi:

1. Non scraping indiscriminato (TOS, HTML instabile).
2. Catalogo URL noti (TI `lit/er`, STM `errata`, Microchip).
3. DeepSeek `web_search` **opzionale** gated, citazione obbligatoria, stesso `quote_verify`.
4. Finding `PS-ERRATA-001` se il workaround (pull-up, bond-out) non è nello schema.

**Done when:** un MPN con errata nota in fixture produce finding; vendor senza URL → skip silenzioso loggato.

### C3. OCR / vision block diagram (2)

Passi:

1. Non un modello CV a parte: riusare pagine “block diagram” già in `_PAGE_KEYWORDS`.
2. Tool extraction: `internal_features: {esd_clamp_pins[], pullup_pins[], analog_switch[]}`.
3. Check: pin dichiarato open-drain senza pull visibile.

### C4. Layout rules dal datasheet (placement proposto)

La pagina “Typical application / PCB layout” non è solo uno schema: spesso dice *quanto vicino*, *quanti via*, *da che lato del package*. Va estratto in **struttura**, non lasciato in prosa al reviewer.

Skill o estensione specs (libreria per MPN, versionata come il pintable):

```json
{
  "layout_rules": [
    {
      "kind": "decoupling_proximity",
      "pin": "VDD",
      "cap_value_hint": "100nF",
      "max_distance_mm": 2.0,
      "same_layer": true,
      "source_page": 14
    },
    {
      "kind": "thermal_via",
      "pin": "EP",
      "min_via_count": 4
    },
    {
      "kind": "keepout",
      "net_class": "analog",
      "note": "no digital return under analog pin"
    }
  ]
}
```

Passi:

1. Pagine già keyword-matched (`application`, `layout`, `decoupling`, `PCB`). Vision obbligatoria (disegni).
2. `validate.py` sulla lista: `kind` enum chiuso; distanze solo se il testo/figura ha un numero; altrimenti `max_distance_mm` null e il check G2 usa una default **dichiarata** (es. 3 mm) con severity WARNING.
3. Citazione `source_page` + quote_verify sul testo se c’è (“place within 2 mm”).
4. Non inventare una land pattern JEDEC se il PDF non la dà.

**Done when:** MSPM0 o LDO del `simple_project` ha almeno una `decoupling_proximity` in library JSON, o skip esplicito `layout_rules: []` con log.

---

---

## Wave D — Impedenza analitica (punto 3) *senza* PCB

Motore **standalone**, stile calcolatrice. I vincoli CAD sono export, non verità sul board.

### D1. Motore Wheeler/Schneider

Passi:

1. `pinscopex/impedance.py`: microstrip, stripline, coupled diff, CPW — formule documentate + test numerici vs 3 valori ImpedanceFinder.
2. Input: `h`, `er`, `t`, `w`, `s`, `target_z`.
3. UI tab progetto “Impedance” (non LLM).

### D2. Stackup → regole CAD

Passi:

1. Form stackup (N layer, h, er).
2. Output: w/s per 50 / 90 USB / 100 diff.
3. Export KiCad `.kicad_dru` o netclass — **consigli**, l’utente applica.
4. Nessun finding “traccia troppo stretta” finché non c’è `.kicad_pcb`.

---

## Wave E — RF schema (punto 7, parte schema)

Passi:

1. Topologia π/T tra pin ANT e connettore/antenna (stesso matcher filtri).
2. Target 50 Ω come **intento**, non misura: WARNING se manca rete e datasheet mostra matching.
3. CPW clearance: **Wave G** (layout).

---

## Wave F — Supply chain (punto 11)

Passi:

1. Estendere DigiKey/Mouser/LCSC: campi `lifecycle`, `rohs`, `stock`, `lead_time` già spesso nel payload.
2. Job periodico (non ogni review): `lifecycle.json` per MPN libreria.
3. Finding INFO/WARNING EOL/NRND; RoHS fail solo se il flag è esplicito.
4. Cross-ref: **solo** se il distributore dà `replacement` / family; niente LLM “equivalente”.

---

## Wave G — Layout (punti 3 residui, 7 CPW, 8, 10 SI)

Due file per progetto: **schema KiCad flatten** + **`.kicad_pcb`**.

**G0. Ingest layout**

Passi:

1. Parser `.kicad_pcb`: tracce, via, zone, layer, **net name**, footprint, courtyard, differential pairs se presenti.
2. I net del PCB devono combaciare con quelli dello schema dopo il flatten gerarchico (stesso `U1.4` ↔ pad).
3. Modello `LayoutGraph` affiancato a `DesignGraph`.
4. Gerber: non in questa wave. Solo se un utente non può dare il `.kicad_pcb`.

**G1. Check (solo se net e geometria sono legati)**

Passi:

1. Length matching / intra-pair skew vs limite datasheet (USB/HDMI/PCIe).
2. 3W: distanza centro-centro vs W aggressore.
3. Creepage/clearance: profilo IEC 62368 (pollution, RMS V dai net).
4. Isolation barrier: bbox isolator + divieto piste LV nel courtyard HV.
5. CPW: gap verso GND copper vs valore del calcolatore D2.

**G2. Placement vs datasheet (piste, decoupling, thermal)**

Lo schema dice se C12 è sul net VDD. Il PCB dice se C12 è a 8 mm dal pad. Questo check è **solo layout + layout_rules**.

Passi:

1. Per ogni pin alimentazione del pintable: footprint pad xy sul `.kicad_pcb`; condensatori sul medesimo net (grafo); distanza euclidea pad-cap (pin cap verso GND/VDD).
2. Se `max_distance_mm` estratto: ERROR/WARNING se oltre. Se assente: WARNING oltre default configurabile, testo “datasheet non specifica mm; usato default 3 mm”.
3. Via in pad / via sotto EP: contare via nel courtyard del thermal pad vs `min_via_count`.
4. Stesso layer: se `same_layer: true` e il cap è sull’altro lato senza via sotto il pin → WARNING.
5. Piste: lunghezza net VDD dal pin al cap (somma segmenti) come proxy di “loop area”; se >> distanza euclidea, c’è un giro largo.
6. Crystal: cap load vs pin XIN/XOUT (stessa metrica di distanza), se X1 è nel grafo.
7. Finding `PS-PLC-001` con `pins`, `net`, pagina datasheet. Plugin: focus footprint su pcbnew.

Non confrontare una foto del layout TI con il board pixel-a-pixel. Solo vincoli numerici/topologici.

**Done when:** fixture PCB con C di decoupling a 15 mm da VDD (regola 2 mm) → `PS-PLC-001`; cap a 1 mm → niente finding.

**Done when (G1+G2):** un `.kicad_pcb` di test (USB diff pair volutamente sbagliata) produce `PS-SI-001`. I net coincidono con lo schema gerarchico della stessa repo.

---

## Wave H — Enterprise (punto 12)

Passi:

1. Stato finding: `open | false_positive | accepted | wontfix` + motivo obbligatorio.
2. Firma rilascio: hash report + user + timestamp (OSS: locale; cloud: già Clerk).
3. ECO: export `eco.json` / CSV: rule_id, ref, before/after raccomandazione, finding_id.
4. Dashboard: filtri già URL; aggiungere coda “da approvare”.

Commenti esistono: non rifarli, agganciarli allo stato.

---

## Ordine di esecuzione (sviluppo)

Non parallelizzare A0 schema finding con G.

| Sprint (indicativo) | Contenuto | Dipende da |
| --- | --- | --- |
| 0 | Schema finding + eval + smoke V4.1 | — |
| 1 | A1 KiCad GA + A2 BOM match | 0 |
| 2 | B3–B5 pull-up/decoupling/Cin-Cout | 0 |
| 3 | B6–B9 DC bias, ESR, filtri, termico | 2 |
| 4 | B1–B2 power drop/sequencing + B10 DNP | 1 |
| 5 | A3 plugin KiCad + E2 JSON | 1, 0 |
| 6 | C2 errata + C3 internal features + **C4 layout_rules** | eval C1 |
| 7 | D1–D2 calcolatrice impedenza + export netclass | — |
| 8 | F lifecycle | APIs già presenti |
| 9 | H review workflow / ECO | 0 |
| 10+ | G layout `.kicad_pcb` + G2 placement datasheet | A1 + C4 |

Stima onesta: Wave A–B (schema) sono il ritorno; G è un secondo prodotto. Non promettere creepage nel plugin schema.

---

## Passi operativi per **ogni** check nuovo

1. Fixture grafo minimo in `tests/test_<nome>.py` (non solo `simple_project`).
2. Funzione in `pinscopex/` senza I/O.
3. Registrare in `services/validation.py` accanto a pin_mux/LED.
4. `rule_id` + `source`.
5. Una riga changelog.
6. Se tocca UI: tab o badge “Automated check” già usato.
7. Browser solo se UI; senno pytest.

---

## Fuori scope (esplicito)

- Plugin o parser **EasyEDA**.
- Agente che **progetta** lo sbroglio.
- Simulazione SPICE/IBIS.
- Sostituti pin-to-pin inventati dall’LLM.
- Scraping errata senza whitelist.
- Layout da netlist PADS dump (`!PADS-POWERPCB`) — già rifiutato.

---

## Prossimo passo concreto (quando si apre lo sviluppo)

Sprint 0, in quest’ordine:

1. Estensione `Finding` (`rule_id`, `pins`, `net`).
2. Eval script `simple_project` (finding count + citation).
3. Flatten `.kicad_sch` gerarchico (fixture multi-foglio).
4. Upload `.kicad_pcb` accanto allo schema (parse, ancora senza check SI).
5. BOM mismatch finding.

Il plugin KiCad aspetta uuid + sheet path. Placement decoupling in mm e 3W aspettano `.kicad_pcb` + `layout_rules`.