Medical Visit QR Signup Sprint — 2026-05-09

요약

의료 본부 issue dc644f93 (진료완료 → star365 가입 + 5,000P) Phase 1 MVP 구현 완료. QR 코드 방식 채택으로 카카오 알림톡/SMS 외부 대행사 의존 0. clinic-emr (kahan:3006) → star365-members (kahan:3720) → star365-hub (paperclip:3400) 3-tier E2E 작동. 트레이딩/UFW/DB DROP 0 영향.

의사결정 흐름

격차 매트릭스 작성 (5 영역 A~E)
(A) 진료완료 트리거: 사용자 결정 — clinic-emr UI 수동 버튼
(B) 알림 채널: ALIGO 키 placeholder 확인, 카카오 KAKAO_CHANNEL_ADMIN_KEY 비어있음 → 알림톡 인프라 미구비 판명 → QR 방식으로 결정 (대행사 가입 영업일 5-7일 우회)
(진행) Phase 1 MVP 우선

구현 (5 작업 단위)

W1: members 서버 medical 토큰 endpoint (kahan `/opt/star365-members/server.mjs`)

DB: medical_visit_tokens 테이블 + 2 인덱스 (postgres user CREATE, star365_svc GRANT)
POST /medical/visit-token — 토큰 발급 (mvt-{16hex}, 24h 만료, atomic INSERT)
GET /medical/visit-token/:token — 토큰 정보 조회 (valid/already_redeemed/expired)
POST /medical/visit-redeem — atomic redeem (FOR UPDATE 락 + member 조회 + unified_point_accounts UPDATE + point_transactions INSERT + journey_events INSERT + token mark redeemed)
백업: server.mjs.bak-medical-20260509
LOC: +5,811 bytes (~89 lines)

W2: clinic-emr 백엔드 (kahan `/opt/clinic-emr/server/routes/star365-token.js`)

신규 라우트 파일 91 LOC
POST /api/star365-token/issue — record_id 또는 appointment_id 받아 환자 정보 조회 + members /medical/visit-token 호출 + signup_url 반환 (인증 필요: doctor/admin)
GET /api/star365-token/:token/qr.png — QR PNG (300x300, errorCorrectionLevel M, Cache 5min, 인증 불필요 — 토큰 자체가 비밀)
의존성: qrcode 추가
env: STAR365_MEMBERS_URL, STAR365_INTERNAL_KEY, CLINIC_ID
백업: index.js.bak-medical-20260509, .env.bak-medical-20260509

W3: clinic-emr UI (kahan `/opt/clinic-emr/src/pages/MedicalRecord.jsx`)

handleSave('signed') 후 confirm → POST /api/star365-token/issue → QR 모달
QR 모달: 환자에게 보여주는 큰 QR + URL 복사 버튼 + 만료시간 표시
vite build PASS (754 KB chunk warning 무시 — 기존 동일)
백업: MedicalRecord.jsx.bak-medical-20260509
LOC: 6,501 → 8,701 bytes

W4: star365-hub (paperclip `/opt/star365-hub/`)

server.mjs: /auth/signup body에 medical_token 받아 가입 후 /medical/visit-redeem 호출 + 응답에 medical_reward 포함. 신규 GET /medical/token-info?mt=xxx proxy endpoint
public/signup.html: ?mt= URL 파라미터 감지 → /medical/token-info 호출 → "🏥 진료 완료 가입 보너스" 배너 + 가입 버튼 라벨 동적 변경 ("가입하고 5,000P 받기") + 가입 후 alert
백업: server.mjs.bak-medical-20260509, signup.html.bak-medical-20260509
안전: medical_token 사용 시 platform='medical' override (기존 platform_memberships 분기 호환)

W5: E2E 검증 + cleanup

의사 진료완료 → 토큰 발급 ✅ (record_id=4, 환자 김영수)
paperclip /medical/token-info 검증 valid ✅
외부 HTTPS https://members.star365.site/auth/signup → 가입 + medical_reward {reward_amount:5000, balance_after:5000} ✅
같은 토큰 재사용 → medical_reward.error="already_redeemed" ✅ (가입 자체는 성공, 5,000P 미지급)
DB 6/6 검증 PASS:
- medical_visit_tokens.redeemed_at SET
- star365_members 신규 (first_platform='medical')
- unified_point_accounts: balance=5000, lifetime_earned=5000, BRONZE
- point_transactions: EARN 5000 HOSPITAL platform, reference_type='medical_visit_token'
- member_journey_events: signup + medical_visit_redeem 2건
- platform_memberships: medical real + 7 shadow (auto-shadow)
테스트 데이터 정리: 테스트 회원 3명/토큰 5개/transactions 2건/journey_events 5건/platform_memberships 24건 일괄 삭제

API 흐름

[의사] clinic-emr UI 서명 완료
   ↓ POST /api/star365-token/issue
[clinic-emr Express :3006]
   ↓ POST kahan:3720/medical/visit-token (x-star365-key)
[star365-members :3720]
   ↓ INSERT medical_visit_tokens
   ↓ return {token, signup_url, expires_at}
[clinic-emr UI] QR 모달 표시 (https://members.star365.site/signup?mt=mvt-...)

[환자] QR 스캔 → 모바일 브라우저
   ↓ GET https://members.star365.site/signup?mt=mvt-...
[star365-hub :3400]
   ↓ GET /medical/token-info?mt=... → kahan /medical/visit-token/:token
[signup.html] 배너 표시 "🏥 5,000P 가입 보너스"
   ↓ 이메일/PW 입력 → POST /auth/signup {email, password, medical_token}
[star365-hub /auth/signup]
   ↓ kahan /register
   ↓ kahan /sso/issue (cookie set)
   ↓ kahan /medical/visit-redeem {token, star365_uid}
[members /medical/visit-redeem] BEGIN
   - SELECT FOR UPDATE token
   - check redeemed/expired → 409/410
   - INSERT/UPDATE unified_point_accounts +5000
   - INSERT point_transactions (EARN, HOSPITAL)
   - INSERT member_journey_events (medical_visit_redeem)
   - UPDATE token redeemed_at
COMMIT
   ↓ 가입 성공 alert "🎉 5,000P 적립" → /me 리다이렉트

안전 점검

✅ 트레이딩 무영향 (gunja-pair-hedge / gate-pair-hedge active 검증)
✅ DB ALTER ADD/CREATE TABLE만 (DROP 0)
✅ nginx vhost 변경 0 (기존 emr.metaquant.club, members.star365.site 재활용)
✅ UFW 변경 0
✅ 5서버 헬스 정상
✅ 토큰 1회용 + 24h 만료 + atomic redeem (이중 지급 방지)
✅ paperclip→kahan 통신은 기존 KAHAN_INTERNAL_KEY 재사용 (신규 키 추가 0)

미해결 / Phase 2 후보

알림톡 발송 채널 (ALIGO/솔라피/NHN 가입 + 비즈채널 연결 + 템플릿 사전등록 영업 5-7일)
진료완료 후 SMS 발송 (QR 외 추가 채널)
"이미 사용된 토큰" UX 개선 (가입은 성공하되 보너스만 누락 → 확실한 안내 필요)
가입자 유입 분석 대시보드 (medical platform 추적)
clinic-emr 외 다른 EMR(sj-clinic, plus365 등) 동일 패턴 적용
ALL_PLATFORMS 리스트에 'medical' 추가 검토 (현재 7 platform shadow + medical real → 8 platform 회원 형식 정합)