first commit

???????_???? _개발설명서 (1).md

@@ -0,0 +1,238 @@
+# 지역사회간호학 「개념 우주」 개발 설명서
+
+작성일: 2026-10-06  
+용도: 공동 연구 개발자와 화면 설계 및 구현 범위를 논의하기 위한 문서  
+함께 볼 파일: `지역사회간호학_개념우주_와이어프레임.html`
+
+> 교과서의 전체 색인을 ‘탐색 가능한 개념 지도’로 바꾸는 학습 사이트입니다. 학생이 용어의 뜻을 이해하고, 그 용어가 어느 주제에 속하며 다른 개념과 어떻게 연결되는지 확인하도록 돕습니다. 우주를 시각적 표현으로 사용하며, AI 대화 기능을 전제로 하지 않습니다.
+
+## 1. 개발의 출발점
+
+학생들은 교과서에 나오는 용어의 뜻을 충분히 알지 못해 본문을 읽거나 학습 내용을 연결하는 데 어려움을 겪습니다. 정확한 용어를 모르면 일반적인 색인이나 검색창도 활용하기 어렵습니다.
+
+이 사이트가 돕고자 하는 학습은 다음 세 가지입니다.
+
+- **뜻 이해:** “이 용어는 무슨 뜻인가?”
+- **위치 이해:** “이 용어는 교과서의 어느 영역에 속하는가?”
+- **관계 이해:** “다른 용어와 어떤 관계이며, 무엇을 함께 살펴보면 좋은가?”
+
+장기적인 범위는 **교과서 전체 색인**입니다. 현재 와이어프레임의 25개 용어는 화면과 상호작용을 보여주기 위한 예시이며, 최종 수록 범위를 뜻하지 않습니다.
+
+## 2. 현재 대화에서 정한 방향과 개발 제안
+
+| 구분 | 내용 |
+| --- | --- |
+| 정한 방향 | 지역사회간호학 교과서를 기반으로 제작 |
+| 정한 방향 | 전체 색인을 마인드맵처럼 탐색하고 개념의 관계를 확인 |
+| 정한 방향 | 우주, 은하, 별, 행성을 떠올리게 하는 화면 |
+| 정한 방향 | AI 기반 질문 해석이나 챗봇을 전제로 하지 않는 사이트 |
+| 정한 방향 | 용어 검색과, 정확한 명칭을 몰라도 주제를 따라 찾아가는 탐색을 함께 제공 |
+| 확보 가능한 원자료 | 교과서 PDF. 실제 파일은 아직 이 시안에 반영되지 않음 |
+| 아래 문서의 제안 | 데이터 필드, 관계 유형, 검수 절차, 단계별 구현 및 검증 기준 |
+
+데이터 구조와 세부 구현은 개발자와 협의할 제안입니다. 특정 프레임워크, 서버, 데이터베이스 또는 배포 서비스는 아직 정하지 않았습니다.
+
+## 3. 우주 표현의 의미
+
+| 화면 요소 | 학습상 의미 | 구현 시 유의점 |
+| --- | --- | --- |
+| 전체 우주 | 교과서의 전체 개념 구조 | 처음에는 큰 영역이 읽혀야 함 |
+| 은하 | 단원 또는 큰 주제별 묶음 | 실제 교과서 목차에 맞춰 조정 |
+| 행성처럼 보이는 중심 | 해당 주제를 여는 버튼 | 현재 시안에서는 별도의 개념 계층을 뜻하지 않음 |
+| 별 | 개별 용어 | 용어를 누르면 설명과 연결 개념을 표시 |
+| 별 사이 연결선 | 정의된 개념 관계 | 연결 이유를 짧은 문구로 제시 |
+| 배경의 작은 빛과 타원 궤도 | 공간감을 위한 장식 | 학습 개념이나 개념 관계와 시각적으로 구분 |
+
+**우주 표현은 개념을 찾고 연결을 이해하도록 돕는 장치입니다.** 별의 크기나 밝기를 성적, 중요도, 학습 완료 정도로 해석하게 하려면 별도 기준이 필요합니다. 현재 시안에서 밝은 별은 선택한 용어를 나타냅니다.
+
+화면상의 거리는 현재 배치상의 거리입니다. 두 별이 가깝다는 이유만으로 개념적 유사성이 높다고 해석하게 해서는 안 됩니다. 소속 주제는 묶음으로, 구체적인 관계는 이름이 붙은 선으로 전달합니다.
+
+## 4. 핵심 사용자 흐름
+
+### A. 용어를 알고 있는 학생
+
+1. 검색창에 용어 전체 또는 일부를 입력합니다.
+2. 검색 결과에서 용어와 소속 주제를 확인합니다.
+3. 용어를 선택하면 해당 은하가 펼쳐지고 선택한 별이 강조됩니다.
+4. 쉬운 설명, 사례, 연결된 개념을 확인합니다.
+5. 연결된 개념을 눌러 탐색을 이어갑니다.
+
+### B. 정확한 용어를 모르는 학생
+
+1. 전체 우주에서 큰 주제와 그 옆의 쉬운 설명을 살펴봅니다.
+2. 자신이 배우는 내용에 가까운 은하를 선택합니다.
+3. 펼쳐진 용어를 누르며 설명을 확인합니다.
+4. 찾던 개념을 확인한 뒤 주변 개념으로 이동합니다.
+
+예를 들어 ‘지역사회 간호과정’이라는 이름만으로 판단하기 어려운 학생에게는 ‘문제를 찾고, 해결하고, 돌아보기’라는 보조 설명이 진입점을 제공합니다. 이런 보조 설명도 교재와 교수자의 검토를 거쳐 확정해야 합니다.
+
+### C. 두 용어의 관계를 알고 싶은 학생
+
+현재 시안에서는 한 용어의 ‘연결된 개념’을 눌러 관계를 확인합니다. 두 용어를 동시에 선택해 경로를 강조하는 기능은 **후속 검토 항목**입니다. 개발한다면 등록된 관계만 활용하고, 직접 연결이 없거나 중간 개념을 거치는 경우를 구분해야 합니다.
+
+## 5. 검색 기능의 범위: AI 없이 무엇을 할 것인가
+
+검색은 준비된 데이터의 문자열을 찾는 기능입니다. 학생의 자유로운 질문을 이해하거나 새로운 설명을 생성하지 않습니다.
+
+| 검색 방식 | 현재 시안 | 실제 개발 시 고려할 점 |
+| --- | --- | --- |
+| 정식 용어의 일부 입력 | 지원 | ‘우선’ → ‘우선순위 설정’처럼 부분 일치 |
+| 등록된 동의어·검색 표현 | 지원 | 교수자가 검수한 표현을 용어에 연결 |
+| 설명 속 단어 검색 | 지원 | 입력한 단어가 등록된 설명에 포함되면 후보 표시 |
+| 대소문자·일부 공백 차이 처리 | 지원 | 한글·영문·약어의 정규화 규칙 정리 |
+| 여러 단어 입력 | 단어별 일치 결과를 합쳐 표시 | 현재는 단어 중 하나만 일치해도 후보가 될 수 있음 |
+| 임의의 문장 의미 이해 | 미지원 | ‘뭐부터 해결하지?’를 자동 해석한다고 안내하지 않음 |
+| 오타 교정·초성 검색 | 미지원 | 필요할 경우 별도의 규칙 기반 기능으로 검토 |
+| AI가 되묻거나 답변 생성 | 미지원 | 현 개발 범위에 포함하지 않음 |
+
+현재 시안은 용어명 일치에 우선순위를 주고, 동의어와 설명의 일치도 함께 사용합니다. 결과는 최대 6개를 보여줍니다. 전체 색인을 넣을 때는 전체 결과 보기나 추가 결과 표시가 필요합니다.
+
+검색창 안내는 **‘용어·설명 속 단어로 찾기’**처럼 실제 기능과 일치시킵니다. 결과가 없으면 짧은 단어로 다시 찾거나 은하를 선택하도록 안내합니다. 질문형 입력을 받는 것처럼 보이는 채팅창은 사용하지 않습니다.
+
+## 6. 용어 상세 화면에서 보여줄 내용
+
+현재 시안의 상세 화면은 다음 순서로 구성되어 있습니다.
+
+1. 소속 주제와 정식 용어
+2. 함께 찾는 표현
+3. 쉬운 뜻
+4. 개념을 떠올리는 데 도움이 되는 짧은 사례
+5. 연결된 개념과 연결 이유
+6. 해당 은하 또는 전체 우주로 이동하는 버튼
+
+실제 교재를 반영할 때는 **교과서 정의, 쉬운 설명, 사례를 구분**하는 것을 제안합니다. 원문 표현과 교수자가 풀어 쓴 설명이 혼동되지 않도록 합니다. 교과서 위치도 단원과 페이지로 연결하면 학생이 본문으로 돌아갈 수 있습니다.
+
+여러 단원에 등장하는 용어는 여러 개로 복제하기보다 하나의 개념에 여러 소속 단원과 출처를 연결하는 것이 좋습니다. 이름이 같아도 의미가 다른 용어는 구분이 필요합니다.
+
+## 7. 데이터 구조 제안
+
+화면 배치와 학습 내용을 분리합니다. 설명을 고치거나 교과서를 바꿀 때 화면 코드를 직접 수정하지 않도록, 용어와 관계를 JSON 등 별도의 구조화된 데이터로 관리하는 방향입니다.
+
+| 데이터 | 주요 필드 | 목적 |
+| --- | --- | --- |
+| 교재 | `book_id`, 제목, 판, 출판연도 | 서로 다른 판의 내용과 페이지를 구분 |
+| 단원·주제 | `chapter_id`, 제목, 쉬운 보조 설명, `parent_id` | 목차 구조와 은하 구성 |
+| 용어 | `term_id`, 정식 명칭, 동의어, 약어, 검색 표현 | 검색과 동일 개념 식별 |
+| 용어 설명 | 교재 정의, 쉬운 설명, 사례 | 상세 화면 구성 |
+| 소속 | `term_id`, `chapter_ids` | 여러 단원에 등장하는 개념 처리 |
+| 출처 | `book_id`, 단원, PDF 페이지, 인쇄 페이지 | 근거 확인 및 본문 위치 연결 |
+| 관계 | `relation_id`, 시작 용어, 도착 용어, 유형, 라벨, 방향 | 개념 연결선 구성 |
+| 관계 근거 | 출처, 근거 설명, 검토 상태 | 추정 관계가 확정 관계로 표시되는 것 방지 |
+| 검수 이력 | 초안/검토중/확정, 검토자, 수정일 | 내용 검수와 버전 관리 |
+| 화면 배치 | 표시 위치, 묶음, 펼침 상태 | 내용과 독립적으로 지도 구성 |
+
+PDF의 파일상 페이지와 책에 인쇄된 페이지는 다를 수 있으므로 따로 저장합니다. 아직 확인하지 않은 페이지는 비워 두며 임의로 채우지 않습니다.
+
+### 관계 유형의 예
+
+| 제안 유형 | 뜻 | 화면 표현 |
+| --- | --- | --- |
+| `part_of` | 상위·하위 또는 구성 관계 | ‘…의 구성 요소’ |
+| `precedes` | 과정의 앞뒤 관계 | 방향과 ‘다음 단계’를 표시 |
+| `informs` | 다른 판단이나 활동의 근거로 활용 | ‘…의 자료로 활용’ |
+| `contrasts_with` | 차이를 비교해 배워야 하는 관계 | ‘구분할 개념’ |
+| `related_to` | 그 밖의 검수된 관련 관계 | 구체적인 연결 이유를 별도로 작성 |
+
+‘같은 단원에 있다’, ‘색인에서 가까이 있다’, ‘같은 페이지에 나온다’는 정보만으로 위 관계를 확정하지 않습니다. 목차의 계층 구조와 개념 간 관계망은 별개로 관리해야 합니다. 관계망에는 단원 간 연결이나 순환 관계도 있을 수 있습니다.
+
+### 관계 레코드 예시
+
+아래는 구조를 설명하기 위한 초안입니다. 실제 교재에서 확인한 확정 데이터가 아닙니다.
+
+```json
+{
+  "relation_id": "r001",
+  "source_term_id": "t_assessment",
+  "target_term_id": "t_diagnosis",
+  "type": "informs",
+  "label": "사정 자료를 바탕으로 문제를 정리",
+  "directed": true,
+  "sources": [],
+  "review_status": "draft"
+}
+```
+
+## 8. 교과서 PDF에서 실제 데이터로 만드는 절차
+
+1. **PDF 상태 확인:** 텍스트 선택 가능 여부, 스캔 품질, 목차·색인 유무를 확인합니다. 스캔본이면 문자 인식과 교정이 필요합니다.
+2. **목차·색인 추출:** 용어, 하위 색인 항목, 참조 표현, 수록 페이지를 원래 구조와 함께 확보합니다.
+3. **용어 정리:** 표기 차이, 동의어, 약어, 중복과 동음이의어를 정리하고 고유 ID를 부여합니다.
+4. **본문 확인:** 색인 페이지를 따라 정의, 설명, 사례 및 단원 맥락을 확인합니다. 색인만으로 설명을 작성하지 않습니다.
+5. **관계 작성·검수:** 포함, 순서, 활용, 비교 등의 연결을 본문 근거와 함께 작성하고 교수자가 확인합니다.
+6. **데이터 반영:** 검수 상태에 따라 학생에게 공개할 내용을 구분하고 실제 지도와 검색에 연결합니다.
+
+자동 추출을 사용하더라도 내용의 정확성을 확인하는 단계는 필요합니다. 특히 OCR 오인식, 여러 단원에 등장하는 용어, 비슷한 이름의 개념, 연결 방향을 확인해야 합니다. 데이터 준비 과정에서 보조 도구를 쓰는 것과 학생용 사이트가 AI 서비스를 호출하는 것은 별개의 결정입니다.
+
+## 9. 화면 구현에서 중요한 기준
+
+### 전체를 담되 한 번에 모두 읽게 하지 않기
+
+전체 색인을 데이터로 보유하면서도 처음에는 주제별 묶음을 보여줍니다. 은하를 선택하면 관련 용어를 펼치고, 별을 선택하면 필요한 관계를 강조합니다. 수백 개 용어와 모든 연결선을 처음부터 같은 밀도로 노출하면 학습 목적을 달성하기 어렵습니다.
+
+### 읽기와 조작을 우선하기
+
+- 배경 별과 클릭 가능한 용어 별을 구분합니다.
+- 주요 용어와 설명은 배경 효과보다 선명하게 보이도록 합니다.
+- 계속 회전하거나 움직이는 화면은 기본 동작으로 삼지 않습니다.
+- 색뿐 아니라 이름, 선택 표시, 관계 라벨로도 의미를 전달합니다.
+- 키보드로 주제와 용어를 선택할 수 있게 합니다.
+- 모바일에서는 주제 중심으로 화면을 단순화하고 설명을 아래에 배치합니다.
+- 관계가 많은 개념은 필요한 연결을 먼저 보여주고 나머지를 펼치는 방식을 검토합니다.
+
+실제 확대·축소와 드래그 이동은 전체 데이터 규모에 따라 검토할 기능입니다. 현재 시안의 은하 선택은 **화면 구성을 바꾸는 탐색**이며, 연속적인 줌이나 물리적인 우주 이동을 구현한 것은 아닙니다.
+
+## 10. 현재 HTML 시안에 구현된 것과 한계
+
+| 항목 | 현재 상태 |
+| --- | --- |
+| 주제와 용어 | 예시 5개 주제, 25개 용어 |
+| 내용 근거 | 교재를 아직 반영하지 않은 화면 설계용 설명·사례·관계 |
+| 전체 지도 | 주제별 은하와 일부 대표 용어 표시 |
+| 은하 선택 | 선택한 주제의 용어를 펼쳐 표시 |
+| 용어 선택 | 선택 표시, 상세 설명, 관련 연결선 갱신 |
+| 연결 개념 이동 | 같은 은하와 다른 은하의 용어로 이동 |
+| 검색 | 용어·등록 표현·설명에 대한 문자열 검색 |
+| 화면 크기 대응 | 좁은 화면에서는 지도를 단순화하고 상세 설명을 아래에 배치 |
+| 관계 표시 | 일부 관계의 라벨 강조. 방향 화살표 등은 실제 개발 시 보강 필요 |
+| 교재 원문·페이지 링크 | 미구현 |
+| PDF 업로드·자동 추출 | 미구현 |
+| 교수자용 편집·검수 화면 | 미구현 |
+| 두 용어 동시 선택·경로 찾기 | 미구현 |
+| 계정·학습 기록·서버 저장 | 미구현 |
+
+시안은 HTML, CSS, JavaScript로 구성되어 있으며, 예시 데이터가 파일 안에 들어 있습니다. 배포용 HTML은 필요한 코드를 한 파일에 담아 별도 설치 없이 브라우저에서 열도록 구성했습니다. 개발 시에는 배포용 파일의 미리보기 포장 코드보다 화면 구조, 동작, 예시 데이터의 의미를 참고하면 됩니다.
+
+## 11. 권장 개발 순서와 완료 기준
+
+### 1단계: 대표 단원으로 데이터와 탐색 규칙 확인
+
+실제 교재의 대표 단원을 골라 목차·용어·출처·관계 구조를 검증합니다. 교수자 검수 후 학생이 정확한 용어를 모르더라도 주제와 설명을 따라 찾을 수 있는지 확인합니다.
+
+### 2단계: 전체 색인으로 확장
+
+전권의 용어를 연결하고, 여러 단원에 속하는 개념과 단원 간 관계를 처리합니다. 데이터가 늘어도 검색과 화면 전환이 원활한지, 글자와 연결선이 겹치지 않는지 확인합니다.
+
+### 3단계: 학습에 필요한 기능만 추가
+
+교과서 위치 연결, 비교할 개념의 나란히 보기, 최근 탐색 경로, 교수자 편집·검수 화면 등은 실제 사용을 보며 우선순위를 결정합니다.
+
+완료 여부는 다음 기준으로 확인할 수 있습니다.
+
+- 정식 용어, 등록된 동의어, 설명 속 단어로 예상한 검색 결과가 나오는가?
+- 검색 결과가 없을 때 주제 탐색으로 이어갈 수 있는가?
+- 별을 선택하면 해당 용어의 설명과 관계가 일치해 표시되는가?
+- 관계선의 의미와 방향이 내용에 맞으며 근거를 확인할 수 있는가?
+- 여러 단원에 등장하는 용어가 일관된 ID와 설명을 사용하는가?
+- 전체 지도와 개별 은하 사이를 오가도 현재 위치를 이해할 수 있는가?
+- 작은 화면과 키보드 조작에서도 핵심 내용에 접근할 수 있는가?
+- 교재 확인 전 예시와 검수된 학습 내용이 구분되는가?
+
+## 12. 개발자와 우선 협의할 사항
+
+1. 실제 교과서의 제목·판과 목차를 어떤 은하 구조로 표현할 것인가?
+2. 용어·관계 데이터를 누가 어떤 형식으로 작성하고 검수할 것인가?
+3. 한 개념이 여러 단원에 속할 때 소속과 단원별 설명을 어떻게 표시할 것인가?
+4. 전체 색인 규모에서 한 화면에 보여줄 정보량과 탐색 방식을 어떻게 조절할 것인가?
+5. 학생들이 용어의 뜻과 관계를 더 잘 이해하게 되었는지 어떤 과제로 확인할 것인가?
+
+이 프로젝트의 핵심은 **교과서에 근거한 개념 구조를 만들고, 용어를 모르는 학생에게도 그 구조로 들어갈 길을 제공하는 것**입니다. 우주형 화면은 이 학습 과정을 지원하도록 설계합니다.