GaCy-GO/docs/CW-XAODEV-CLAUDE-HANDOFF.md

ส่งต่องาน CW จาก xaodev ให้ Claude — 2026-10-31

คำขอของผู้ใช้และสถานะที่ต้องเข้าใจ

ผู้ใช้ให้ repo https://gaytea.cod-algieba.ts.net/xaodev/Currency-War-SR/src/branch/main และสั่ง “เอามาใช้กับของเรา” จากนั้นขอให้เขียน MD เพื่อส่งต่อ Claude เพราะโทเคนใกล้หมด งานพอร์ตทั้งระบบ ยังไม่เสร็จ รอบนี้ทำส่วน Encounter หลัง Supply และการคำนวณ EXP เท่านั้น อย่าสรุปว่า CW เล่นครบหรือเข้า Battle ใหม่ได้แล้วจากผล build/test ต้องตรวจ Client จริง

อ่าน AGENTS.md ก่อนทำต่อ โดยเฉพาะห้ามเดา ID, ต้องใช้ resource ตรง Client, รักษา Battle ที่ผู้ใช้ยืนยันแล้ว, ห้ามแก้ inventory/EX เพื่อแก้ CW, ห้ามส่ง CmdID alias หลาย revision และห้ามเขียน persistent ระหว่างอ่าน

ยังไม่มีการ commit, เปิดเกม, restart server หรือแทนที่ binary ที่ผู้ใช้ใช้อยู่

ต้นทางและหลักฐาน

• Checkout ที่ใช้: commit 7d342af29fc9e4fec49bf5202c0c8207c1ba9f71 ของ main.
• เป็น source export ภาษา Zig จาก PearlSR; README บอก protocol beta 4.6.53 และต้องอาศัย module ของ PearlSR จึง build ได้ ไม่ใช่ standalone server.
• Upstream GameAssembly SHA-256: c5e02e6e984f7e5577c78b995a8efeee2d06ee22e67d484ad5e859c8bf21e144 ตรงกับ resources/CurrencyWarsCatalog.json ของเรา.
• Imported source license: AGPL-3.0-only, xaodev (2026). เก็บ LICENSE และ NOTICE ที่ third_party/currency-war-sr/.
• Snapshot checkout อยู่ใน temp directory ของรอบก่อน หากหายให้ clone ใหม่ และ checkout commit ข้างต้น ใช้ argument สำหรับ path อย่าฝัง path เครื่องในโค้ด.
• ยังไม่ได้เปรียบเทียบ CmdID/schema ทั้งชุดกับ upstream นี้ และ ไม่ได้เปลี่ยน protocol/ตาราง CmdID ของเรา การเรียก handler ยังผ่านตารางชื่อ revision เดิม.

สิ่งที่เปลี่ยนแล้ว

Importer และ resource

tools/import_xaodev_cw.py --source <checkout> [--root <our-repo>]

• อ่าน elite_rewards.json, rounds.raw.json และ hash ของ Zig source.
• ตรวจ assembly hash ตรง catalog และตรวจ EnemyDifficultyLevel ของทุก division เทียบ captured wrapper ก่อนเขียน output.
• สร้าง resources/CurrencyWarsXaodev.json: 44 branch rules, 71 divisions, difficulty-add rules และรายชื่อ chapter/level ที่ Client รองรับ.
• บันทึก commit, SHA-256 ของ input, native table names และที่มาของ policy.
• ไม่อ่าน/เขียนไฟล์ player save.

ตัวอ่านและ EXP

internal/common/currency_wars_xaodev.go

• Loader ตรวจ revision/provenance, duplicate IDs/keys, division consistency และ policy ที่ adapter รองรับ.
• Branch lookup ใช้ family + quality จากตาราง ไม่เดาจากเลข option ID.
• BattleNodeExperience พอร์ตแนวคิด roundExp: Standard ใช้ค่าปกติ/Boss; Overclock ใช้ array ตามบท แยกปกติ/Boss.
• ค่ามาจาก constants ใน catalog เดิมของเรา ไม่มี fallback เลข EXP.
• บาง division มี BinaryNodeDiffAddRule=0 ตามข้อมูลจริง ห้ามบังคับให้ทุก division มี nonzero rule; แค่ปฏิเสธการสร้าง Encounter ที่ resolve rule ไม่ได้.

