검사도구 만들기

Clinic-OS의 검사도구는 /ext/survey-tools/{toolId} 형태로 열리는 자가진단/설문/결과 흐름입니다.

사람이 구조를 외우기보다, 에이전트가 아래 기준으로 진행하는 것이 맞습니다.

언제 검사도구가 맞나요?

간단한 자가진단이나 설문을 만들고 싶을 때
검사 결과 페이지와 인쇄 리포트가 필요할 때
환자 상세 화면과 연결되는 결과 저장이 필요할 때

원장·관리자가 먼저 정할 질문

코드를 만들기 전에 아래 운영 결정을 먼저 에이전트에게 알려주세요.

이 도구는 방문자가 스스로 참고하는 공개 안내용인가, 진료 과정에서 쓰는 원내용인가?
결과만 보여줄 것인가, 사용자가 원할 때 문의 흐름도 함께 제공할 것인가?
이름·연락처처럼 개인을 식별하는 정보가 정말 필요한가?
결과 문구가 질환을 진단하거나 치료 효과를 단정하는 표현처럼 보이지 않는가?
누가 결과 문구를 검토하고, 어떤 상황에서 다시 갱신할 것인가?

공개 검사도구는 모든 사용자를 문의로 바꾸는 장치가 아닙니다. 검사 자체로 유용해야 하며, 개인정보는 목적에 필요한 범위에서만 받도록 설계합니다. 결과는 참고 정보와 다음 확인 질문을 제공하고, 진료 판단을 대신하는 표현은 피합니다.

/guides/survey-builder의 기존 입문 안내는 이 문서로 통합되어 있습니다. 관리자 관점의 목적과 공개 범위를 먼저 정한 뒤 아래 기술 절차로 이어가면 됩니다.

작업 위치

로컬 클리닉 전용 검사도구는 여기에서 만듭니다.

src/survey-tools/local/{toolId}/

우선순위는 local > store > core 입니다.

로컬에서 새 검사도구를 시작할 때는 에이전트가 아래 명령으로 스캐폴드를 먼저 만드는 편이 안전합니다.

npm run survey-tool:create -- --id burnout-check --mode manifest --dry-run --json

실제 생성:

npm run survey-tool:create -- --id burnout-check --title "번아웃 자가진단" --mode hybrid --with-report

검증:

npm run survey-tool:check -- --id burnout-check --json

스토어에서 받은 검사도구는 에이전트가 아래 경로에 자동으로 설치해야 합니다.

src/survey-tools/store/{toolId}/

사람이 HQ에서 manifest.json 을 내려받아 손으로 복사하는 방식은 더 이상 권장하지 않습니다.

스토어 설치

기본 흐름은 다음 둘 중 하나입니다.

관리자 화면: /admin/surveys/tools/store 에서 설치
에이전트 명령: npm run survey-tool:install -- --id {toolId}

먼저 계획만 확인하려면:

npm run survey-tool:install -- --id burnout-check --dry-run --json

실제 설치는:

npm run survey-tool:install -- --id burnout-check

패키지에 migration.sql 또는 seed.sql 이 있으면 로컬 D1에도 같이 적용됩니다.

기본 구조

src/survey-tools/local/stress-check/
├── manifest.json
├── survey.astro
├── result.astro
└── report.astro

필수는 manifest.json 이고, 나머지는 필요할 때만 추가합니다.

두 가지 방식

1. 데이터 기반 검사

질문과 점수 계산이 단순하면 manifest.json 에 questions 와 scoring 을 넣는 방식이 가장 빠릅니다.

이 방식에서도 다음 로직을 쓸 수 있습니다.

options[].score 로 표시값과 실제 점수를 분리
reverseScored: true 로 역채점 문항 처리
weight 로 문항 가중치 부여
maxScore 로 문항별 최대 점수 고정
scoring.interpretation 으로 결과 구간과 문구 정의

기본 렌더러 지원 질문 타입:

info
radio
checkbox
select
text
textarea
number
nrs

2. 커스텀 검사

브랜딩, 애니메이션, 복잡한 입력 흐름이 필요하면 survey.astro, result.astro, report.astro 를 직접 만듭니다.

혼합 모드도 가능합니다.

survey.astro 만 두면 커스텀 검사지 + 기본 결과/리포트
result.astro 만 두면 기본 검사지 + 커스텀 결과
report.astro 만 두면 기본 검사지/결과 + 커스텀 결과지

필요하면 manifest 에 useCustomSurvey, useCustomResult, useCustomReport 로 개별 제어할 수 있습니다.

검증 경로

에이전트는 최소한 아래를 확인해야 합니다.

npm run build
/ext/survey-tools/{toolId}
검사 제출 후 /result/{resultId}
필요 시 /report/{resultId}
환자 연결이 있으면 환자 상세 화면 진입 흐름

하지 말아야 할 것

src/plugins/survey-tools/ 를 직접 수정하지 않기
루트 migrations/ 를 검사도구용으로 수정하지 않기
코드에서 직접 참조하는 썸네일/로고를 관리자 업로드로만 해결하지 않기

에이전트에게 이렇게 요청하면 됩니다

"불면 검사도구를 로컬 survey-tools로 만들어줘"
"manifest 기반으로 가능한지 먼저 보고, 복잡하면 custom renderer로 만들어줘"
"검사 제출부터 결과 페이지까지 로컬에서 검증해줘"