RoomiSplit (루미스플릿)#

룸메이트·셰어하우스·사택의 공동 생활비를 수집부터 정산까지 자동화하는 도구. 셀프호스팅 PoC로 시작해 React Native 모바일 앱을 목표로 합니다.

무엇을 해결하나#

매달 룸메이트 공동비용을 정산하려면 보통 이런 일을 한다:

1. 도시가스·인터넷·생수·관리비를 각기 다른 사이트/앱에 서로 다른 계정으로 로그인해 캡처한다.
2. 금액을 옮겨 적고, 사람마다 다른 분담 규칙(예: 특정인 생수 제외)을 반영해 계산한다.
3. 결과를 공유하고 송금을 요청한다.

여기서 진짜 시간을 잡아먹는 건 2번 계산이 아니라 1번 수집이다. 그리고 그 계산조차 "컴퓨터 앞에 앉아야" 가능한 경우가 많다.

RoomiSplit은 이미 쉬운 "OCR·계산"이 아니라, 정작 귀찮은 "수집과 모빌리티"를 공략한다. 청구 메일을 한 번 자동전달되게 설정해두면, 그 뒤로는 폰만으로 한 달치 정산이 끝난다.

⚠️ 한계: 현재 자동 수집은 이메일로 청구서가 오는 출처에만 적용된다. (검증 시점 기준, 쿠팡 생수만 메일 수신 확인.) 가스·인터넷·관리비처럼 메일이 안 오는 출처는 스크린샷을 전달하면 OCR로 처리한다. 자세한 배경은 PLAN.md의 "전략 리스크" 참고.

어떻게 동작하나 (수집 모델: 전달 기반)#

RoomiSplit은 사용자의 메일함을 직접 읽지 않는다. 대신 사용자가 청구 메일을 전용 주소로 전달하고, 서버는 전달받은 메일만 본다. → OAuth/IMAP 권한이 필요 없어 프라이버시·법규(개인정보·Google CASA 등) 부담을 회피한다.

[각 서비스: 가스/인터넷/생수/관리비]
        │  (이메일 고지 ON)
        ▼
   [사용자 Gmail]
        │  필터: "청구 메일 → 전용 주소로 자동전달"
        │  (메일 안 오는 출처는 스크린샷을 수동 전달)
        ▼
[내 도메인 MX → Cloudflare Email Routing]
        │  (수신 → 웹훅)
        ▼
[Cloudflare Email Worker (TypeScript)]
   ├─ 카테고리 판별 (제목 태그 [가스] 등 / 발신자)
   ├─ 텍스트 청구 파싱  +  이미지 첨부 OCR(LLM Vision)
        ▼
   [규칙 엔진]  거주자별 분담 규칙 적용
        ▼
   [Supabase]  월별 청구·정산 상태 기록
        ▼
   [정산 결과 회신]  이메일/메신저로 내역 전송

핵심 개념#

거주자 규칙 (residents)#

거주자마다 항목별 포함 여부를 boolean 매트릭스로 정의한다.

{
  "residents": [
    {
      "name": "홍길동",
      "note": "본인",
      "includes": {
        "가스": true,
        "인터넷": true,
        "생수": true,
        "관리비": true,
        "기타": true,
      },
    },
    {
      "name": "김영희",
      "note": "생수 별도 구매",
      "includes": {
        "가스": true,
        "인터넷": true,
        "생수": false,
        "관리비": true,
        "기타": true,
      },
    },
    // ...
  ],
}

카테고리#

관리비 · 인터넷 · 가스 · 생수 · 기타

분배 규칙#

• 항목별로 포함된 거주자 수 N으로 나눈다: 각자 몫 = ROUNDDOWN(총액 / N, 0)
• 본인(기준 거주자)이 반올림 잔액을 흡수한다: 본인 몫 = 총액 − Σ(나머지 사람 몫) → 합계가 정확히 맞음.
• 제외 항목은 N이 줄어든다. 예: 김영희가 생수 제외면 생수는 3명으로 분할, 김영희의 생수 몫 = 0.
• 일할계산 지원: 월중 입·퇴거 시 일수 비례 (예: ROUNDDOWN(총액 / N × 사용일 / 총일수, 0)).

이 규칙은 기존 수동 워크플로우(정산_TEMPLATE.xlsx)에서 검증된 로직을 그대로 옮긴 것이다.

엔드유저 가이드#

1. 각 서비스에서 "이메일 고지"를 켠다 (가능한 출처).
2. Gmail 필터를 만든다: 해당 발신자의 청구 메일을 RoomiSplit 전용 주소(u_xxxx@in.<도메인>)로 자동전달. (전달 주소 인증 메일은 서버가 자동 처리.)
3. 메일이 안 오는 출처(예: 관리비)는 스크린샷을 같은 주소로, 제목에 카테고리 태그([관리비])를 달아 전달한다.
4. 정산: 모든 항목이 모이면(또는 [정산] 메일을 보내면) 결과 내역이 회신된다. PC 불필요.

개발자 가이드#

기술 스택#

디렉토리 구조 (예정)#

roomisplit/
├── apps/
│   ├── worker/     # Cloudflare Email Worker (수집·파싱·정산 트리거)
│   └── mobile/     # React Native (Expo) 앱 — Phase 후반
├── packages/
│   ├── core/       # 규칙 엔진(분배 계산), 공유 타입
│   └── parsers/    # 출처별 청구 파서 플러그인
├── infra/          # Terraform 모듈 (Cloudflare, Supabase)
└── PLAN.md

로컬 실행 (예정)#

• Worker: wrangler dev
• DB: Supabase 로컬 스택 (supabase start)
• 환경변수: .env.example 참고 (도메인, Supabase 키, LLM API 키 등)
• 인프라: terraform plan / apply

기여#

이슈/PR 환영. 현재는 PoC 단계로 구조가 빠르게 바뀔 수 있다. 자세한 로드맵은 PLAN.md 참고.

로드맵 요약#

상세 계획·검증 게이트·전략 리스크는 PLAN.md.