adlee-was-taken 9fc6b83bba v3.0.0: V3 features, server refactoring, and documentation overhaul

- Extract WebSocket handlers from main.py into handlers.py
- Add V3 feature docs (dealer rotation, dealing animation, round end reveal,
  column pair celebration, final turn urgency, opponent thinking, score tallying,
  card hover/selection, knock early drama, column pair indicator, swap animation
  improvements, draw source distinction, card value tooltips, active rules context,
  discard pile history, realistic card sounds)
- Add V3 refactoring docs (ai.py, main.py/game.py, misc improvements)
- Add installation guide with Docker, systemd, and nginx setup
- Add helper scripts (install.sh, dev-server.sh, docker-build.sh)
- Add animation flow diagrams documentation
- Add test files for handlers, rooms, and V3 features
- Add e2e test specs for V3 features
- Update README with complete project structure and current tech stack
- Update CLAUDE.md with full architecture tree and server layer descriptions
- Update .env.example to reflect PostgreSQL (remove SQLite references)
- Update .gitignore to exclude virtualenv files, .claude/, and .db files
- Remove tracked virtualenv files (bin/, lib64, pyvenv.cfg)
- Remove obsolete game_log.py (SQLite) and games.db

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-14 10:03:45 -05:00

1.7 KiB

Raw Blame History

Remaining Refactor Tasks

Leftover items from the v3 refactor plans that are functional but could benefit from further cleanup.

R1. Decompose `calculate_swap_score()` (from Plan 2, Step 4)

File: server/ai.py (~236 lines)

Scores a single position for swapping. Still long with inline pair calculations, point gain logic, reveal bonuses, and comeback bonuses. Could extract:

_pair_improvement(player, position, new_card, options) — pair-related benefit of swapping into a position
_standings_pressure(player, game) — how much standings position should affect decisions (shared with should_take_discard)

Validation: python server/simulate.py 500 before and after — stats should match within normal variance.

R2. Decompose `should_take_discard()` (from Plan 2, Step 5)

File: server/ai.py (~148 lines)

Decides whether to take from discard pile. Contains a nested has_good_swap_option() helper. After R1's extracted utilities exist, this should shrink since project_score() and known_score() handle the repeated estimation logic.

Validation: Same simulation approach as R1.

R3. New Test Files (from Plan 3, M6)

After Plans 1 and 2, the extracted handlers and AI sub-functions are much easier to unit test. Add:

server/test_handlers.py — Test each message handler with mock WebSocket/Room
server/test_ai_decisions.py — Test individual AI sub-functions (go-out logic, denial, etc.)
server/test_room.py — Test Room/RoomManager CRUD operations

Priority

R1 and R2 are pure structural refactors — no behavior changes, low risk, but also low urgency since the code works fine. R3 adds safety nets for future changes.

1.7 KiB Raw Blame History