PRO-CTCAE 한국어 설문 웹사이트
외래기반 항체-약물 접합체(ADC) 치료를 받는 암 환자의 증상 부담 연구용 온라인 설문입니다.
Next.js(App Router) + Neon Postgres, Vercel 배포.
기능
- 참여신청 (
/register): 신청 저장 후 연구팀에 솔라피 문자 알림. 발송 성공/실패는 관리자 화면에 표시
- 본인확인 (
/): 이름 + 생년월일로 참여자번호 조회 (관리자가 번호를 배정한 신청자만 통과)
- 설문 선택 (
/select): 1. 기본정보(W0) → 2. 증상(PRO-CTCAE) → 3. 삶의 질(EORTC QLQ-C30) 순서
- 기본정보: 처음 한 번만. 제출하면 비활성화
- 증상: 처음엔 자유롭게, 이후 직전 완료일 + 6일부터 다시 열림
- 삶의 질: 처음 한 번(Baseline, 사례비 없음) 열려 있고, 이후 연구참여시작일부터 12주째가 속한 주(월~일)부터 12주마다 반복, 창마다 1회
- 증상 설문 첫 화면에서 '다음 종양내과 외래 일시'(날짜+시간, 리포트 전달일 확인용)를 묻고
clinic_visits에 저장. 기록된 외래 일시가 아직 지나지 않았으면 다시 묻지 않고, 지나면 다음 증상 설문에서 다시 물음. 일정이 없으면 '아직 일정이 잡히지 않았어요'로 넘길 수 있음. 날짜·시간은 달력/시계 입력창 대신 일반 선택 상자(select)라 어디를 눌러도 열림. 환자 대시보드 상단에 다음 외래 표시
- 첫 설문을 시작하면 연구참여시작일이 자동 지정됨 (관리자 화면에서 수정 가능)
- 환자별 링크 (
/s/<토큰>/<w0|pro|qlq>): 관리자 화면에서 환자·설문별 링크를 복사해 전달. 본인확인 없이 바로 해당 설문이 시작됨 (토큰은 64자 무작위, 링크 소지자 = 해당 환자)
- 안내 문자 (Vercel Cron, 매일 10시 KST): 연구참여 확인된 참여자에게 마지막 증상 설문 완료 7일 뒤 설문 링크·적립금 안내 문자 발송. 같은 완료분에는 한 번만 발송. 적립금은 증상 설문 1회당 10,000원 + 삶의 질 설문 완료 시 10,000원 추가
- 미응답 알림: 안내 문자 발송 1일(24시간) 뒤에도 증상 설문이 없으면
FOLLOWUP_NOTIFY_TO 번호로 "연락 필요" 문자 (환자별 1회)
- 진료용 요약 PDF (1쪽, 교수님이 요약만 볼 수 있게 간결하게): 환자 대시보드의
진료용 PDF 버튼(브라우저 인쇄 → PDF로 저장) 또는 npm run report -- <참여자번호> [--date YYYY-MM-DD] [--lang en] [--out 폴더](영문판: 증상·응답은 NCI 영어 원문)(기본은 preview/ 폴더에 HTML·PDF 생성, Chrome/Edge 필요). 구성: ① 현재 Grade 3 증상 ② 직전 설문보다 Grade가 올라간 증상 ③ 증상 부담 추이(설문별 Grade 분포) ④ 증상별 변화(설문 3회 이상일 때만: Grade 2 이상이었거나 변화가 있던 증상의 1→2→3회차 Grade 궤적, ▲▼) ⑤ PRO-CTCAE 증상부담 요약(Grade 3 개수·새로 Grade 3·일상 방해 “상당히” 이상·호전). 연구자 노트 원문은 인쇄하지 않고 API로도 보내지 않으며, 노트에 증상명(또는 별칭, 예: 불안·어지러)이 언급되면 그 증상을 요약 목록 맨 앞에 두고 ★을 붙임(로컬 문자열 매칭). 같은 데이터면 HTML이 동일하게 재현되며 푸터에 자료 ID가 찍힘
- 접수 확인 문자: 참여신청 직후 신청자에게 "곧 연락드리겠습니다" 문자 (같은 번호는 24시간에 1회)
- 성별별 문항: 참여신청 때 성별을 받고(관리자 화면에서도 수정), 성별에 해당하지 않는 PRO-CTCAE 문항(여성 전용 생리·질 4문항, 남성 전용 발기·사정 2문항)은 설문에서 자동으로 빠지고 관리자 대시보드·진료용 요약에서는 "해당없음"으로 처리. 성별 미입력이면 전 문항 표시
- PRO-CTCAE (
/survey): 80개 증상 항목·124문항을 영역별로 표시
- 선택할 때마다 자동 저장, 중간에 나가도 다시 들어오면 이어서 진행 (미완료 세션 재사용, 기한 없음)
- "이 영역 증상이 모두 없었어요" 버튼, 미응답 문항 표시
- 고령 환자용 UI (큰 글씨·큰 버튼·고대비). 문항·선택지 문구와 증상별 묶음은 NCI 원문 그대로 유지
- 문의 버튼: 설문 중 연구팀에 메시지 전송
- 관리자 (
/admin, 아이디+비밀번호 로그인): 환자 선택(001 (이름) 형식) → 환자 대시보드(Composite grading / 전체 124문항 토글, CSV), 참여신청(번호 배정·문자알림 상태·연구참여 확인·연구참여시작일·설문 링크 복사), 환자 문의
구조
- 모든 DB 접근은 서버 액션에서만 실행됩니다. 브라우저에는 DB 접속 정보가 전달되지 않습니다.
src/lib/actions.ts — 환자용 (입력값 검증 포함, 세션 UUID가 해당 세션 쓰기 권한 역할)src/lib/adminActions.ts — 관리자용 (각 액션이 관리자 쿠키를 직접 확인)src/lib/db.ts — Neon 클라이언트 (서버 전용)
db/schema.sql — 전체 스키마 (재실행 가능)
시작하기
npm install
cp .env.local.example .env.local # 값 채우기
npm run dev
스키마는 Neon 콘솔 SQL Editor에서 db/schema.sql을 실행해 만듭니다.
환경변수
| 이름 | 용도 |
|---|
DATABASE_URL | Neon 접속 (Vercel Neon 연동이 자동 등록) |
ADMIN_USERNAME | /admin 로그인 아이디 (기본값 admin) |
ADMIN_PASSWORD | /admin 로그인 비밀번호 |
SOLAPI_API, SOLAPI_SECRET | 참여신청 문자 알림 |
SMS_SENDER | 솔라피에 등록된 발신번호 |
SMS_NOTIFY_TO | 참여신청 알림 수신번호(쉼표 구분) |
FOLLOWUP_NOTIFY_TO | 미응답 알림을 받을 연구자 번호(쉼표 구분) |
ANTHROPIC_API_KEY | (선택, 현재 진료용 PDF에는 사용하지 않음) 노트 요약 자동 생성용. 노트 원문이 Anthropic API로 전송되므로 동의 범위 확인 필요 |
CRON_SECRET | Vercel Cron이 /api/cron/reminders를 호출할 때 쓰는 비밀값 (미설정 시 호출 거부) |
SITE_URL | (선택) 안내 문자 링크의 기준 주소. 기본값 https://cancerpatient.vercel.app |
안내 문자 대상 확인: GET /api/cron/reminders?dry=1 (Authorization: Bearer $CRON_SECRET) — 발송 없이 대상만 조회합니다.
배포
main 브랜치에 push하면 Vercel이 자동 배포합니다.
라이선스
PRO-CTCAE™ 문항은 미국 국립암연구소(NCI)가 개발한 도구입니다. NCI의 이용약관을 따릅니다.
