AzuTear
87 lines
4.9 KiB
Markdown
87 lines
4.9 KiB
Markdown
# Conventions
|
|
|
|
This document defines project engineering standards.
|
|
|
|
## Naming
|
|
|
|
- Use Genshin domain language where it makes behavior clearer: artifact, slot, set, main stat, substat, triage, build.
|
|
- Name booleans as predicates such as `isScanning`, `bridgeReady`, or `isGenshinCandidate`.
|
|
- Prefer explicit scanner names such as `createArtifactCrops` over generic names such as `processImage`.
|
|
|
|
## File Organization
|
|
|
|
- Keep Electron OS integration in `electron/`.
|
|
- Keep Electron `main.ts` as composition/wiring. Move durable window, file, helper, capture, OCR, or dev-control responsibilities into named modules under `electron/`.
|
|
- Keep React components in `src/`, with extraction when `App.tsx` becomes hard to review.
|
|
- Keep feature controller hooks small enough to review. If a hook owns persistence, import/export, entry choreography, scan-loop orchestration, and UI state at once, split those concerns into feature-local hooks or services.
|
|
- Keep pure domain logic in `src/lib/`.
|
|
- Keep shared contracts in `src/types/`.
|
|
- Keep generated outputs in `dist/`, `dist-electron/`, and `outputs/`.
|
|
- Keep `src/styles/global.css` as the stylesheet entrypoint. Put broad app styles in `base.css` and dev/diagnostic-only styling in `diagnostics.css` unless a more specific style module is introduced.
|
|
|
|
## UI Rules
|
|
|
|
- The scan page should prioritize the capture workspace over secondary status content.
|
|
- The active scan view should read as preview plus compact result rail, not as a dashboard of live diagnostics.
|
|
- Details and debug information belong in modals or secondary panels.
|
|
- Avoid long, overfilled cards on scanner pages.
|
|
- Do not collapse OCR/extraction confidence and artifact value into one ambiguous UI state; uncertain reads should be visibly `Review`.
|
|
- Artifact value pills should be short, stable labels backed by deterministic data, with detailed reasons behind click-through detail.
|
|
- The design direction is a premium, cinematic Galaxy system with restrained
|
|
glass surfaces, semantic contrast, and focused controls; reuse shared tokens
|
|
instead of feature-local state colors.
|
|
- Use skeletons for initial content layout, inline spinners for bounded work,
|
|
and toasts only for explicit mutation outcomes. Durable progress, blockers,
|
|
and errors stay in the owning view.
|
|
- Respect `prefers-reduced-motion`, keep focus-visible styling intact, and never
|
|
rely on color or animation as the only status signal.
|
|
- Disable buttons when their required data does not exist.
|
|
- Route user-facing renderer copy through `src/i18n`. English is the default
|
|
application locale; German is an explicit settings choice. Do not use an app
|
|
language switch to imply that another Genshin OCR/capture language is
|
|
supported.
|
|
- Keep stable `data-*` hooks for scripted renderer acceptance. Tests should not
|
|
depend on localized visible strings when a semantic hook is available.
|
|
- A destructive-looking local-data control must say what it removes and state
|
|
that it does not change Genshin. Require confirmation before local deletion.
|
|
|
|
## Scanner Rules
|
|
|
|
- Prefer focused crops over full-screen OCR.
|
|
- Confidence and raw OCR details must remain inspectable.
|
|
- Heuristics should fail safely into unknown fields or review notes.
|
|
- Do not add irreversible game actions.
|
|
- Treat global aliases as unsafe when the OCR text is ambiguous across pieces.
|
|
Canonicalize a partial artifact name only when independent high-confidence
|
|
field evidence, such as a direct slot read, leaves one valid match.
|
|
- Keep auto-entry choreography separate from scan-loop execution. Entry code may navigate to a readable artifact detail state; loop code should process verified grid targets.
|
|
|
|
## TypeScript Rules
|
|
|
|
- Keep strict type checks passing.
|
|
- Do not use `any` for capture, OCR, artifact, or recommendation contracts unless a boundary genuinely requires it.
|
|
- Parser functions should be deterministic and testable.
|
|
|
|
## Testing
|
|
|
|
- Use unit tests for parser and scoring logic.
|
|
- Use build/type checks for Electron IPC contract changes.
|
|
- Use manual Smart Capture smoke tests for crop and capture changes.
|
|
- For native timing claims, validate a complete `run-timing.json` and derive
|
|
end-to-end time from one request-to-reconciliation interval. Never add
|
|
overlapping capture and processing durations.
|
|
- Test local native-result removal for active-run blocking, tombstone filtering,
|
|
raw-evidence preservation, crop-path containment, and exact Store-record
|
|
scope.
|
|
|
|
## Documentation
|
|
|
|
- Update `docs/PROJECT.md` when product scope changes.
|
|
- Update `docs/ARCHITECTURE.md` when module boundaries or flows change.
|
|
- Add an ADR to `docs/DECISIONS.md` for durable technical trade-offs.
|
|
- Keep workflow/runbook docs linked from `docs/PROJECT.md` so future sessions
|
|
do not depend on chat history.
|
|
- Do not store tokens, passwords, cookies, or generated credentials in project
|
|
files. Use Git Credential Manager for Gitea HTTPS credentials; document only
|
|
the setup path in `docs/GITEA_AUTH.md`.
|