찰떡 (ChalDduck)

대학생 팀 프로젝트(팀플)를 위한 협업 앱. 초대 링크 + 이름으로 들어와서 역할을 조율하고, 회의 시간을 잡고, 자료를 모으고, 기여 기록을 남깁니다.

계정 가입은 없습니다 — 이메일을 쓰는 것은 이미 팀에 속한 사람이 몇 팀 중 어디로 들어갈지 고르는 보조 길일 뿐입니다(1-2절).

디자인 핸드오프(33화면 프로토타입)를 실제 코드베이스로 옮기는 중입니다.

스택

프레임워크	Next.js 16 (App Router) · React 19 · TypeScript
스타일	Tailwind CSS v4 + CSS 변수 디자인 토큰
아이콘	lucide-react (직접 등록한 것만 번들에 들어감)
서체	Pretendard Variable (저장소에 포함, next/font/local)
데이터	PostgreSQL (Supabase) + Prisma
AI	OpenRouter (기본 openrouter/free)
서버	Next.js Server Actions

처음 실행

npm install

.env 를 만들고 Supabase 대시보드 > Connect 의 값으로 채웁니다 (.env.example 참고 — 커밋되지 않습니다).

로컬 DB 로 개발하기 (권장)

.env 는 운영(배포본)과 같은 Supabase 를 가리킵니다. 개발 중에 누르는 버튼이 실제 팀의 데이터를 바꾸지 않도록, 로컬 Postgres 를 따로 두고 .env.development.local 로 덮어씁니다(커밋되지 않습니다).

createdb chalddeok_dev               # Homebrew Postgres 기준

Windows 는 PostgreSQL 설치 시 bin 을 PATH 에 추가하면 createdb 를 같은 이름으로 씁니다. 경로 예시 C:\Program Files\PostgreSQL\17\bin. psql 도 같이 들어갑니다. 기본 DB 사용자가 달라질 수 있어 DATABASE_URL 의 <사용자> 를 맞추고, scripts/db-test-base.mts 는 DIRECT_URL 을 그대로 씁니다.

npm run verify 가 돌아가는지 확인하려면 로컬 Postgres 가 실제로 살아 있어야 합니다 — db:check·test 계열이 이 DB 를 봅니다.

# .env.development.local
DATABASE_URL="postgresql://<사용자>@localhost:5432/chalddeok_dev"
DIRECT_URL="postgresql://<사용자>@localhost:5432/chalddeok_dev"
SUPABASE_URL=""                      # 파일 저장소를 끈다 — 운영 버킷에 쌓이지 않게

npx prisma migrate deploy            # 표 만들기
npm run db:seed                      # 데모 팀 한 개 넣기
npm run dev

이 파일은 next dev 뿐 아니라 Prisma CLI 와 시드도 먼저 읽습니다 (scripts/load-env.mjs). 그래서 파일이 있는 동안에는 prisma migrate 가 운영 DB 로 가지 않습니다. 운영에 직접 마이그레이션해야 할 때만 잠시 치우세요(평소에는 배포가 prisma migrate deploy 를 돌립니다).

시드는 로컬이 아닌 DB 를 가리키면 멈춥니다(같은 초대 코드의 팀을 지우고 다시 넣기 때문입니다). 정말 원격에 넣으려면 ALLOW_REMOTE_SEED=1 을 붙입니다.

로컬 시드에는 데모 팀원 네 명이 같은 재입장 코드를 받습니다 — /join/rejoin 에서 초대 코드 CD-3K7F2Q, 이름(김민준·이서연·박지호·최유나), 재입장 코드 DEMO-DEMO-DEMO. 원격에 넣을 때는 코드를 넣지 않습니다(누구나 아는 코드는 뒷문이 됩니다).

DATABASE_URL 은 런타임용 트랜잭션 풀러(6543), DIRECT_URL 은 마이그레이션·시드용 직결(5432) 입니다. 풀러로는 prepared statement 와 DDL 잠금을 못 버텨 마이그레이션이 깨집니다.

