michele
a63e5bd7ab
Replace Faradworks Inc. TOS/privacy/contact/metadata with Michele Bigi. Dual-read pinscope_* keys; write periscope_* only. AGPL LICENSE and GitHub fork parent unchanged. validate.py not edited.
121 lines
4.7 KiB
Markdown
121 lines
4.7 KiB
Markdown
# Motore finding — schema e PCB (stesso oggetto)
|
||
|
||
Fonte: specifica di Michele (Project chat). Vale per **analizzatore schematico e PCB**. Un finding è un oggetto riproducibile, non un paragrafo LLM.
|
||
|
||
Libreria datasheet: **una** (`library/extracted` + extracted/ di progetto). L’esame PDF profondo gira **una volta** (pipeline schema). Il job PCB consuma quella cache e aggiunge solo geometria.
|
||
|
||
---
|
||
|
||
## 1. Tre strati — non mescolare
|
||
|
||
Ogni finding ha **tre campi distinti**:
|
||
|
||
| Strato | Nome campo | Chi lo produce | Cosa può contenere |
|
||
| --- | --- | --- | --- |
|
||
| **FACT** | `facts` | Motore deterministico (netlist, BOM, `.kicad_pcb`) | Solo osservabili: pin, net, mm, V, A, width, thickness |
|
||
| **REQUIREMENT** | `requirement` | Rule DB + estrazione libreria (citazione, pagina, MPN) | Testo **sourced**. Provenance nel DB, non nella prosa del modello |
|
||
| **INFERENCE** | `inference` | Ingegnere / LLM **solo** qui | Giudizio. Mai copiare un’inferenza in `facts` o `requirement` |
|
||
|
||
Non mescolare: un check non scrive “probabilmente sottodimensionato” dentro `facts`. Se manca un parametro, `evidence_status=INSUFFICIENT` e si **dice** che manca — non si inventa 1 oz, 10 °C, 50 Ω, IEC.
|
||
|
||
`finding` / `why` restano per compatibilità UI (copia di facts / requirement).
|
||
|
||
---
|
||
|
||
## 2. Provenance datasheet (rule DB)
|
||
|
||
Sul **record di regola**, non nel testo LLM:
|
||
|
||
| `provenance` | Significato | Classe / severity |
|
||
| --- | --- | --- |
|
||
| **MANDATORY** | Shall / abs-max / pin NC | Può essere **RULE** + ERROR |
|
||
| **RECOMMENDED** | Should / layout note | **Mai ERROR**. RISK o INFO |
|
||
| **TYPICAL** | Typical / default application | INFO o RISK, mai RULE ERROR |
|
||
| **EXAMPLE** | Figure / typical application circuit | REVIEW o INFO |
|
||
|
||
**Recommended ≠ ERROR.** Il clamp è nel motore (`complete_finding`).
|
||
|
||
---
|
||
|
||
## 3. Classi — Design Rule ≠ Design Review
|
||
|
||
| `finding_class` | Ruolo |
|
||
| --- | --- | --- |
|
||
| **RULE** | Violazione di un requisito MANDATORY misurato (FACT vs REQUIREMENT). Deterministico. |
|
||
| **RISK** | Margine / derating / inferenza ingegneristica con evidenza parziale. |
|
||
| **REVIEW** | Esame AI (schema o PCB). Non è una design rule. |
|
||
| **INFO** | Inventario, evidenza insufficiente, decisione del progettista, skip onesto. |
|
||
|
||
LLM `source=review` / `pcb_review` → sempre **REVIEW**, mai RULE.
|
||
|
||
---
|
||
|
||
## 4. Intent + memoria DECISION
|
||
|
||
Il progettista può dichiarare un intent (es. **PSEL tied low on purpose**). Persistenza: `decisions.json` nel progetto, fingerprint:
|
||
|
||
`{rule_id\|source}|{designator}|{net}|{aspect}`
|
||
|
||
`wontfix` / `false_positive` sul report **scrive** una DECISION. Al rescan il motore **non ri-naga** come ERROR: finding `suppressed=true`, `finding_class=INFO`, `decision_id` valorizzato.
|
||
|
||
---
|
||
|
||
## 5. Severity, confidence, evidence — indipendenti
|
||
|
||
- `status` (severity): ERROR | WARNING | INFO
|
||
- `confidence`: 0–1 (quanto è solido il FACT+REQUIREMENT)
|
||
- `evidence_status`: SUFFICIENT | INSUFFICIENT
|
||
|
||
Alto confidence + INFO è legale (misura chiara, non è un fault). Bassa confidence + ERROR **non** è legale se evidence è INSUFFICIENT: si declassa.
|
||
|
||
---
|
||
|
||
## 6. Oggetto finding (riproducibile)
|
||
|
||
Campi obbligatori del motore (oltre a designator / MPN / ids esistenti):
|
||
|
||
```
|
||
facts, requirement, inference
|
||
source (pagina/MPN/rule_id)
|
||
calculation
|
||
assumptions[]
|
||
confidence
|
||
status (severity)
|
||
action # cosa fare; UI usa anche recommendation
|
||
provenance
|
||
finding_class
|
||
evidence_status
|
||
decision_id? suppressed?
|
||
```
|
||
|
||
---
|
||
|
||
## 7. Libreria unica / esame unico
|
||
|
||
| Store | Path |
|
||
| --- | --- |
|
||
| Estrazioni IC | `library/extracted/{safe_mpn}.json` (shared) ∪ `extracted/` progetto |
|
||
| PDF blob | `library/datasheets/blobs/{md5}.pdf` |
|
||
|
||
PCB: `review_ic_async(..., pdf_path=None)` se c’è pintable. Skip: `no library extraction — run schematic review first`.
|
||
|
||
---
|
||
|
||
## 8. Cosa è solo PCB
|
||
|
||
Geometria board: width/thickness, via, pour courtyard, placement mm, return/stitch, pad-net vs schema (`PE-LAY-*` gerarchia `/net`). **Non** duplicare check schema (mux, LED, filtri netlist).
|
||
|
||
---
|
||
|
||
## 9. Fasi (non fingere completezza)
|
||
|
||
**Fase A:** oggetto finding + clamp provenance/class (**ERROR solo se RULE e MANDATORY**) + decisions + UI schema/PCB + libreria condivisa + check geometria già gated.
|
||
|
||
**Fase B (questa slice):** gerarchia component→pin→net→block; derating PASS/MARGIN/RISK da Vop/Vrated; timing RC/strap solo con numeri; PI local vs bulk; ESD e return path come REVIEW.
|
||
|
||
**Fase B close-out:** BOM↔PCB↔datasheet (package/pinout/V/T/I); SPOF REVIEW; EMI solo con FACT in `layout_rules`; Tj da θJA+rame+via quando tutti i parametri ci sono.
|
||
|
||
**Fase B leftovers:** thermal FEM / OpenEMS; ImpedenceFinder LICENSE UNKNOWN; auto-place pcbnew; GitHub fork detach.
|
||
|
||
**Fase A identity (shipped on product HEAD):** operator TOS/privacy/fence; not a `validate.py` rewrite.
|