Document scanner product roadmap and Gitea workflow
This commit is contained in:
AzuTear
@@ -0,0 +1,270 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user