# AuditAI PoC-First Flow Schema (v1)

## Flow
`finding -> poc -> patch -> verify`

## 1) Finding (existing `/scan`)
Response shape:
```json
{
  "scan_id": "uuid",
  "contract_name": "Contract.sol",
  "summary": "...",
  "findings": [
    {
      "id": "VULN-001",
      "title": "...",
      "category": "...",
      "severity": "Critical|High|Medium|Low",
      "line_number": 42,
      "description": "...",
      "exploit_scenario": "...",
      "suggested_fix": "...",
      "confidence": "High|Medium|Low"
    }
  ]
}
```

## 2) PoC + Patch scaffold (`/generate-poc`)
Request:
```json
{
  "contract_code": "...",
  "contract_name": "Contract.sol",
  "solidity_version": "0.8.19",
  "finding_id": "VULN-001"
}
```

Response:
```json
{
  "poc_id": "uuid",
  "contract_name": "Contract.sol",
  "vulnerability_type": "reentrancy|access-control|oracle-misuse|unchecked-call|generic",
  "source_finding_id": "VULN-001",
  "title": "...",
  "foundry_test_filename": "test/Contract.PoC.t.sol",
  "foundry_test_code": "...",
  "patch_diff": "...",
  "verification_steps": ["..."],
  "notes": ["..."]
}
```

## 3) Verify (current v1)
Verification in v1 is checklist-driven:
1. Apply `patch_diff`.
2. Run generated Foundry test.
3. Re-run `/scan`.
4. Confirm finding count/severity reduction.

## Planned endpoint for v2
`POST /verify-fix`
```json
{
  "original_contract_code": "...",
  "patched_contract_code": "...",
  "finding_id": "VULN-001"
}
```

Target response (planned):
```json
{
  "verification_id": "uuid",
  "status": "fixed|partially-fixed|not-fixed",
  "before": {"findings_count": 3, "critical_count": 1},
  "after": {"findings_count": 1, "critical_count": 0},
  "evidence": ["scan diff", "test output"]
}
```