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의 이용약관을 따릅니다.