michele
dc65e96a22
FACT, REQUIREMENT, and INFERENCE are separate fields; datasheet provenance lives in the rule DB so Recommended cannot stay ERROR; LLM output is REVIEW. Designer decisions persist across rescans. Schematic and PCB share one library and the same finding object in the report UI.
115 lines
4.4 KiB
Markdown
115 lines
4.4 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 (questa slice):** oggetto finding + clamp provenance/class + decisions + UI schema/PCB + libreria condivisa + check geometria già gated.
|
||
|
||
**Fase B (pianificata):** gerarchia component→system; timing; energy/thermal solo con θJA/P/I_load; ratings; derating PASS/MARGIN/RISK; PI; SI oltre skew mm; return path oltre stitch INFO; ESD/EMI; thermal FEM; BOM↔PCB↔datasheet; SPOF come REVIEW.
|