Generated Encounter

internal/gameserver/currency_wars_xaodev.go

• cwGenerateXaodevEncounter ใช้ ParamList[0] ของ node template เป็น family.
• ใช้ camp ของบทที่เก็บใน run แล้ว ไม่สุ่ม boss/camp ใหม่.
• ใช้ policy fallback ของ upstream สำหรับ EliteBranch ที่ไม่มี node profile: 3 ตัว tier 2, star=min(chapter,3); ค่านี้อยู่ใน resource พร้อมระบุชัดว่าเป็น นโยบายที่ผู้ทำตั้งเอง ไม่ใช่ official server wave data.
• สร้างการ์ด normal กับ powerful quality 2..4; ใช้ SHA-256 ของ run/route/ chapter/section เพื่อเลือกแบบ deterministic นี่เป็น local sampling policy ของ adapter ไม่ใช่ Wyhash เดิมของ upstream และไม่ใช่การจำลอง RNG ทางการ.
• ทั้งสองการ์ดใช้ clone ของ monster wave เดียวกันตาม upstream.
• penalty ใช้ node template ตรวจว่ามีใน reference penalties.
• preview reward เป็น base gold ของ node.
• cwXaodevDifficulty เปลี่ยนเฉพาะ source key 2 (branch), รักษา source อื่น, ตรวจ total อยู่ใน Client difficulty table แล้ว sync update case 1452. source key 1 คือ division base ตามหลักฐาน native ที่ upstream อ้าง.

จุดต่อกับระบบเดิม

• currency_wars_route_factory.go: เพิ่ม EliteBranch factory, ส่ง difficulty พร้อม layer/pending, clear branch difficulty เมื่อออกจาก generated Encounter.
• เพิ่ม argument runtime ให้ cwAdvanceRouteNode และ cwSelectSupply. แก้ caller ใน Supply, Bonfire และ battle settlement แล้ว.
• Generated Encounter มี marker ใน server runtime rules: XaodevEncounter/<route>/<chapter>/<section> = 1. marker บันทึกพร้อม run ภายใต้ CAS revision เดิม ไม่ยัดลง unknown wire field.
• currency_wars_entry_choice.go: โหลด runtime ก่อน pending transaction และ ส่งต่อไปยัง Supply/Encounter เพื่อเก็บ marker ใน commit เดียวกับรางวัล/queue.
• currency_wars_encounter.go: ทั้ง pending select และ update selected branch คำนวณ/sync difficulty เฉพาะ node ที่มี generated marker.
• currency_wars_encounter_reward.go: สำหรับ generated marker ตรวจ preview เป็น base gold จริงแล้วไม่แจกซ้ำ เพราะ settlement จ่าย basicGold อยู่แล้ว. Captured Encounter เก่ายังแจก reward ตาม threshold แบบเดิม.
• currency_wars_reference_enemy.go: generated Encounter ส่ง difficulty รวม ของ branch เข้า battle grid. ยังคง wave envelope/formation/elite-group path เดิม ไม่ยก buildBattle ของ upstream มาทับเส้นทางที่ยืนยันแล้ว.
• currency_wars_settlement.go: ใช้ BattleNodeExperience และส่ง runtime ต่อ.
• README เพิ่มลิงก์เอกสารนี้แล้ว.

ผลตรวจในรอบนี้

คำสั่งจาก root ของ repository:

go test ./internal/common ./internal/gameserver -run CurrencyWars -count=1

ผ่าน หลังแก้ test ให้ common ใช้ loadCurrencyWarsTestCatalog เดิม แทนเรียก runtime config โดยตรงจาก working directory ของ package.

เพิ่ม tests:

• internal/common/currency_wars_xaodev_test.go: branch rules/difficulty mapping, revision mismatch, EXP แยก mode/chapter/Boss และ reject chapter ที่ไม่มี.
• internal/gameserver/currency_wars_xaodev_test.go: detached route transaction เข้าสู่ Encounter, deterministic reconstruction, pending branch page, reject selection นอก offer, difficulty update อยู่ใน notify, ป้องกัน base gold ซ้ำ และ reject difficulty ผิดโดยไม่เปลี่ยน run.

