bao/genshin-assistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document scanner product roadmap and Gitea workflow

Browse Source
This commit is contained in:
AzuTear
2026-07-09 10:28:17 +02:00
parent eb666febb6
commit 28d60eb915
9 changed files with 558 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/PROJECT.md
+74 -15
View File
@@ -5,14 +5,17 @@ This document is the source of truth for project intent, scope, runtime facts, a
For implementation structure, see [ARCHITECTURE.md](ARCHITECTURE.md). For engineering standards, see [CONVENTIONS.md](CONVENTIONS.md).
For the latest Inventory-Kamera comparison work, see
[scanner-ik-progress-report.md](scanner-ik-progress-report.md).
For the next scan-result and artifact-inventory product phase, see
[scanner-results-inventory-roadmap.md](scanner-results-inventory-roadmap.md).
For the 2026-07-09 scanner merge evidence, see [MERGE_READINESS.md](MERGE_READINESS.md).
For Gitea push/authentication setup, see [GITEA_AUTH.md](GITEA_AUTH.md).
## Project Identity
| Field | Value |
| --- | --- |
| Project name | Genshin Artifact Assistant |
| Status | Scanner baseline merged to `main`; repeatability, corpus growth, and recommendation work are next |
| Status | Scanner baseline merged to `main`; scan result rail, artifact inventory, extraction quality, and corpus growth are next |
| Platform | Windows desktop |
| Target users | Genshin Impact players who want artifact decisions without complex optimizer setup |
| Runtime | Electron app with React UI and TypeScript |
@@ -29,6 +32,9 @@ The app is not intended to replace deep min-max tools. It prioritizes time savin
- Build one local canonical Genshin data package for artifact sets, pieces, slots, stats, and characters.
- Parse artifact name, slot, main stat, substats, set, equipped state, and confidence deterministically against that package.
- Save weak or failed reads automatically as review samples and turn corrections into reusable local fixes.
- Present finished scan results as a compact artifact list instead of a debug-heavy live stats surface.
- Keep extraction confidence separate from artifact value so uncertain OCR becomes review, not a misleading low score.
- Provide a browsable local artifact inventory with detail views before promoting broader recommendations.
- Keep the app offline-first and usable without Genshin Optimizer, Inventory Kamera, Enka, or HoYoLAB.
- Re-introduce recommendations only after the scanner base is trustworthy.
@@ -54,6 +60,9 @@ The app is not intended to replace deep min-max tools. It prioritizes time savin
| FR-009 | Provide account-level artifact triage after scanner trust is acceptable. | Should | Pending |
| FR-010 | Provide 1-3 simple build suggestions per character from owned artifacts after scanner trust is acceptable. | Should | Pending |
| FR-011 | Farming overlay for reward scans. | Later | Prototype shell |
| FR-012 | Show active scan results as a minimal right-side rail with artifact number, name or compact fallback, value score, and status pill. | Should | Planned |
| FR-013 | Provide a scanned artifact inventory view with compact score pills, filters, sorting, and click-through detail. | Should | Planned |
| FR-014 | Provide artifact detail evaluation with screenshot/crops, parsed fields, OCR confidence, value reasons, and optional upgrade projection. | Should | Planned |
## Non-Functional Requirements
@@ -64,6 +73,7 @@ The app is not intended to replace deep min-max tools. It prioritizes time savin
| IK target | First 100 artifacts should scan with accuracy at least as good as Inventory Kamera and equal or better speed. | `npm run scan:goal:compare:validated` or `npm run scan:goal:compare:validated:wait` quality-gated report |
| Privacy | Captures and parsed data stay local by default. | No remote upload in scanner path |
| Reliability | Uncertain OCR must be visible to the user. | Confidence and details view |
| Score integrity | Extraction confidence and artifact value are separate concepts. | Review state can block or qualify a value score |
| Learning loop | Scanner mistakes should become reusable local review samples. | `review-samples.jsonl` |
| Maintainability | Scanner heuristics must be isolated and documented. | Parser tests, scan-loop tests, data generator, review sample pipeline |
@@ -128,8 +138,11 @@ The app is not intended to replace deep min-max tools. It prioritizes time savin
2026-07-08.
- OCR quality is still inconsistent enough that some fields are recovered by fallback and derivation more often than they should be.
- Learned fixes currently focus on text replacements; they do not yet update crop offsets, UI profile variants, or scanner targeting rules in a structured way.
- The scan page is cleaner than before, but it still exposes too much operator/debug state in the main flow.
- Recommendations and build logic exist, but the scanner is not yet reliable enough to make them the core focus.
- The scan page is cleaner than before, but it still needs the next minimalist
result-rail pass so the main flow shows preview plus completed artifact
outcomes instead of live diagnostic/stat content.
- Recommendations and build logic exist, but artifact inventory, detail review,
and value scoring should land first so recommendations have trustworthy inputs.
- The latest source has completed the final current-vs-IK-traineddata live
comparison for this environment. Repeatability and 3 artifacts/second are
still open.
@@ -140,9 +153,10 @@ The app has crossed from OCR-demo/prototype into a validated scanner baseline on
`main`. The current merge-ready path is the visible-inventory scan flow: the
operator opens Artifact inventory with a visible detail card, the app verifies
the state, scans read-only, persists parsed artifacts, and keeps uncertain data
reviewable. The next product phase is not another broad scanner rewrite; it is
repeatability, corpus growth, UI polish, and then recommendations on top of the
trusted artifact store.
reviewable. The next product phase is not another broad speed rewrite; current
speed is acceptable for now. The priority is better content extraction, a
minimal scan-result rail, a browsable artifact inventory, detail evaluation, and
corpus growth before recommendations become the core product surface.
## Product Direction
@@ -151,6 +165,11 @@ trusted artifact store.
- Team building stays out of the critical path until artifact ingestion is stable.
- Inventory Kamera remains a reference for scan choreography and page movement, not a runtime dependency.
- Self-learning stays deterministic and local first: review samples, aliases, crop offsets, and UI profile tuning before any ML retraining discussion.
- The scan workspace should be an operator surface: preview, live result rail,
Stop, status, and review access. Detailed stats and debug evidence belong in
diagnostics, summaries, or artifact detail.
- Artifact value scoring must not hide OCR uncertainty. `Review` is a distinct
outcome, not just a weak artifact score.
## Execution Plan
@@ -270,31 +289,69 @@ Status:
crop adjustment proposals, and UI-profile adjustment proposals. Crop/profile
changes still require live review before being auto-applied.
### Phase 6 - Recommendations come back on top of a trusted scanner
### Phase 6 - Minimal scan result rail and artifact inventory
Outcome:
- The scan page shows a large screenshot/preview and a compact right-side rail
of finished artifact evaluations.
- Each row shows scan number, artifact name or compact fallback, value score,
and a colored status pill.
- Debug stats, confidence breakdowns, and OCR internals move out of the main
scan surface.
- A new artifact inventory menu provides compact browsing, filters, sorting,
and click-through details.
Status:
- Planned. See
[scanner-results-inventory-roadmap.md](scanner-results-inventory-roadmap.md)
for the implementation phases and acceptance criteria.
### Phase 7 - Artifact detail evaluation and upgrade projection
Outcome:
- Artifact detail explains parsed fields, OCR confidence, scoring reasons, and
review needs.
- Upgrade projection is available only when enough data is known and is labeled
as probabilistic, with worst/middle/best projected value scores.
- Low-confidence OCR disables or qualifies value conclusions instead of showing
false certainty.
Status:
- Planned after the scan result rail and inventory data contracts.
### Phase 8 - Recommendations come back on top of a trusted scanner
Outcome:
- Account snapshot and build suggestions are only promoted once scan quality is high enough to trust owned artifacts.
- Recommendations explain uncertainty and surface conflicts instead of pretending perfect certainty.
Status:
- Next major product area after repeatability and corpus work. Do not promote
recommendation UX until stored artifact quality is backed by more confirmed
review samples and repeat live scan runs.
- Next major product area after inventory, detail evaluation, repeatability, and
corpus work. Do not promote recommendation UX until stored artifact quality is
backed by more confirmed review samples and repeat live scan runs.
## Immediate Next Implementation Order
1. Keep the visible-inventory scanner path as the production baseline and avoid
promoting `auto-entry`, `direct-inventory`, or `paimon-menu` until they pass
their own low-limit live validations.
2. Grow the confirmed OCR corpus from review samples exported by
2. Implement the scan result and inventory data contracts from
[scanner-results-inventory-roadmap.md](scanner-results-inventory-roadmap.md),
preserving separate extraction confidence and artifact value.
3. Rework the scan page into preview plus minimal result rail; keep diagnostic
stats out of the primary scan surface.
4. Add the artifact inventory menu and detail view before expanding broad build
recommendations.
5. Grow the confirmed OCR corpus from review samples exported by
`npm run eval:review-candidates` and prepared through
`npm run eval:prepare-confirmed`.
3. Repeat live scanner runs in later sessions to prove repeatability across
6. Repeat live scanner runs in later sessions to prove repeatability across
pages, locked/unlocked artifacts, equipped footers, and duplicate handling.
4. Continue the optional `3 artifacts/second` work only if the next change can
7. Continue the optional `3 artifacts/second` work only if the next change can
reduce OCR/capture transport time without weakening quality gates.
5. Start recommendation/product UX work only after repeat scan quality and
confirmed corpus coverage are strong enough to trust stored artifacts.
8. Start recommendation/product UX work only after inventory/detail evaluation,
repeat scan quality, and confirmed corpus coverage are strong enough to trust
stored artifacts.
## Open Questions
@@ -303,4 +360,6 @@ Status:
| Is the current C# helper sufficient for production packaging, or does a later Rust/C++ sidecar still materially reduce latency or packaging risk? | Open |
| When should UI-profile learning be allowed to change crop geometry automatically versus requiring review approval? | Open |
| What scan-quality threshold is high enough before recommendations should be considered user-facing again? | Open |
| What exact first-pass value formula should drive the `0-100` artifact score before build-aware recommendations exist? | Open |
| Which upgrade projection model is honest enough for early UX: deterministic roll buckets, probability-weighted outcomes, or a deliberately simple best/middle/worst estimate? | Open |
| Which Genshin UI languages should be supported after English once the scanner contract is stable? | Open |