🎴🪙 판돈정산 (pandon-settle)

친구 2~5명이 고스톱·포커·훌라를 할 때,
누가 누구에게 얼마를 보내야 하는지 끝날 때 한 화면에서 알려주는 웹앱

_{"동전은 없어도 계산은 정확하게"}

👉 pandon.blackpet.workers.dev

_{설치 없이 링크만 열면 됩니다 · 폰에서 "홈 화면에 추가"하면 앱처럼 씁니다}

---

이게 뭔가요

술자리에서 고스톱 한 판 끝날 때마다 벌어지는 일:

"야 지금 내가 얼마 잃었지?"
"아까 피박 그거 계산했나?"
"잠깐만, 그럼 결국 누가 누구한테 보내는 거야?"

판돈정산은 이걸 대신해 줍니다. 한 판 끝날 때마다 누가 났는지 + 몇 점인지 두 번만 탭하면 잔액이 실시간으로 굴러가고, 자리를 파할 때 "영희 → 재호 12,400원" 처럼 송금 목록으로 딱 떨어지게 정리해 줍니다.

잔액의 합은 언제나 0이므로, 송금은 인원 − 1 건을 넘지 않습니다. 3명이면 2건, 5명이면 4건입니다.

---

현재 상태

Important

동작합니다. npx serve public 으로 띄워서 바로 칠 수 있고, 테스트 108개가 통과합니다 (npm test). 문서는 두 편이고 역할이 다릅니다.

• SPEC.md — 무엇을 만드는가. 데이터 모델·계산 공식·화면 명세·검증된 테스트 기대값
• 설계서 — 어떤 구조로 만들고 어디에 올리는가. 웹앱 대 네이티브 앱, 모듈 경계, 저장 방식, Cloudflare 배포 형상
• docs/design/ — 어떻게 보이는가. 화면 시안과 디자인 시스템 (.dc.html)

명세 11장의 기대값 표는 그대로 테스트가 되어 있습니다 — 계산을 고칠 때 여기부터 보세요.

단계	상태
설계 명세 (SPEC.md)	✅
아키텍처·배포 설계서	✅
정산 알고리즘 settle.js + 테스트	✅
게임별 계산 rules.js + 테스트	✅
저장/복원 store.js	✅
고스톱 입력 화면	✅
정산 화면 · 공유 텍스트	✅
포커 · 훌라 화면	✅
SVG 누적 그래프 · 통계	✅
룰 설정 화면	✅
PWA (홈화면 추가 / 오프라인)	✅
실제 폰에서 확인	⏳

---

해보기

pandon.blackpet.workers.dev 를 열면 바로 칠 수 있습니다. 직접 돌리려면:

npx serve public      # 열어서 바로 치기 (빌드 없음)
npm test              # 계산·저장·그래프 108개
npx wrangler deploy   # Cloudflare 배포. --env 없이 한 줄

한 판은 누가 났어? → 몇 점? → 확인 세 번입니다. 피박·고박 같은 배수 칩은 전부 꺼진 채로 시작하고, 해당될 때만 누릅니다.

---

설계 원칙

이 프로젝트에서 타협하지 않는 것들입니다.

1. 입력이 쉬운 게 최우선

평범한 한 판은 승자 탭 → 점수 탭 → 확인 세 번으로 끝납니다. 피박·광박·고박 같은 배수 칩은 기본이 전부 꺼져 있고, 해당될 때만 누릅니다. 새 기능이 탭 수를 늘린다면 기능을 넣는 대신 기본값을 다시 설계합니다.

2. 어두운 방에서 보인다

밤에 술 마시며 본다는 전제라 다크 테마 고정입니다. 터치 타겟은 최소 56px, 금액은 tabular-nums 로 자릿수를 고정해서 숫자가 갱신될 때 레이아웃이 흔들리지 않습니다.

3. 룰은 하드코딩하지 않는다

고스톱과 훌라는 모임마다 룰이 다릅니다. 피박 배수, 3고부터 2배, 점수 상한, 독박 처리 방식까지 전부 설정으로 빠져 있습니다. 대신 기본값만으로도 바로 시작할 수 있게 설정 화면은 접혀 있습니다. "판돈 계산은 정확성보다 합의 가능성이 중요하다"는 전제입니다.

4. 계산 결과를 라운드에 박아 둔다 ★

각 라운드는 계산된 금액 변화량(deltas)을 자기 안에 캐시로 들고 있습니다. 잔액은 라운드를 매번 접어서 구하고, 따로 저장하지 않습니다.

export function balances(rounds, n) {
  const b = new Array(n).fill(0);
  for (const r of rounds) r.deltas.forEach((v, i) => (b[i] += v));
  return b;
}

덕분에 세 가지가 공짜로 따라옵니다.

