점심 모으기부터 정산 계좌 자동 DM까지 처리하는 사내 슬랙봇입니다.
처음 쓰신다면 → 📖 사용 설명서 를 꼭 읽어주시면 감사하겠습니다!
① 모집중 ──▶ ② 모집 완료 ──▶ ③ 정산 중 ──▶ ④ 정산 완료
| 단계 | 해당 단계에서의 작업 | 권한 보유자 |
|---|---|---|
| ① 모집중 | /배달 으로 팟 생성 → 채널에 모집 메시지. 누구나 참여/취소 가능 |
— |
| ② 모집 완료 | 인원 확정. 더 이상 참여할 수 없음 | 파티장 (🔒 모집 마감) |
| ③ 정산 중 | 총 금액 입력 → 참여자 전원에게 계좌 DM 자동 발송. 각자 입금 체크 | 파티장 (💸 정산 시작) |
| ④ 정산 완료 | 전원 입금되면 자동 전환. 파티장이 수동으로 끝낼 수도 있음 | 자동 / 파티장 |
취소됨 · 정산 없음 · 추첨 완료. 이 세 상태의 경우는 이전 단계로 되돌아갈 수 없고 단계를 건너뛰거나 파티장이 아닌 사람이 마감·정산 처리를 할 수 없도록 막아두었습니다.
정산 없이 종료 (각자 계산): 각자 계산하는 식당처럼 봇으로 돈을 모을 필요가 없을 때, ② 모집 완료에서 파티장이 🙋 정산 없이 종료 를 누르면 ③·④ 단계를 건너뛰고 바로 끝납니다. 취소와 달리 "약속은 잘 끝났다"는 뜻이라 상태를 따로 구분합니다. 한 번 선택하면 되돌릴 수 없으니 주의하시기 바랍니다.
내기 (/내기빵): 이 4단계 흐름과 별개로 동작합니다.
정산이 필요 없기에 ① 모집중에서 파티장이 🎲 추첨하기 를 누르면 곧장 참가자 중 한 명을 무작위로 뽑고, 채널에 당첨자를 멘션으로 알려줍니다.
최소 2명이 모여야 추첨할 수 있고, 결과는 되돌릴 수 없습니다.
슬랙 앱 만들기와 토큰 발급은 SETUP.md 를 참고해주세요!
Node 26 이 필요합니다 (.nvmrc 에 적혀 있습니다). node:sqlite 같은 내장 기능을 쓰기 때문에
버전이 낮으면 실행되지 않습니다.
nvm 을 사용하고 계시다면 nvm use 을 입력해주시면 됩니다.
npm install
cp .env.local.example .env.local # 토큰 채우기 (SETUP.md 참고)
npm run bot # 슬랙봇 실행
npm run dev # 관리자 대시보드 (선택)봇 코드를 고쳐가며 개발할 땐 npm run bot:dev 를 쓰면 저장할 때마다 알아서 재시작합니다.
봇이 안 돌거나 커맨드가 안 뜬다면 먼저 아래 명령어를 입력하여 진단 과정을 밟으시면 됩니다. 진단 과정은 토큰 형식 · 권한 · 연결을 한 번에 검사하여 문제점을 찾습니다.
npm run doctor코드를 고친 뒤에는 이것부터 돌려보세요. 슬랙에서 일일히 테스트하지 않아도 문제 발생 유무를 확인할 수 있습니다.
npm test상태 전이 규칙(특이사항 포함), 파티장 권한, 정원 제한, 정산 금액 분배, 내기 추첨, 계좌 보관 기간, 모달의 필수/선택 표시를 검사합니다. 실제 DB는 건드리지 않고 임시 폴더에서 돕니다.
PR 과 main 커밋에서는 CI 가 타입 검사 · 린트 · 테스트를 한 번에 진행합니다.
슬랙 없이 대시보드가 어떻게 생겼는지만 보려면 아래 명령어를 입력하시면 됩니다.
npm run seed
npm run dev| 입력 | 동작 |
|---|---|
/배달 |
팟 만들기 모달 (메뉴 · 장소 · 시간 · 정원 · 계좌) |
/외식 |
팟 만들기 모달. 장소 대신 가게 이름·주소를 적으면 채널 메시지에 카카오맵 링크가 붙음 |
/내기빵 |
점심·커피·디저트 중 골라 참가자 모집 → 🎲 추첨하기 를 누르면 한 명 무작위 당첨 |
/계좌등록 |
내 계좌 저장. 다음부터 자동으로 채워짐 |
나머지는 전부 메시지의 버튼으로 진행됩니다.
버튼별 권한과 상태 표시까지 자세한 내용은 사용 설명서 를 참고해주세요.
(소스는 docs/user-guide.html 이고, GitHub Pages 로 띄웁니다)
bot/index.ts 슬랙봇 본체 (Bolt · Socket Mode). 4단계 흐름이 순서대로 적혀 있음
src/lib/status.ts 상태 정의와 전이 규칙 ← 상태 규칙을 바꾸려면 여기
src/lib/pots.ts 팟 생성 · 참여 · 상태 전이 · 추첨 로직 (권한 검사 포함)
src/lib/blocks.ts 슬랙 메시지 · 모달 생김새 (Block Kit)
src/lib/db.ts SQLite 연결과 테이블 정의
src/app/page.tsx 관리자 대시보드 (보기 전용, 30초마다 자동 갱신)
src/app/auto-refresh.tsx 자동 갱신 타이머 (갱신 주기를 바꾸려면 여기)
scripts/seed.ts 샘플 데이터 넣기
scripts/doctor.ts 토큰 · 권한 · 연결 진단 (npm run doctor)
scripts/restart-all.sh 봇과 대시보드를 한 번에 재시작 (macOS · Linux)
tests/ 규칙 테스트 (npm test)
docs/user-guide.html 사용 설명서 (GitHub Pages 로 공개)
docs/images/ 설명서 · README 일러스트
.github/workflows/ci.yml PR · main 커밋 검사
봇과 웹이 같은 SQLite 파일(data/baemin-bot.db)을 읽고 같은 로직(src/lib)을 씁니다.
- 계좌번호는 정산에 필요한 동안만 보관합니다. 팟이 정산 완료·취소·정산 없이 종료되고 24시간이 지나면 봇이 계좌번호를 지웁니다. 금액·참여자·입금 기록은 그대로 남습니다. (24시간을 기다리는 이유: 잘못 끝낸 정산을 🔄 정산 다시 열기 로 되돌릴 때 계좌가 필요합니다)
- 계좌 저장은 물어보고 합니다. 정산 시작 모달의 체크박스를 켠 경우에만
다음 팟에서 자동으로 채워집니다.
/계좌등록으로 직접 등록·변경할 수도 있습니다. - 대시보드는 이 컴퓨터에서만 열립니다.
127.0.0.1로 묶여 있어 같은 와이파이의 다른 사람은 볼 수 없습니다. 사내망에 열어야 한다면package.json의-H 127.0.0.1을 빼면 되지만, 로그인이 없으므로 권하지 않습니다. - DB 파일(
data/baemin-bot.db)에는 진행 중인 팟의 계좌번호가 평문으로 들어 있습니다. 파일을 복사하거나 백업할 때 유의하세요.
- 일러스트는 いらすとや 의 무료 소재를 활용하였습니다. (ありがとうございます！)
- Socket Mode 라서 ngrok이나 배포 없이 로컬에서 바로 동작합니다.
- Node 26 내장 기능만 씁니다 —
node:sqlite(DB), TypeScript 직접 실행. 네이티브 빌드 없음. - 대시보드는
connection()+<Suspense>로 요청마다 DB를 읽습니다. (동기 DB 조회는 이게 없으면 빌드 시점의 값이 굳어버립니다.)