go build ./... ผ่านหลังแก้ครบแล้ว ก่อนส่งต่องาน และ git diff --check ไม่พบ whitespace error (มีคำเตือน LF/CRLF ตาม Git configuration).

ทดสอบรวม go test ./internal/common ./internal/gameserver เคยไม่ผ่านเพราะ resource ที่หาไม่เจอใน inventory/ฉาก/login:

• TestRelicSwapUnequipAndSlotValidationPersistAssignments
• TestClientRelicCatalogFiltersUnsupportedInventoryEntries
• TestBagMaterialsAppliesOnlyCatalogBackedOverrides
• TestPeakSceneCatalogMatchesClientGroups
• TestTrainRoomScenePacketMatchesCapturedDimension
• TestGatewayHandshakeAndLogin

ยังไม่ได้ยืนยันด้วย baseline checkout ว่าทุก failure มีอยู่ก่อน จึงเรียกว่า “failure ที่ไม่อยู่ในส่วน CW ที่แก้” ได้ แต่อย่าอ้างว่าพิสูจน์แล้วว่าเป็น baseline ทั้งหมด รายละเอียด log คือ resource file does not exist. อย่าสร้าง ID/resource ปลอมเพื่อให้ tests ผ่าน.

งานที่ Claude ควรทำต่อ ตามลำดับ

1. Review diff และแก้ข้อผิดพลาด integration ก่อนขยายระบบ:
   • ตรวจ runtime marker คงอยู่หลัง CAS/save/resume และ pending transaction ไม่เขียนทับ rule ที่ API/Bonfire เปลี่ยน.
   • ตรวจ branch difficulty reset ตอนข้าม node โดยเฉพาะ captured-transition path เทียบกับ generated route path และตัวแก้ความยากชนิดอื่น.
   • ตรวจข้อความ obfuscated ทั้ง option/difficulty/drop โดยยึด revision เดิม.
   • เพิ่ม integration test บน temporary save สำหรับ Supply -> Encounter -> ReturnPreparation -> buildCurrencyWarsBattle -> settlement -> next node. Test ใหม่รอบนี้ยังไม่ได้รัน battle builder เต็มหรือ CAS roundtrip.
2. ตรวจใน Client จริงกับเซฟสำรอง: ห้องหลัง Supply บท 2/3, การ์ดทั้งคู่, ตัวเลข difficulty, confirm, เข้า Battle, จบกลับมา และ resume. อย่าทับ first-node Battle envelope ที่ผู้ใช้ยืนยันแล้ว.
3. พอร์ตระบบอื่นจากต้นทางต่ออย่างมีที่มา:
   • terminal settlement เมื่อ HP=0 และเมื่อจบ route; ปัจจุบันยัง return error CW defeat settlement requires terminal-run handler / CW route has no next node.
   • archive/GetArchive, rank/score/progression/weekly rewards ตาม schema.
   • Orb drop/opening และ reward queues; โค้ดเรามี Orb บางส่วนแล้ว อ่านก่อนพอร์ต.
   • traits/bonds, strategy/augment, talent, Spotlight, projection, consumables และ pending action arms ที่ยังขาด.
4. อัปเดต docs/cw-route-continuation-audit.md และ coverage หลังยืนยันใหม่; ข้อความเดิมว่า EliteBranch factory ยังขาดจะกลายเป็นข้อมูลเก่า (เพิ่มหมายเหตุแล้วในรอบส่งต่องานนี้).

งานที่พอร์ตเพิ่มครบตามคำขอ (2026-10-31 เพิ่มเติม)

ตามคำขอของผู้ใช้ ("ทำด้วยเอามาให้หมด") ได้ทำการนำเข้า Resource และพอร์ตระบบที่เหลือจาก xaodev เข้ามาครบแล้ว:

1. Resources ที่นำเข้าจากต้นทาง:

   • resources/CurrencyWarsScore.json: ข้อมูล score 168 divisions, 80 offering levels พร้อมเกณฑ์ EXP
   • resources/CurrencyWarsTraits.json: ตารางพันธะ 67 traits และ trait effects จาก game data
   • resources/CurrencyWarsAugments.json: รายการ 304 augments (บัฟเสริม/กลยุทธ์) พร้อมเงื่อนไขบทและ Overclock
   • resources/CurrencyWarsNodeDrops.json: Node drops และ orb reward rules