런타임 커넥션 풀은 src/server/db.ts 에서 직접 만듭니다 — 쉬고 있던 연결이 끊겼을 때 프로세스가 죽지 않게 받아 주고, 순간적인 연결 실패(P1001·P2024)는 짧게 두 번 다시 시도합니다. 자세한 이유는 그 파일 주석에 있습니다.

지금까지 구현된 것

• 디자인 토큰 — 색·타이포·치수 (src/styles/tokens/)
• 공통 컴포넌트 — src/components/ui/
• 온보딩 00~06 — 팀 만들기 → 초대 입장 → 이름 → MBTI(또는 30초 컷) → 캐릭터 → 희망 역할·Veto. 06 팀 화면에는 팀 MBTI 집계도 붙습니다(features/team/team-mbti.tsx). MBTI는 표시와 대화를 돕는 재료일 뿐이며, 역할 배정의 근거로 쓰지 않습니다 — 배정은 희망 역할과 Veto 만 봅니다(data/accepted-roles.ts). 캐릭터도 마찬가지입니다(05 화면에 같은 취지가 적혀 있습니다)
• 07 팀 역할 조율 — 역할별 현황, 협의 → 추첨 → 수락/거절, 팀원별 선호
• 08 내 가능한 시간 — 안 되는 시간만 표시. 목록형이 기본, 주간 격자는 보조
• 09 / 10 회의 시간 — 후보 제안 → 반대 없으면 자동 확정. 전원 불가한 주는 최다 인원 후보 + 다음 주 이월
• 11 홈 — 오늘의 브리핑 → 내 확인이 필요한 일 → 가까운 일정 → 최근 자료·업무 → AI 도구. 앞 두 구역은 07·09의 실제 상태에서 계산합니다
• 12 / 13 / 22 드라이브 — 역할별 제출함 → 파일 목록 → 버전 기록 → 열람·복원. 파일은 Supabase Storage 에 올라가고, 같은 이름으로 다시 올리면 덮어쓰지 않고 새 버전이 쌓입니다. 파일 목록은 핸드오프에 없던 화면입니다(아래 참고)
• 19 / 30 / 31 / 32 채팅 — 통합 목록, 팀 단톡방, DM 목록·대화. 단톡방과 DM 이 같은 말풍선 규격
• 읽기 순화 — 받는 사람은 순화된 표현을 받습니다(2-2 참고). 도착한 남의 말은 openrouter/free 로 다듬어져 보이며, 원문은 그대로 두고 그 사람에게만 순화문을 보여 주며, 원문으로 언제든 돌아갑니다
• 14 / 15 / 20 / 25 / 26 / 27 AI 도구 — 허브, 쿠션 번역기, AI 서기, 리서처, 발표 지원, 문장 변환
• 16 / 17 / 18 / 23 기여도 — 본인 확인 → 팀원 확인 → 1장 PDF. 점수·순위 없음. 기록을 직접 추가하고, 팀원이 확인해 주거나 "사실과 다릅니다"를 적고, 그 의견에 응답하는 한 바퀴가 다 돕니다. 자기 기록은 자기가 확인할 수 없습니다. 회의 참여 표시는 17 화면에서 팀장이 직접 찍고, 리포트에는 사람별 숫자로만 나옵니다(3절)
• 21 / 24 할 일 — 체크리스트와 콕 찌르기(담당자에게 진행상황 요청, 업무당 하루 한 번)
• 28 / 29 팀 친목 — 아이스브레이킹, 메뉴 룰렛
• 알림함 — 콕 찌르기·회의 제안·기여 기록 확인/정정·가입 승인 요청이 홈의 종에 모입니다
• 실패한 화면 · 없는 주소 — 렌더가 실패하면 기본 오류 화면 대신 나갈 길이 있는 화면을 보여 줍니다(app/error.tsx, 탭 안은 app/(tabs)/error.tsx 라 탭바가 남습니다)
• 33 채팅 PC 화면 — 1024px 이상에서 목록·대화·정보 3분할 (아래 참고)
• 반응형 앱 셸 — 모바일 하단 탭바 ↔ 데스크톱 세로 막대 (아래 참고)

