📝 달레 스터디 피드백

스터디 참가자 피드백을 한곳에 모으는 사이트. https://feedback.dalestudy.com

스터디·프로젝트(dalestudy.com/programs 의 프로그램) 리더마다 다른 도구로 피드백을 받다 보니 지난 기수 피드백을 찾기도, 기수 간 비교도 어려웠다. GitHub 로그인으로 중복 응답을 막고, 응답은 D1 에 쌓는다.

구조

• TanStack Start (React) on Cloudflare Workers
• D1 (SQLite) + Drizzle
• daleui 디자인 시스템
• 로그인: DaleStudy GitHub App 의 user-to-server OAuth

surveys ─┬─ questions
         ├─ responses ─ answers
         └─ survey_editors (survey_id, login)  ← 설문을 고치고 결과를 보는 사람
users ─ sessions                               ← users.can_create_surveys: maintainer 팀이면 새 설문을 만든다

관계와 설계 이유는 docs/erd.md, 테이블별 컬럼과 예시 행은 docs/tables.md 에 있다. 무엇을 왜 그렇게 정했고 무엇을 감수했는지는 docs/decisions.md 에 날짜순으로 쌓는다. 미뤄둔 일도 그 문서 끝에 있다.

설문은 기수나 프로그램에 매이지 않는다. 맥락은 제목("블로그 스터디 1기 참여 회고")이 담는다. 공개 범위(listed)가 "홈에 보이기" 면 로그인한 누구나 홈에서 보고, "링크로만" 이면 링크로만 들어온다.

참가자 명단은 두지 않는다. 설문 링크는 해당 프로그램 채널에만 공유되고, 답하려면 GitHub 로그인이 필요하며, 같은 사람의 중복 응답은 막히므로 명단이 주는 추가 안전이 Discord↔GitHub 매핑을 유지하는 비용보다 작다.

응답은 responses.user_id 로 GitHub 계정과 함께 저장한다. 결과 화면은 누가 답했는지 보여 주지 않고 답만 모은다.

개발

bun install
bun run cf-typegen          # wrangler.jsonc 바뀔 때마다
bun run db:migrate:local
bun run db:seed:local seed/example.json
bun run dev                 # http://localhost:3000

로컬 시크릿은 .dev.vars 에 둔다 (git 에 올라가지 않음).

GITHUB_CLIENT_ID=...        # DaleStudy GitHub App 의 Client ID
GITHUB_CLIENT_SECRET=...    # 같은 앱의 Client secret

GitHub App 설정의 Callback URL 에 http://localhost:3000/auth/callback 이 등록돼 있어야 한다. __Host- 접두사 쿠키는 Secure 가 필수라 로컬 개발은 localhost 를 secure context 로 취급하는 Chrome/Firefox 에서 한다.

설문 만들기

DaleStudy 조직의 maintainer 팀 멤버가 로그인하면 헤더에 관리 탭(/manage)이 생기고 새 설문을 만들 수 있다. 팀 멤버인지는 로그인할 때 GitHub 에 물어 users.can_create_surveys 에 적는다 — 팀이 바뀌면 다음 로그인 때 반영된다. 설문의 편집자로 추가된 사람에게도 관리 탭이 보인다(자기 설문만).

새 설문은 제목과 설명만 받고, id 는 자동으로 만든다(/V1StGXR8, nanoid 8자). 나머지는 편집 화면에서 정한다.

• 문항 탭: 왼쪽 목록 · 가운데 편집 · 오른쪽 응답 화면 미리보기. 공통 문항을 골라 넣거나(참여 회고 기본 문항 넣기) 직접 쓴다. 공통 문항의 문구는 설문의 공통 문항 변수(vars)로 채워지며 손으로 고칠 수 없다.
• 설정 탭: 설명·마감일·공개 범위·공통 문항 변수·편집자.

응답이 1건이라도 들어오면 문항과 변수는 잠기고 제목·설명·마감일·공개 범위만 고칠 수 있다. 설문 삭제도 응답이 없을 때만 된다.

seed (로컬 개발)

로컬 D1 에 설문을 넣을 때 seed/ 의 JSON 을 쓴다. seed/example.json 이 형식 설명이다. editors 가 편집자, survey.id 를 생략하면 자동으로 만든다.

bun run db:seed:local seed/blog01-final.json

같은 id 의 설문이 이미 있으면 실패한다.

seed 의 문항은 두 종류다.

• { "common": "goal_achieved" } — src/questions/common.ts 의 공통 문항. 모든 프로그램이 같은 key 로 묻는다. 문구 속 {program}, {activity} 같은 자리표시자는 설문의 vars 로 채운다. 프로그램별 값은 docs/questions.md 참고. 설문끼리 비교는 이 key 로 한다. 공통 문항 문구를 고치면 이전 설문과 비교가 깨지므로 신중히.
• { "type": "long", "label": "…" } — 이 설문만의 문항. key 는 비어 있다.

공통 문항은 required 만, 직접 문항은 required(기본 true)와 config 를 줄 수 있다. 유형은 scale, short, long, choice 네 가지. 각 유형의 저장값·검증·config·공통 문항 목록·유형 추가 절차는 docs/questions.md 에 있다.

스키마 바꾸기

# src/db/schema.ts 수정 후
bunx drizzle-kit generate --name <설명>
bun run db:migrate:local

배포

main 에 push 하면 Cloudflare Workers Builds 가 bun run build → npx wrangler deploy 를 실행한다. 다른 브랜치를 push 하면 프리뷰 빌드가 돈다. bun run deploy 는 자동 배포가 안 될 때의 수동 fallback.

이미 설정된 것 (다시 만들 필요 없음):

• D1 feedback (APAC) — id 는 wrangler.jsonc 에 있음
• 시크릿 GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET
• 커스텀 도메인 feedback.dalestudy.com (wrangler.jsonc 의 routes)
• Workers Builds ↔ DaleStudy/feedback 연결. 빌드 변수 BUN_VERSION=1.4.0 (빌드 이미지 기본 bun 1.2.15 는 lockfile v2 를 못 읽는다. 로컬 bun 을 올리면 같이 올린다)
• GitHub App Callback URL: http://localhost:3000/auth/callback, https://feedback.dalestudy.com/auth/callback
• GitHub App 은 공개(public) 여야 한다. 비공개 앱은 소유 조직 멤버만 authorize 할 수 있어서 조직 밖 계정은 GitHub 의 authorize 페이지에서 404 를 본다 (우리 로그엔 아무것도 안 남는다). Advanced → Make public. 참가자를 조직 멤버로 제한하려면 프로그램 참여 절차에 조직 초대가 먼저 들어가야 한다 — 블로그 스터디 1기 참가자의 40% 는 조직 멤버가 아니다.

스키마가 바뀌면 배포 전에 bun run db:migrate:remote 를 직접 실행한다.