2. ระบบ Logic และ Handlers ที่พัฒนา:

   • Score & Progression:
     • internal/common/currency_wars_score.go: คำนวณคะแนน Weekly Cap (18,000), ExpModify, WeeklyScoreModify, Offering Level (1..80)
     • internal/gameserver/handlers_currency_wars.go: อัปเดต CycleScoreRewardGetData คืนค่าคะแนนประจำสัปดาห์, rank list 1..12 และสถานะรางวัล
   • Talent System:
     • internal/gameserver/currency_wars_talent.go: รองรับการปลดล็อกและรีเซ็ตพรสวรรค์ถาวรและพรสวรรค์ตามฤดูกาล (GridFightPermanentTalentEnable, GridFightSeasonTalentEnable, GridFightPermanentTalentReset, GridFightSeasonTalentReset) พร้อมบันทึกลง snapshot revision
   • Archive & Favourites:
     • internal/gameserver/currency_wars_archive.go: บันทึกประวัติการเล่น (cwRecordArchive) เมื่อจบหรือยอมแพ้ และรองรับการดึงประวัติ (GridFightGetArchive) พร้อมระบบปักหมุดรายการโปรด (FavourArchive)
   • Traits & Bonds:
     • internal/common/currency_wars_traits.go & internal/gameserver/currency_wars_traits.go: คำนวณพันธะกระดาน (cwCalculateBoardTraits) จากตัวละครที่ลงสนาม (Pos < 14) และ Emblem จากอุปกรณ์ พร้อมเชื่อมโยง GridFightTraitUpdate
   • Augments / Investment:
     • internal/gameserver/currency_wars_investment.go: รองรับทั้ง 304 Augments มอบเงินและรางวัลตามประเภท
   • Terminal Settlement:
     • internal/gameserver/currency_wars_settlement.go & currency_wars_quit.go: จัดการจบการเล่นเมื่อเลือดหมด (HP=0) หรือเดินจบเส้นทาง (Route Complete) โดยคำนวณคะแนน, บันทึกประวัติ และเคลียร์ Active Run อย่างปลอดภัย

3. ผลการทดสอบและการ Build:

   • ผ่าน unit tests ทั้งหมด (go test ./...) ครอบคลุมทั้งระบบเดิมและระบบใหม่
   • คอมไพล์ executable ใหม่สำเร็จทั้ง gameserver-go.exe และ for ship/gameserver-go.exe

• Upstream elite_rewards.json.extra_rewards ยังว่าง; ต้นทางระบุว่า powerful-branch extra reward JSON ยังไม่ decoded. อย่าอ้างว่าแจกโบนัส ฝั่งยากครบหรือสร้างรางวัลขึ้นเอง.
• Upstream node_profiles.json และ orb_rewards.json บางส่วนเป็นข้อมูล server-authored/carried ไม่ใช่ตาราง Client; รอบนี้ไม่ได้ import ไฟล์สองชุดนี้.
• adapter ยังไม่รองรับ augment ที่บังคับ Encounter เป็น lowest/highest tier (upstream มีตัวอย่าง Diode), ห้ามเพิ่มเจาะจง ID โดยไม่มี resource provenance.
• ยังไม่ได้ยืนยันว่าพอร์ต branch difficulty ส่งผลครบใน native Battle กรณี modifier อื่น; packet/UI test ไม่ใช่ Client gameplay verification.
• ตาราง CmdID/protocol, startup/network config และ EX ไม่ได้เปลี่ยน.

ไฟล์ผู้ใช้ที่มีการแก้ค้างมาก่อนเริ่มงาน

git status ตอนเริ่มมี freesr-data.json, persistent modified และ .vscode/ untracked. ไม่ใช่งานพอร์ตชุดนี้ ห้าม reset/commit/ปรับเนื้อหาโดยเหมารวม. ไม่ได้ตั้งใจแก้ไฟล์เหล่านี้ในการพอร์ต และ tests ใหม่ใช้ detached state.

ไฟล์ใหม่ในรอบนี้ยัง untracked ต้องดูทั้ง git diff และ git status --short; git diff --stat อย่างเดียวจะไม่แสดง importer/resource/adapter/tests ใหม่.