• 나중에 룰 설정을 바꿔도 이미 끝난 판의 금액이 흔들리지 않는다
• 잔액이 별도 상태가 아니므로 상태 불일치가 원천 봉쇄된다
• 실행취소가 rounds.pop() 한 줄로 끝난다

5. 인원은 2~5명, 어디에도 3을 박지 않는다

기본은 3명이지만 둘이 맞고를 쳐도, 다섯이 둘러앉아도 됩니다. 계산 코드는 인원을 인자로 받고, balances(rounds, n) 의 n 에는 기본값을 두지 않습니다 — 빠뜨렸을 때 조용히 3인으로 도는 것보다 그 자리에서 터지는 편이 낫기 때문입니다.

고스톱은 4인부터 한 명이 광을 팔고 쉬므로, 라운드에 sitout 을 둬서 그 사람을 0원 처리합니다. 기본은 전원 참여라 평범한 판의 탭 수는 인원이 몇이든 그대로입니다.

6. 불변식은 코드가 지킨다

모든 라운드의 deltas 합은 반드시 0이고, 길이는 인원과 같다.

계산 함수는 반환 직전에 이걸 검사하고, 어긋나면 저장하지 않고 에러를 던집니다. 모든 금액은 정수(원 단위) 로만 다룹니다 — 부동소수점 금지.

---

기술 스택

의도적으로 아무것도 안 씁니다.

항목	결정	이유
프레임워크	없음 (Vanilla JS + ES Modules)	화면 5개짜리 앱에 런타임이 필요 없다
빌드	없음	npx serve 로 바로 뜨고, 정적 호스팅에 그대로 올라간다
상태 저장	localStorage	서버·로그인·계정 전부 없음
그래프	인라인 SVG 직접	꺾은선 몇 개에 차트 라이브러리 200KB는 과하다
테스트	node --test	계산·저장·그래프 108개. DOM 테스트는 없고 화면은 눈으로 본다
글꼴	표제만 웹폰트	본문은 시스템 한글 — 오프라인에서 먼저 떠야 한다
PWA	manifest.json + sw.js	홈화면 추가 · 오프라인 동작
배포	Cloudflare Workers 정적 자산	wrangler deploy 한 줄. Worker 코드는 한 줄도 없다

---

구조

pandon-settle/
├── SPEC.md                   ← 기능 명세
├── docs/superpowers/specs/   ← 아키텍처·배포 설계서
├── docs/design/              ← 화면 시안·디자인 시스템 (.dc.html)
├── wrangler.jsonc            ← Cloudflare 배포 형상
├── public/                   ← 이 폴더만 배포된다 (전체 120KB)
│   ├── index.html
│   ├── styles.css            ← 토큰과 컴포넌트
│   ├── manifest.json
│   ├── sw.js                 ← 오프라인. 앱은 network-first, 글꼴은 cache-first
│   ├── icon.svg · icon-{180,192,512,maskable}.png
│   └── src/
│       ├── rules.js          ← 게임별 점수→금액 (순수 함수)
│       ├── settle.js         ← 송금 정산 (순수 함수)
│       ├── store.js          ← 상태 + localStorage. 저장소를 주입받는다
│       ├── chart.js          ← SVG 누적 그래프 (순수 함수)
│       └── ui.js             ← 화면 렌더링 · 이벤트
└── test/                     ← 배포되지 않음
    ├── helpers.js            ← 모든 케이스에 걸리는 공통 불변식
    ├── settle.test.js · rules.test.js · store.test.js · chart.test.js

rules.js · settle.js · chart.js 는 DOM을 절대 참조하지 않습니다. 순수 함수만 export 합니다. store.js 는 저장소를 인자로 받으므로(createStore({ storage })) 브라우저 없이도 저장 실패·데이터 손상 같은 경로를 테스트할 수 있습니다.

---

지원하는 게임

🎴 고스톱	♠️ 포커	🃏 훌라
승자가 나머지 참여자 각각에게 받는 구조 고 횟수 (3고부터 2배씩) 흔들기 배수 패자별 피박 · 광박 · 멍박 고박 (외친 사람이 전부 뒤집어씀) 빠짐 (4~5인, 광 팔고 쉬는 사람) 점수 상한 옵션	simple — 딴 사람과 금액만 넣으면 나머지가 나눠서 부담합니다. 남는 1원은 기본적으로 딴 사람이 덜 받습니다(설정으로 바꿀 수 있음). detail 모드(n−1명만 넣고 나머지는 자동 계산)는 계산 코드에 들어 있지만 화면은 아직 없습니다 — 포커를 실제로 어떻게 치는지 정하고 만듭니다 (SPEC.md 12장 1번).	패자가 손에 남은 카드 점수만큼 지불 잔여점수 (A=1, J·Q·K=11·12·13) 독박 · 스톱박 훌라 · 7포카드 · 대빵/소빵 보너스 잔여점수가 20~80까지 나와서 점당 금액을 게임별로 분리합니다 (기본 10원).

계산 예시 — 고스톱, 점당 100원

