genshin-assistant/docs/scanner-results-inventory-roadmap.md

# Scanner Results And Artifact Inventory Roadmap

This document defines the next product phase after the validated visible-inventory
scanner baseline. The scanner is already fast enough for the current milestone;
the next work should improve artifact content extraction, review safety, and a
minimal inventory experience that makes scanned artifacts useful.

## Product Stance

- Keep the scan workspace focused on operation, not analysis.
- Keep the live preview as the dominant surface.
- Move debug metrics, OCR internals, and detailed evaluation behind details,
  diagnostics, or the inventory view.
- Do not merge scan confidence and artifact value into one ambiguous score.
- Treat uncertain OCR as review, not as a low-quality artifact.
- Prioritize extracting correct artifact content over another speed pass unless
  live timings regress materially.

## Target User Flow

1. The user opens Artifact inventory in Genshin with a visible detail card.
2. The scanner runs the existing read-only visible-inventory flow.
3. The scan view shows the latest screenshot/preview on the left.
4. A compact live result rail on the right receives one row per finished
   artifact evaluation.
5. Each row shows only:
   - scan number,
   - artifact name or compact slot/set fallback,
   - artifact value score from `0` to `100`,
   - a colored result pill.
6. After the scan, the user opens the inventory menu to browse all scanned
   artifacts.
7. Clicking an artifact opens a detail view with screenshot, parsed fields,
   OCR confidence, scoring reasons, and optional upgrade projection.

## Score Contract

The UI must keep two concepts separate:

| Concept | Meaning | UI behavior |
| --- | --- | --- |
| Extraction confidence | How reliable the scan/OCR/parser result is. | Drives `Review`, warnings, and detail confidence rows. |
| Artifact value score | How useful the artifact appears for builds. | Drives the `0-100` value and good/mid/weak pill. |

Rules:

- If extraction confidence is too low, show `Review` instead of a normal value
  decision, even when a tentative value score exists.
- If the artifact is a duplicate, show duplicate state separately from value.
- The live rail may show one compact pill, but the data model should preserve
  separate `extractionStatus` and `valueStatus` fields.
- Score labels should be stable and simple:

| Value score | Label |
| --- | --- |
| `90-100` | Strong |
| `70-89` | Good |
| `45-69` | Mid |
| `0-44` | Weak |
| unknown or unsafe | Review |

The exact formula can start simple and deterministic. It should explain its
reasons in the detail view before it becomes a recommendation source.

## Planned Pipeline Shape

The current scan loop can keep shipping while the UI and data contracts are
built. A fuller producer/consumer pipeline is a later implementation step:

```mermaid
flowchart LR
    Capture["Single capture and game-control worker"]
    Queue["Bounded screenshot/crop queue"]
    OCR["OCR and parse workers"]
    Eval["Artifact evaluation"]
    Aggregate["Aggregator and store"]
    UI["Live rail and inventory"]

    Capture --> Queue
    Queue --> OCR
    OCR --> Eval
    Eval --> Aggregate
    Aggregate --> UI
```

Constraints:

- Only one worker may control Genshin input, focus, click, scroll, or failsafe
  polling.
- OCR/parse/evaluation workers may run concurrently on already captured
  screenshot/crop jobs.
- The queue must be bounded, initially around `4-8` jobs, so the scanner does
  not outrun retries, review decisions, or stop requests.
- The pipeline must preserve current safety rules: no memory reads, hooks,
  injection, game-file changes, deleting, feeding, enhancing, locking/unlocking,
  or spending resources.
- Do not implement the queue refactor before the result/inventory contracts are
  stable, unless timing evidence shows the current loop has become the blocker.

## Implementation Phases

### Phase 0 - Documentation and contracts

Status: prepared by this document.

Outcome:

- Product direction is documented.
- Main docs point to this roadmap.
- Acceptance criteria and checklists exist before code changes.

### Phase 1 - Result data model

Outcome:

- Add a durable scan result entry model with sequence number, capture metadata,
  parsed artifact identity, extraction status, artifact value score, value
  status, duplicate/review flags, and timestamps.
- Keep existing stored artifact records compatible.
- Add tests for status derivation so low-confidence OCR cannot become a normal
  `Good` or `Strong` result.

Likely files:

- `src/types/domain.ts`
- `src/types/storage.ts`
- `src/lib/scannerSession.ts`
- `src/lib/storedArtifactAdapter.ts`
- `src/lib/scanReviewUtils.ts`

### Phase 2 - Minimal live result rail

