STUDY.refaktor_fegyver_v2 - kaktusztea/szilankrpg GitHub Wiki

STUDY: feat/fegyver_v2 branch átfogó refaktor (belépő-doksi)

Státusz: VÉGREHAJTVA (2026-09-30). A felmérés + a 3 fázis (holtkód / dedup / modularizáció) elkészült - l. §10 és a web/karakter/refactorlog/2026-09-30.md (2. menet). Ez a doksi maradt a BELÉPŐ-doksi: olvasd be ELŐSZÖR, majd a refactorlog naplókat.

0. A feladat (user)

Átfogó, "clean code" refaktor a feat/fegyver_v2 branch teljes tartományára:

  • Commit range: 0c39772c..feat/fegyver_v2 (a kiágazás óta az egész branch). Ellenőrzött: 53 commit, 355 fájl, +7020/-3948 - nagy terep.
  • Fő célok:
    1. Konstansok kimozgatása a data/sources/konstansok.yaml alá (data layer elsőbbség - AGENTS.md).
    2. Erős modularizáció (nagy fájlok szétbontása, felelősség-tisztítás).
    3. Clean code (olvashatóság, konzisztencia).
    4. Dead code eltávolítás (elárvult fn-ek, kivezetett ágak maradványai).

1. Miért most / kontextus

A feat/fegyver_v2 branch a fegyver v2 migráció fő ága. A branchen sok inkrementális munka történt (v2 adatmodell, idea_default, extrák, kétkezes, távharc v2, pajzs-kivezetés). A gyors iteráció után most jön a konszolidáció: a felhalmozódott hardcode, duplikáció, halott kód és a túl nagy modulok rendbetétele - MIELŐTT a branch mergelődik.

2. A terep (mérve, 2026-09-30)

  • konstansok.json már 54 kulcsú (sok konstans MÁR itt van) - a refaktor a MARADÉK hardcode-ot keresi, nem nulláról épít.
  • FONTOS megkülönböztetés (különben zajos a keresés): a ?? 0 / ?? 1 fallback-ok NEM hardcode-konstansok (védő default-ok) - ezeket NE mozgasd. A valódi cél: beégetett BALANSZ/KÜSZÖB számok (pl. egy * 2, > 16, === 20 a logikában), amelyek a data layerbe valók.
  • Két külön konstans-világ, NE keverd:
    • data/sources/konstansok.yaml → konstansok.json (webapp runtime).
    • data/sources/fegyverek/konstansok.yaml (fegyvergenerátor belső - a code/balance használja, NEM megy át a generate_tables.py-n; l. fegyvergenerátor-overview invariáns).
  • Reactive engine: a kalkuláció nagy része data/rules.json (53 szabály) - a formula-nyelv az elsődleges hely a számításra, a hardcode CSAK ott indokolt, ahol a reactive nem elég (2D lookup, per-fegyver override) - l. AGENTS.md "Data layer elsőbbség".

3. Korábbi refaktor-logok (KÖTELEZŐ olvasmány, tanulságok)

web/karakter/refactorlog/ - mind "AI ügynök célközönség", csapdákkal + detektáló scriptekkel:

  • 2026-09-09.md (nagy, 14 szekció) - a legátfogóbb korábbi refaktor.
  • 2026-09-11.md, 2026-09-15.md, 2026-09-20.md - fortély-mods, effekt-modell, egyéb.
  • 2026-09-30.md (mai) - fegyver v2 idea_default + kétkezes + távharc v2 + extra-prefix. Csapdák: közös teszt-fixture (load-gamedata.ts), 0-index falsy, dist-postbuild, SP -99 sentinel.

Ezekben KÉSZ detektáló scriptek és rögzített konvenciók vannak - használd őket újra, ne írj újat.

4. Javasolt megközelítés (a nagy terep miatt fázisokban)

A 355 fájl miatt EGY menetben kockázatos. Javasolt: fázisokra bontva, mindegyik után npm run build (18s, teljes: test + tsc + bundle) + git-commit, hogy a regresszió lokalizálható legyen.

  1. Felmérés (módosítás nélkül): a 0c39772c..HEAD diff átnézése, a hardcode / duplikáció / halott kód / túl nagy modulok listázása. Delegálható sub-agentnek (a fő context védelme).
  2. Konstans-kimozgatás: a valódi beégetett balansz-számok → konstansok.yaml (+ séma + a webapp olvassa). Fázisonként egy témakör (pl. harc, páncél, manőver).
  3. Dead code: az elárvult fn-ek/ágak (pl. process_fegyverek.py a pajzs+távharc kivezetés után - l. STUDY.tavharc_v2 "Hátra"; a code/lib másik fogyasztója generate.markdown.py, óvatosan).
  4. Modularizáció: a túl nagy fájlok szétbontása felelősség szerint (a MAP.md a jelenlegi felelősség-térkép - frissítsd, ahogy bontasz).
  5. Clean code: konzisztencia (naming, komment-nyelv angol, magyar UI), a workaround-regiszter (gui_spec) átnézése.

