얼굴 읽기 관리자 가이드 Face Reading Admin Guide

🏥 환자 허브 — Phase C 통합 시스템 (NEW!)Patient Hub — Phase C Integrated System (NEW!)

환자 허브는 Face Reading + ADHD Catcher + Symptom Catcher + QEEG + 임상 노트를 한 환자 중심으로 통합하는 새 시스템입니다. 기존 Clinic Dashboard의 확장판. Patient Hub is a new system that unifies Face Reading + ADHD Catcher + Symptom Catcher + QEEG + Clinical Notes around each individual patient. An extended version of the existing Clinic Dashboard.

✨ 주요 기능Key Features

• 통합 환자 DB: 이메일, 전화, 생년월일, 선호 언어, 주호소 등 임상 기본 정보Unified patient DB: email, phone, DOB, preferred language, chief complaint
• 모든 모달리티 한눈에: 6개 탭 (Overview / Face / ADHD / Symptom / QEEG / Notes)All modalities at a glance: 6 tabs (Overview / Face / ADHD / Symptom / QEEG / Notes)
• 활동 타임라인: 최근 15개 활동 시간순 통합 표시Activity timeline: recent 15 activities chronologically unified
• 임상 노트: intake/progress/assessment/plan/discharge 종류별Clinical notes: intake/progress/assessment/plan/discharge types
• 이메일 전송: 버튼 한 번으로 Face Reading 결과 HTML 이메일Email delivery: HTML email of Face Reading results in one click

🗄️ DB 테이블 구조DB Table Structure

• patients — 중앙 환자 정보 (확장됨)central patient info (extended)
• face_sessions — Face Reading
• adhd_sessions — ADHD 평가 (스키마 준비, 연결 대기)ADHD assessments (schema ready, wiring pending)
• symptom_sessions — Symptom 평가 (스키마 준비)Symptom assessments (schema ready)
• qeeg_sessions — QEEG (future)
• clinical_notes — 임상 노트clinical notes
• email_logs — 이메일 전송 추적email send tracking
• patient_activity_summary (VIEW) — 환자별 활동 요약per-patient activity summary

🚀 배포 단계 (세라피스트가 할 일)Setup Steps

1. Supabase SQL Editor에서 schema_phase_c_central_db.sql 실행Run schema_phase_c_central_db.sql in Supabase SQL Editor
2. Resend 계정 생성 + API Key 발급Create Resend account + API key
3. Supabase CLI로 Edge Function 배포 (send-face-reading-email)Deploy Edge Function via Supabase CLI
4. GitHub에 patient-hub-v1.html 업로드 → 자동 배포Upload patient-hub-v1.html to GitHub → auto-deploys
5. 상세 가이드: A2_EMAIL_DEPLOY_GUIDE.md 및 CLINICIAN-MANUAL.htmlDetailed guides: A2_EMAIL_DEPLOY_GUIDE.md and CLINICIAN-MANUAL.html

🏗️ 시스템 구조 이해System Architecture

3단계 계산 파이프라인3-Stage Calculation Pipeline

이 시스템의 모든 가중치는 편집 가능해요. 연구 결과와 임상 관찰에 따라 지속적으로 튜닝할 수 있도록 설계됐어요. 하드코딩된 AI 모델이 아니에요. All weights are editable in this system. Designed for continuous tuning based on research and clinical observation. Not a hardcoded AI model.

파일 구조File Structure

🩺 클리닉 대시보드 (Phase B)Clinic Dashboard (Phase B)

접속 URLAccess URL

🔐 로그인Login

현재 비밀번호: bnm2026 (Phase B 임시, 추후 강화 예정) Current password: bnm2026 (Phase B temporary, to be hardened)

👥 환자 등록Patient Registration

1. 왼쪽 패널 "➕ 새 환자 등록" 클릭Click "➕ Add New Patient" on left panel
2. 이름과 메모 입력 (모두 선택사항)Enter name and notes (both optional)
3. "등록" 클릭 → 자동으로 다음 ID 발급 (BNM-002, BNM-003...)Click "Add" → next ID auto-generated (BNM-002, BNM-003...)
4. 환자에게 코드 알려주기 → 환자가 face-reading에 입력하면 자동 저장Give code to patient → results auto-save when they use face-reading

📊 환자 상세 화면Patient Detail View