Outcome:

- Rework the scan main section into preview plus right-side result rail.
- Remove live evaluation cards and noisy stats from the primary scan area.
- Append rows only after an artifact has finished parse/evaluation.
- Keep Stop, scan status, and review access available.
- Keep debug stats in diagnostics or summary modals.

Likely files:

- `src/features/scan/components/ScanMainSection.tsx`
- `src/features/scan/components/ScanResultCards.tsx`
- `src/features/scan/components/hooks/useScanMainSectionModel.ts`
- `src/features/scan/components/hooks/useScanResultCardsModel.ts`
- `src/styles/base.css`

### Phase 3 - Artifact inventory view

Outcome:

- Add a menu item for scanned artifact inventory.
- Show a compact, minimal list or dense grid of stored artifacts.
- Each entry shows the same score/pill language as the live rail.
- Provide filters and sorting for review, score, set, slot, equipped, locked,
  and newest scan.
- Avoid a marketing/landing layout; the first screen is the actual inventory.

Likely files:

- `src/features/inventory/*`
- `src/features/layout/navigation.ts`
- `src/pages/app/*`
- `src/lib/artifactStore.ts`
- repository bridge/storage files as needed

### Phase 4 - Artifact detail view

Outcome:

- Clicking a live row or inventory item opens detail.
- Detail shows screenshot or detail crop when available.
- Detail lists parsed fields, OCR confidence, parser notes, extraction status,
  value score, and scoring reasons.
- Review-required items make the uncertainty explicit and do not present their
  score as final.

Likely files:

- `src/features/inventory/components/*`
- `src/features/scan/components/modals/*`
- `src/lib/artifactOcrParser.ts`
- `src/lib/scoring.ts`

### Phase 5 - Artifact value evaluation

Outcome:

- Add a deterministic artifact value evaluator before promoting build
  recommendations.
- Explain the score through factors such as set, slot, main stat, substat
  quality, level, locked/equipped state, and available character/build context.
- The evaluator must accept incomplete data and return review/unknown instead
  of confident nonsense.

Likely files:

- `src/lib/artifactEvaluation.ts`
- `src/lib/scoring.ts`
- `src/lib/substatRolls.ts`
- `src/lib/genshinLookup.ts`
- targeted unit tests under `src/lib/*.test.ts`

### Phase 6 - Upgrade projection

Outcome:

- For artifacts below max level, show optional projection only in detail.
- Provide `worst`, `middle`, and `best` projected value scores.
- Label projection as probabilistic and not a guaranteed result.
- Use known Genshin upgrade constraints and current substats; unknown or
  partially read data must disable or soften the projection.

Likely files:

- `src/lib/upgradeProjection.ts`
- `src/lib/substatRolls.ts`
- `src/features/inventory/components/*`
- parser/scoring tests

### Phase 7 - Queue-based analysis pipeline

Outcome:

- Introduce a bounded screenshot/crop job queue only after the UI/data contract
  is stable.
- Keep one game-control worker.
- Allow OCR/parse/evaluation workers to process queued jobs.
- Preserve stop/failsafe behavior and review decisions.
- Compare throughput against the current baseline without weakening accuracy.

Likely files:

- `src/lib/autoScanLoop.ts`
- `src/lib/scannerSession.ts`
- Electron capture/OCR boundary in `electron/main.ts` or extracted services
- scan-loop tests and live soak scripts

### Phase 8 - Recommendation promotion

Outcome:

- Promote account-level recommendations only after scan result quality,
  inventory browsing, detail review, and value scoring are trustworthy.
- Recommendations must reference stored artifact quality and uncertainty.

## Acceptance Criteria

- The scan page still fits the primary workflow without page-level scrolling.
- The preview remains visible during active scan.
- The right rail shows finished artifact evaluations, not noisy intermediate
  parser/debug state.
- Review items are visibly different from weak artifacts.
- Artifact value score and extraction confidence remain separate in data.
- Inventory view can browse stored scan results without opening diagnostics.
- Detail view explains why an artifact received its score.
- Upgrade projection never implies a guaranteed future roll.
- Existing safety constraints and scan quality gates remain intact.

## Validation Plan

- `npm run lint`
- `npm test`
- `npm run build`
- Add unit tests for score/status derivation and upgrade projection.
- For scanner-facing changes, run a low-limit visible-inventory live scan before
  wider validation.
- Keep `npm run scan:repeatability:wait` for later regression checks, not for
  every UI-only pass.