AzuTear
55 lines
2.6 KiB
Markdown
55 lines
2.6 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.
|
|
- Details and debug information belong in modals or secondary panels.
|
|
- Avoid long, overfilled cards on scanner pages.
|
|
- The design direction is dark purple fintech glassmorphism with premium, focused controls.
|
|
- Disable buttons when their required data does not exist.
|
|
|
|
## 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.
|
|
- 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.
|
|
|
|
## 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.
|