핸드오프의 33개 화면을 모두 옮겼습니다.

파일 업로드는 SUPABASE_SECRET_KEY 가 있을 때만 동작합니다. 없으면 화면이 "파일 저장소가 아직 연결되지 않았습니다"라고 그대로 알립니다.

AI 도구는 OPENROUTER_KEY 가 있을 때만 모델을 부릅니다. 키가 없으면 앱은 그대로 돌아가고 도구는 미리 적어 둔 샘플을 돌려주며, 화면이 "아직 AI가 연결되지 않았습니다"라고 그대로 알립니다 — 샘플을 AI 결과인 척 보여 주지 않습니다.

구조

src/
  app/                  라우트
    join/               01 초대 링크 입장 · 00 팀 만들기 · 이메일 로그인
    onboarding/         02~06
    (tabs)/             하단 5탭(홈·채팅·일정·드라이브·팀)이 붙는 화면들
  components/ui/        공통 컴포넌트 (핸드오프 ui.jsx 대응)
  features/             화면 코드 — chat · contrib · drive · home · onboarding ·
                        roles · schedule · social · tasks · team · tools
  server/               서버에서만 도는 코드 — DB 연결·세션·쓰기 액션과
                        AI·인증·푸시·레이트리밌·파일 저장소
  data/                 읽기 전용 조회(api.ts) · 제품 설정값(catalog.ts)
  lib/                  도메인 타입·MBTI·유틸
  styles/tokens/        디자인 토큰 (색·타이포)
prisma/                 schema.prisma · seed.ts · migrations/
docs/handoff/           디자인 핸드오프 원본 — 여기 있으면 화면이 어디까지 왔는지
                        알 수 있습니다(참고 자료, 빌드에 포함되지 않음)

이 블록은 파일을 다 적은 게 아닙니다. 어느 폴더에 무엇이 들어 있는지 알려 주기 위한 간단한 안내입니다. 화면 번호(07·11·13 등)와의 대응은 docs/handoff/HANDOFF.md 에 있고, 새 폴더를 만들면 굳이 여기를 고칠 필요가 없습니다.

반응형

폭	레이아웃
~599px	뷰포트를 꽉 채우고 하단 5탭으로 이동
600~1023px	본문이 860px 까지만 넓어지고 가운데 정렬 · 하단 탭바 유지
1024px~	탭바가 왼쪽 세로 막대로 바뀌고 본문에 폭을 내줌

폭이 생기면 화면도 그에 맞게 바뀝니다 — 홈은 두 기둥, 드라이브 제출함은 두 줄, 기여도 리포트는 A4 비율, 08 시간표 격자는 칸이 44px 로 커져 최소 탭 영역을 지킵니다.

온보딩은 탭이 없는 집중 흐름이라 넓은 화면에서도 420px 카드로 모읍니다 — 입력칸 하나가 화면 폭만큼 늘어나면 읽기 어렵습니다.

채팅(33번)은 넓은 화면에서 실제로 3분할로 동작합니다.

폭	채팅
~1023px	화면을 한 번에 하나씩 (32 → 19 / 31)
1024px~	목록 + 대화
1280px~	목록 + 대화 + 자료·정보

1024px 에서 세 기둥을 다 펴지 않는 이유는 왼쪽 앱 내비게이션이 232px 을 이미 쓰기 때문입니다 — 거기서 세 기둥을 펴면 대화 칸이 말풍선 한 줄도 못 담습니다.

This is the beginning of the README. Read the rest at the original. Read the full README ↗