• 최근 분석 요약: 가장 최근 세션의 Big Five 5개 점수Latest Summary: Most recent session's Big Five scores
• 주요 증상 Top 3: 가장 강한 증상 경향Top 3 Symptoms: Strongest tendencies
• 시간별 변화 그래프: Big Five / 증상 / 감정 3가지 차트 전환 가능Trends Chart: Switch between Big Five / Symptoms / Emotion
• 전체 세션 기록: 모든 분석 시간순 + 세션 삭제 가능All Sessions: Chronological + deletable

💾 데이터베이스 (Supabase)Database (Supabase)

Supabase 프로젝트 URL: Supabase project URL:

두 개의 테이블: Two tables:

• patients — 환자 정보 (id, name, notes, created_at)Patient info
• face_sessions — 분석 세션 (Big5, risks JSON, emotion, wuxing, FACS 등)Analysis sessions (Big5, risks JSON, emotion, wuxing, FACS etc)

🚀 앞으로 (Phase C)Roadmap (Phase C)

• 진짜 인증 시스템 (이메일 + 비밀번호)Real authentication (email + password)
• Row Level Security 강화Hardened Row Level Security
• QEEG 결과와 통합Integration with QEEG results
• AI 적응형 프로토콜 추천AI adaptive protocol recommendations
• HIPAA BAA (필요시 Supabase Pro $25/월)HIPAA BAA (Supabase Pro if needed, $25/mo)

🎛️ 관리자 페이지 둘러보기Admin Panel Tour

face-admin-v3.1.html은 8개 탭으로 구성되어 있어요: face-admin-v3.1.html has 8 tabs:

📊 Linkage Matrix 편집Editing Linkage Matrix

가중치 해석법How to Read Weights

• 양수 (+): 특성이 높을수록 증상 위험도 ↑ (예: 신경증 0.55 → 우울)Positive (+): Higher trait → higher risk (e.g., N=0.55 → depression)
• 음수 (−): 특성이 높을수록 증상 위험도 ↓ (보호 요인, 예: 성실성 −0.25 → 우울)Negative (−): Higher trait → lower risk (protective, e.g., C=−0.25 → depression)
• 0: 연관 없음Zero: No relationship
• 범위: -1.0 ~ +1.0 (관례적으로 ±0.7 이상은 강한 연관, ±0.3~0.7은 중간, ±0.3 이하는 약함)Range: -1.0 to +1.0 (convention: |0.7|+ strong, |0.3-0.7| moderate, |0.3| or less weak)

색상 코딩Color Coding

• 🌸 분홍: 양의 연관 (특성↑→증상↑)🌸 Pink: Positive association
• 💜 보라: 음의 연관, 큰 절댓값 (보호 요인)💜 Purple: Negative, large magnitude (protective)
• 🌿 민트: 음의 연관, 중간🌿 Mint: Negative, moderate

새 증상 추가Adding New Symptoms

1. 🏥 Symptoms 탭으로 이동Go to 🏥 Symptoms tab
2. "새 증상 추가" 섹션에서 ID (snake_case), 한국어명, English name, Category 입력In "Add New Symptom" section, enter ID (snake_case), Korean name, English name, Category
3. ID 명명 규칙: 영문 소문자 + 언더스코어 (예: social_anxiety)ID naming: lowercase + underscore (e.g., social_anxiety)
4. "➕ 추가" → 자동으로 모든 매트릭스에 해당 컬럼 생성됨"➕ Add" → Column auto-created in all matrices
5. 🌸 Big5 → Sym 탭으로 가서 새 증상의 Big5 가중치 입력 (연구 근거 참고)Go to 🌸 Big5 → Sym tab, enter Big Five weights (see research references)
6. "💾 저장" 눌러 반영Click "💾 Save"

커스텀 임상 규칙 (Custom Rules)Custom Clinical Rules

매트릭스로 표현하기 어려운 복합 조건 패턴에 사용해요. 예: 성실성↑ + 신경증↑ + mouth press↑ = burnout 가중치 +0.25 For complex conditional patterns hard to express in matrices. Example: high C + high N + high mouth press = burnout boost +0.25

사용 가능한 condition keys: Available condition keys: C_high, C_low, N_high, N_low, E_high, E_low, O_high, O_low, A_high, A_low, mouth_press_high, AU15_high, AU4_high, AU1_high, asymmetry_high, sanjeong_imbalance_high, fWHR_high, tired_eyelids_high

🚀 배포 워크플로Deployment Workflow