재호가 7점에 2고로 났고, 철수가 피박

공통점수 = 7점 + 2고 = 9점

철수  9 × 2(피박) × 100 =  1,800원 지불
영희  9 ×          × 100 =    900원 지불
재호                      = +2,700원 획득

→ deltas: [+2700, -1800, -900] (합계 0 ✅)

---

정산 알고리즘

잔액 합이 0이므로 그리디 매칭은 한 번 돌 때마다 최소 한 사람을 소진시킵니다.

export function settle(balances) {
  const plus  = balances.map((v,i)=>({i,v})).filter(x=>x.v>0).sort((a,b)=>b.v-a.v);
  const minus = balances.map((v,i)=>({i,v})).filter(x=>x.v<0).sort((a,b)=>a.v-b.v);
  const out = [];
  let p = 0, m = 0;
  while (p < plus.length && m < minus.length) {
    const amt = Math.min(plus[p].v, -minus[m].v);
    out.push({ from: minus[m].i, to: plus[p].i, amount: amt });
    plus[p].v -= amt;  minus[m].v += amt;
    if (plus[p].v === 0) p++;
    if (minus[m].v === 0) m++;
  }
  return out;   // length <= 인원 - 1
}

잔액	결과 송금
[+400, +1150, -1550]	영희→철수 1,150 / 영희→재호 400
[+3000, -3000, 0]	철수→재호 3,000 (1건)
[+3000, -3000]	2인은 언제나 1건
[+5000, +2000, -1000, -2000, -4000]	5인은 4건 (= 인원−1)
[0, 0, 0]	없음

3명 이하에서는 이게 곧 최소 건수입니다. 4명 이상에서 더 줄이려면 잔액이 딱 맞아떨어지는 조합을 뒤져야 하는데, 그 최적화는 하지 않습니다 — "큰 사람부터 큰 사람에게" 가 술자리에서 설명하기 가장 쉬운 순서이고, 이 앱은 정확성보다 합의 가능성을 먼저 봅니다.

---

결과 화면

정산이 끝나면 이런 텍스트를 공유할 수 있습니다 (navigator.share 또는 클립보드 복사).

🎴🪙 판돈정산 · 8/24 · 고스톱 24판

🤑 재호  +12,400
😏 철수   +3,100
🫠 영희  -15,500

💸 정산
영희 → 재호  12,400원
영희 → 철수   3,100원

잔액에 따라 이모지가 자동으로 붙습니다 — 1등 🤑 / 소폭 이득 😏 / 본전 😐 / 소폭 손실 😥 / 꼴찌 🫠 에는 👑 오늘의 호구 왕관이 씌워집니다. 직전 판에서 배수를 맞았으면 💀 가 따라붙습니다.

여기에 사람마다 한 줄씩 그려지는 SVG 누적 그래프와 최고 한 판 / 승률 / 피박 최다 같은 오늘의 기록이 함께 나옵니다.

---

아직 안 정한 것

쳐보고 정하려고 일부러 남겨 둔 것들입니다. 자세한 배경은 SPEC.md 12장에 있습니다.

• 포커를 실제로 어떻게 치는가. 칩을 쓴다면 판마다 넣을 게 아니라 "끝날 때 최종 칩 개수만"이 압도적으로 편하고, 그러면 포커 화면이 완전히 달라집니다. 그때까지 simple 모드만 씁니다.
• 고박일 때 개인 배수. 지금은 고박자 본인 배수만 적용합니다.
• 5인 고스톱을 정말 그렇게 치는가. 전통 룰이라면 4인부터 한 명이 광을 팔고 쉬므로 5인은 두 명이 쉬는 셈입니다. sitout 이 여러 명을 받긴 하지만 확인된 바는 없습니다.
• 판 도중 인원 변경. 늦게 온 친구가 끼는 경우. 지금은 판이 시작되면 인원 고정입니다.

남은 일

실제 폰에서 확인 — 홈 화면에 추가 → 비행기 모드 → 뜨는가. 데스크톱 브라우저에서는 서버를 내린 채로 뜨는 것까지 확인했습니다.

---

하지 말 것

명세 13장에 못 박아 둔 금지 사항입니다.

• ❌ 서버 · 로그인 · 회원가입 — 이 앱의 존재 이유가 사라집니다
• ❌ 차트 라이브러리 도입 — 꺾은선 몇 개에 번들 200KB는 과합니다
• ❌ 계산 결과를 잔액 변수에 누적 저장 — 반드시 rounds 에서 매번 계산합니다
• ❌ 배수 규칙 하드코딩 — 전부 rules 설정을 거쳐야 합니다
• ❌ 입력 단계 추가 — 새 기능이 탭 수를 늘린다면 기본값을 다시 설계합니다
• ❌ 계산 코드에 인원 상수 3 — 인원은 언제나 players.length 에서 흘러 들어옵니다

---

라이선스

MIT