Minden fázis végén: build zöld + refactorlog-bejegyzés (mit, miért, milyen csapda).

5. Veszélyek / csapdák (a mai + korábbi tanulságokból)

  • Közös teszt-fixture: src/__tests__/load-gamedata.ts a VALÓS JSON-okat tölti - egy tábla átnevezése látszólag nem kapcsolódó teszteket bukhat (ENOENT). Refaktornál erre figyelj.
  • ?? fallback ≠ hardcode: ne mozgasd a védő default-okat konstansba (zaj).
  • A generátor a mérvadó (fegyvergenerátor-overview): a code/balance/*.py-ban a balansz-számok a data/sources/fegyverek/konstansok.yaml-ból jönnek - ott NE tegyél a webapp konstansok.yaml-ba valót (két külön world).
  • naming-lint csak yaml-ra fut (data/gen/naming_lint.py), a JSON source-okra (fixed) nem.
  • Séma strict: új konstans-kulcs → a konstansok.yaml séma + minden érintett source frissítendő.
  • Backward-compat NEM kell (localStorage invalidálható) - de a golden tesztek (TÉ/VÉ/SP/CÉ) NE változzanak érték szerint (a refaktor viselkedés-megőrző).

6. Gyors belépő parancsok (friss session)

# 1. A range áttekintése
git -C /repo/github/szilank.code log --oneline 0c39772c..feat/fegyver_v2
git -C /repo/github/szilank.code diff --stat 0c39772c..feat/fegyver_v2 | tail -30

# 2. Kötelező olvasmány
web/karakter/refactorlog/*.md   (különösen 2026-09-09 és 2026-09-30)
data/docs/AGENTS.md, MAP.md, DEVSTATE.md

# 3. Build (verifikáció, ~18s)
cd web/karakter && npm run build

7. Kapcsolódó, még nyitott tételek (a refaktorral érintkezhetnek)

  • process_fegyverek.py teljes kivezetése (STUDY.tavharc_v2 "Hátra") - a dead-code fázis része lehet.
  • Egységes effekt-modell §42 3. fázis (a calcFortelyMods + hatás-operátorok beolvasztása) - NAGY, külön; a modularizáció érintheti, de a big-bang effekt-motor NEM ennek a refaktornak a célja.

8. Emlékeztető a munkamódra

  • Tervet SOHA ne hajts végre automatikusan - mutasd be, kérj jóváhagyást (AGENTS.md workflow).
  • Nagy/kockázatos lépés előtt kérdezz. A 355 fájl miatt a fázisos, commit-onkénti haladás a biztonságos.
  • A refaktor VISELKEDÉS-MEGŐRZŐ: a build (496 teszt jelenleg) végig zöld maradjon.

9. Felmérés eredménye (2026-09-30, sub-agentekkel)

Módszer: a 0c39772c..feat/fegyver_v2 diff (355 fájl, ebből 121 TS/TSX kód + 27 py + 26 yaml) 4 párhuzamos, olvasás-only sub-agenten átvizsgálva (a fő context védelme, STUDY 4/1). Kategóriánként egy agent: konstans / duplikáció / holtkód / modularizáció. MÓDOSÍTÁS NEM történt. A találatok fázisonkénti végrehajtásra várnak (jóváhagyás után).

Fontos módszertani lelet: a naplók halott-export detektora grep -w-t használ, ami az ÉKEZETES magyar azonosítókat rosszul kezeli → HAMIS "EXPORT-ONLY" találatok. A duplikáció-agent ezt ékezet-biztos grep -F-fel újramérte. A jövőbeli detektor-futtatásnál erre figyelni kell.

9.1 Konstans-kimozgatás (2. fázis) - kevés valódi találat

A konstansok.json már 54 kulcsú; a branch keveset égetett be. A valódi (nem-fallback) jelöltek:

Rang Hely Érték Teendő
MAGAS harc/fegyver-calc.ts:28 return 1 (Természetes fegyver SP override) konstansok.yaml VAGY a fortély effekt-adatába (override 1, §42-konform)
KÖZEPES harc/fegyver-calc.ts:80,91 + ketkezes.ts Sebesség ?? 6 (alap fegyver-sebesség, DUPLIKÁLT) fegyver_alap_sebesség: 6 - a dedup is indokolja
KÖZEPES tavharc/helpers.ts:17 fok >= 2 ? 2 : 1 (Alkalmi tárgy hajítás Osztó-váltás) fortély effekt-adatba vagy konstansba
KÖZEPES tavharc/helpers.ts:210-217 Osztó→lövéskitérés kategória switch (1..4,>=5) osztó_lövéskitérés_kategória map a lövéskitérés blokk mellé (megj.: e sorok nem a diffben változtak)
ALACSONY dice.ts:38 EH_SZINT_MAX = 2 opcionális; kocka-motor invariáns, elfogadható a kódban
ZAJ harc-reszletek-calc.ts:162 ?? 99, tavharc/helpers.ts:223 -99 Erőlimit-fallback / SP-sentinel NEM mozgatni (védő fallback / adat-sentinel)

Konklúzió: a konstans-fázis KIS terjedelmű - lényegében 1 MAGAS + 3 KÖZEPES. A "Sebesség ?? 6" a legjobb, mert egyszerre old duplikációt (fegyver-calc + ketkezes) és hardcode-ot.

9.2 Duplikáció (a legnagyobb ROI) - közös lookup-helperek hiányoznak

Rang Minta Előfordulás Javasolt közös helyszín
MAGAS képzettségek.find(k => k.név === X)?.szint ?? 0 18×, 12+ fájl engine/-be képzettségSzint(karakter, név): number (a lookupFegyver mintájára)
MAGAS fortélyok.find(f => f.név === X)?.fok ?? 0 10× fortélyFok(karakter, név): number (pl. Kétkezes harc fok szó szerint dup: harc-reszletek-calc.ts:54 = ketkezes.ts:42)
KÖZEPES harcmodor-összeg reduce (a fenti fölé épül) 4× harcmodorÖsszeg(...) a B1 helperre építve
KÖZEPES kézi Math.max(a, Math.min(b, x)) 5× (eltérő határok) engine/utils.ts → clamp(x,min,max), a clampEHSzint erre épüljön
ALACSONY ${v>=0?'+':''}${v} előjel-formázás 3× előjellel(n): string
ALACSONY generikus .find(d => d.név === X) def-lookup ~90× (eltérő kollekciók/típusok) byNév<T>(arr, név) - gyenge ROI, sok call-site

Un-exportálás: 2 MEGBÍZHATÓ value-jelölt (hatásBadgeLabel HatasokInfo.tsx, rollElőnyHátrányDie dice.ts - utóbbi viszont a MAP.md-ben dokumentált publikus API, óvatosan). 12 típus BIZONYTALAN (TS4023-kockázat - exportált szignatúra hivatkozza) → csak tsc --noEmit után. Test-only exportok: elfogadhatók (tesztelhetőség).

Konklúzió: a képzettségSzint + fortélyFok (+ harcmodorÖsszeg) helper-hármas a refaktor LEGNAGYOBB egyszeri megtérülése - 30+ call-site egységesítése.

9.3 Holtkód - a Python-pipeline maradványai a fő terep, TS tiszta

  • TS: NINCS holtkód. A detektor 0 valódi találat; a 20 "kívülről nem hivatkozott" export mind modul-belső vagy engine/types.ts adatmodell-típus (a naplók 7. csapdája: ezek élők). Orphan-fájl: 0.
  • Python - VALÓSZÍNŰ halott, együtt kivezethető (zárt lánc, üres input, nem hívott, kimenet kivezetve): code/process_fegyverek.py + code/lib/MdToJsonConverter.py + code/lib/util.py.
  • Python - ÓVATOS, MEGTARTANDÓ: code/lib/JinjaHandler.py + code/generate.markdown.py - KÜLÖN (Jinja) fogyasztói ág, NEM esik a fentivel (fontos pontosítás: a generate.markdown.py csak a JinjaHandler-t importálja, a MdToJsonConverter/util-t NEM → a code/lib/ nem monolit).
  • Adat - BIZTOS HALOTT: archive/data_fegyverek_v1/{pajzsok.json, tavfegyver_pattern.json, pajzs_pattern.json} + üres data/patterns/ ág + üres data/gen/tables/ placeholder.
  • Adat - NEM halott: archive/data_fegyverek_v1/fegyverek.json - a code/balance/ v1↔v2 összehasonlítás AKTÍVAN olvassa (harcszimulacio_selftest.py, fegyverek_regi_uj_osszehasonlitas.py).
  • Külön hiba (nem holtkód, de érdemes jelezni): .github/workflows/update_fegyvertablazat.yml egy NEM létező scriptet hív (sync_fegyvertablazat_kozelharci.py); a valódi név sync_fegyvertablazatok.py. Eltört CI-hivatkozás.

Biztonságos kivezetési sorrend: előbb process_fegyverek.py + lib/MdToJsonConverter.py + lib/util.py (+ archív pattern JSON-ok, üres data/patterns/); a JinjaHandler.py/generate.markdown.py és az archive/.../fegyverek.json MARAD.

9.4 Modularizáció - a v2 a pure logikát jellemzően helyesen *-calc.ts-be tette

  • JÓ JELÖLT (pure kiemelhető, render-teszt NEM kell): 3
    1. tavharc/helpers.ts (263) - kitchen-sink 19 fn → mesterfegyver-calc.ts + tavfegyver-resolve.ts
      • loveskiteres-calc.ts; a CÉ/VÉ/szorzó mag maradhat.
    2. aktiv/taktika-helpers.ts (181) - 3 külön felelősség → taktika-megkotes.ts (isTaktikaAllowed)
      • taktika-format.ts; interpolateFokDef generikus util → engine//shared.
    3. tavharc/TavharcLoveskiteres.tsx (157) - buildOpciók pure lista-építő → loveskiteres-calc.ts.
  • ÓVATOS (JSX-monolit, @testing-library kell - NEM jóváhagyott függőség, naplókban tudatosan hagyva): KepzettsegProbaPopup.tsx (518), ManoverDobasPopup.tsx (453), TulajdonsagProbaPopup.tsx (308), SebzesPopup.tsx (295, kis sebzes-popup-calc.ts kiemelhető), TamadoDobasPopup.tsx (228).
  • RENDBEN (nagy de kohézív): HarcScreen.tsx (kompozíciós gyökér), TavharcScreen.tsx, engine/types.ts, engine/data-types.ts, a *-calc.ts pure modulok. data/gen/validators.py (162, validate_aktiv_ful figyelendő, ha tovább nő → al-fn-ek).

Konklúzió: a modularizáció szűk és kockázatmentes - a 3 JÓ JELÖLT mind pure (tesztelhető render nélkül), és mind a fegyver v2 által hízlalt/kevert modul.

9.5 Javasolt végrehajtási sorrend (a naplók bevált sorrendje: holtkód → data/dedup → modul)

A naplók sorrendje (halott kód → típus/data → duplikáció → monolit bontás), a jelen felmérésre szabva:

  1. Holtkód-kivezetés (9.3): Python zárt lánc + archív pattern JSON-ok + üres dir-ek. Külön a code/lib óvatosság miatt. (Mellé: a CI-workflow eltört scriptnév javítása - kicsi, önálló.)
  2. Duplikáció + konstans EGYÜTT (9.2 + 9.1): a képzettségSzint/fortélyFok/harmodorÖsszeg helperek + a Sebesség ?? 6 konstans-kimozgatás egy menetben (a clamp util opcionálisan). Ez a legnagyobb ROI, viselkedés-megőrző, tesztelhető.
  3. Modularizáció (9.4): a 3 JÓ JELÖLT (tavharc/helpers, taktika-helpers, TavharcLoveskiteres). A MAP.md felelősség-térkép frissítendő, ahogy bontunk.

Minden fázis végén: npm run build (496 teszt) zöld + git-commit + refactorlog-bejegyzés. A "MAGAS" konstans (Természetes fegyver SP) és a ?? 99/-99 sentinelek a §42 effekt-modell irányába mutatnak - ha oda kerülnek, az a 2. fázis része, nem külön effekt-motor.

10. Végrehajtás eredménye (2026-09-30)

A 9.5 sorrend szerint, 3 commit, mindegyik npm run build zöld. Részletes napló: web/karakter/refactorlog/2026-09-30.md (2. menet).

Fázis Commit Eredmény
1. Holtkód c9bbc579 (+ utólagos revert) Régi md→json pipeline kivezetve a code/-ból. User-döntés: a Python-lánc NEM törölve, hanem archive/data_fegyverek_v1/ alá mozgatva; az archive/ alatti pattern JSON-ok is maradnak. Üres dir-ek törölve. archive/ mostantól érinthetetlen (AGENTS.md).
2. Dedup + helper d24910b3 engine/utils.ts: képzettségSzint/fortélyFok/harcmodorÖsszeg/clamp. ~20 call-site egységesítve. +6 teszt.
3. Modularizáció 25ae906d tavharc/mesterfegyver-calc.ts + loveskiteres-calc.ts (+buildOpciók) + aktiv/taktika-megkotes.ts. MAP.md frissítve. +3 teszt.

Teszt: 496 → 505, végig zöld, viselkedés-megőrző.

Szándékosan kihagyva (indokkal - l. refactorlog csapdák)

  • Konstans-kimozgatás (9.1): nincs biztonságos, in-scope célpont. A ?? 6 (Sebesség) latens védő default (0 hiányzó a 117 módból), a Természetes fegyver SP (1) §42-függő. A clamp az egyetlen általánosan hasznos kimenet.
  • B4 kézi clamp dedup: 9 eltérő-határú call-site, gyenge ROI; a clamp helper elérhető jövőre.
  • JSX-monolitok: render-teszt (nem jóváhagyott @testing-library) nélkül nem bonthatók.
  • 12 bizonytalan un-exportálás (TS4023): külön, célzott tsc-ellenőrzéssel.