Linkage Matrix JSON 배포 (전체 워크플로)Linkage Matrix JSON Deployment

상세 단계별 가이드Detailed Step-by-Step

Step 1-2: Admin에서 편집 & 다운로드Edit & Download in Admin

1. 브라우저에서 face-admin-v3.1.html 열기Open face-admin-v3.1.html in browser
2. 원하는 탭에서 수정Make changes in desired tab
3. 각 섹션의 "💾 저장" 클릭 (브라우저 localStorage 저장)Click "💾 Save" in each section (saves to browser localStorage)
4. 💾 I/O 탭으로 이동 → 📥 다운로드 클릭Go to 💾 I/O tab → click 📥 Download
5. face-linkage-matrix.json 파일이 다운로드됨face-linkage-matrix.json file downloaded

Step 3: GitHub 업로드GitHub Upload

1. GitHub 저장소 열기: bostonneuromind/neurocatchersOpen GitHub repo: bostonneuromind/neurocatchers
2. 경로로 이동: symptom_catcher/face-reading/config/Navigate to: symptom_catcher/face-reading/config/
3. "Add file" → "Upload files" 클릭Click "Add file" → "Upload files"
4. 다운로드한 face-linkage-matrix.json 드래그 앤 드롭Drag and drop the downloaded face-linkage-matrix.json
5. Commit message 작성 (예: "Update linkage matrix - added social_anxiety")Write commit message (e.g., "Update linkage matrix - added social_anxiety")
6. "Commit changes" 클릭Click "Commit changes"

Step 4: 자동 배포 확인Verify Auto-Deploy

1. GitHub Actions 탭에서 배포 진행 확인 (약 2-5분)Check GitHub Actions tab for deployment progress (2-5 min)
2. 초록색 체크 ✓ 뜨면 배포 성공Green checkmark ✓ means deployment succeeded
3. 실제 사이트 확인: https://neurocatchers.com/symptom_catcher/face-reading/face-reading-v3.2.htmlVerify live: https://neurocatchers.com/symptom_catcher/face-reading/face-reading-v3.2.html
4. 브라우저 캐시 문제시 Ctrl+Shift+R (강제 새로고침)For cache issues: Ctrl+Shift+R (hard refresh)

🎯 임상 튜닝 가이드Clinical Tuning Guide

튜닝 원칙Tuning Principles

1. 연구 우선: 가능한 한 연구 근거(Kotov 2010, Kachur 2020 등) 사용Research first: Use research basis (Kotov 2010, Kachur 2020) when possible
2. 임상 관찰로 보완: 실제 사례에서 반복 관찰되는 패턴만 custom rules에 추가Clinical observation supplements: Only add repeatedly observed patterns to custom rules
3. 작게 시작: 새 가중치는 ±0.2 정도로 시작, 점진적 조정Start small: Begin new weights around ±0.2, adjust gradually
4. 한 번에 하나: 여러 변경을 동시에 하면 효과 추적 불가One at a time: Multiple simultaneous changes prevent effect tracking
5. 검증 케이스: 알려진 프로파일의 테스트 사진으로 결과 검증Validation cases: Verify with known-profile test photos

Fusion 가중치 (α, β) 조정Fusion Weights (α, β)

튜닝 체크리스트Tuning Checklist

• ☐ 변경 전 JSON 백업했나요?☐ Backed up JSON before change?
• ☐ 변경의 연구 근거 또는 임상 근거가 있나요?☐ Research or clinical basis for change?
• ☐ 하나의 증상/특성만 변경했나요?☐ Only one symptom/trait modified?
• ☐ 변경 후 사용자 페이지에서 실제 테스트했나요?☐ Tested on actual user page?
• ☐ Commit message에 변경 이유 명시했나요?☐ Commit message explains reason?

📚 연구 근거 참고Research References

핵심 문헌 (튜닝 근거)Core Literature (tuning basis)

• Ekman, P. & Friesen, W.V. (1978). Facial Action Coding System (FACS). Consulting Psychologists Press. — FACS의 원본 체계— Original FACS system
• Kotov, R. et al. (2010). Linking 'big' personality traits to anxiety, depressive, and substance use disorders: A meta-analysis. Psychological Bulletin, 136(5), 768-821. — Big5 × 증상 연관성의 메타분석 핵심— Core meta-analysis for Big5 × symptom
• Kachur, A. et al. (2020). Assessing the Big Five personality traits using real-life static facial images. Scientific Reports, 10, 8487. — 얼굴 → Big5 예측 (N=12,447)— Face → Big5 prediction (N=12,447)
• Cai, L. & Liu, X. (2022). Identifying Big Five personality traits based on facial behavior analysis. Frontiers in Public Health, 10, 1001828.
• Widiger, T.A. (2009). Neuroticism. In Handbook of Individual Differences in Social Behavior.
• Miller, J.D. & Lynam, D. (2001). Structural models of personality and their relation to antisocial behavior: A meta-analytic review. Criminology, 39(4), 765-798.
• Min, S.K. (2008). Clinical correlates of Hwa-Byung and a proposal for a new anger disorder. Psychiatry Investigation, 5(3), 125-141. — 화병 임상 연구 (한국 문화 증후군)— Hwabyeong clinical research (Korean culture-bound syndrome)
• Martel, M. (2010). Research on ADHD and Big Five personality.
• Carré, J.M. & McCormick, C.M. (2008). In your face: facial metrics predict aggressive behaviour in the laboratory. — fWHR 연구— fWHR research

Kotov (2010) 주요 효과 크기Kotov (2010) Key Effect Sizes

효과 크기 (Cohen's d): ±0.2 작음, ±0.5 중간, ±0.8 큼. ⭐ = 가장 강한 연관. 현재 시스템은 이 값을 -1~+1로 정규화해 사용. Effect sizes (Cohen's d): ±0.2 small, ±0.5 medium, ±0.8 large. ⭐ = strongest links. System normalizes these to -1~+1 range.

🔧 문제 해결Troubleshooting

배포 후 변경사항이 안 보여요Changes not showing after deployment

1. GitHub Actions에서 초록 체크 확인 (배포 완료?)Check green checkmark in GitHub Actions (deployment complete?)
2. 브라우저 강제 새로고침: Ctrl+Shift+R (Win) / Cmd+Shift+R (Mac)Hard refresh: Ctrl+Shift+R (Win) / Cmd+Shift+R (Mac)
3. CloudFront 캐시가 5-10분 남아있을 수 있음 — 기다려주세요CloudFront cache may persist 5-10 min — wait
4. 여전히 안 보이면 시크릿 창(incognito)에서 확인If still not showing, try incognito window

Admin 페이지 수정이 사용자 페이지에 반영 안 돼요Admin edits not reflecting in user page

• 원인: Admin은 브라우저 localStorage에만 저장. JSON 다운로드 & GitHub 업로드 빠뜨림.Cause: Admin only saves to browser localStorage. Missed JSON download & GitHub upload.
• 해결: 💾 I/O 탭에서 📥 다운로드 → GitHub의 config/face-linkage-matrix.json에 업로드Solution: 💾 I/O tab → 📥 Download → upload to GitHub's config/face-linkage-matrix.json

"얼굴을 찾지 못했어요" 오류가 자주 나요"Face not found" error is frequent

• 원인 1: 사진이 어둡거나 흐릿함 → 사용자에게 사진 가이드 안내Cause 1: Dark/blurry photo → guide user to photo guide
• 원인 2: 옆모습이거나 얼굴이 잘렸음 → 정면 사진 권장Cause 2: Side view or cropped face → request front-facing
• 원인 3: MediaPipe 모델 로드 실패 → 네트워크 확인, 페이지 새로고침Cause 3: MediaPipe load fail → check network, refresh

JSON 불러오기 오류JSON Import Error

• 형식 검증 실패: symptoms와 bigfive_to_symptom이 있어야 함 (최소 필수 필드)Format check fail: must have symptoms and bigfive_to_symptom (min required)
• JSON syntax 오류: 콤마·대괄호 확인. jsonlint.com에서 검증JSON syntax error: check commas/brackets. Validate on jsonlint.com

🌿 끝맺는 말Closing Note

이 시스템은 살아있는 도구예요. 임상 사례가 쌓일수록, 연구가 업데이트될수록 계속 정교해지도록 설계됐어요. 당신의 튜닝이 환자·내담자의 더 깊은 이해로 이어지기를 🕊️ This system is a living tool. Designed to grow more refined as clinical cases accumulate and research updates. May your tuning lead to deeper understanding of patients and clients 🕊️

— Boston Neuromind · Canton, MA
v3.1 · 2026.04 — Boston Neuromind · Canton, MA
v3.1 · April 2026