# 지역사회간호학 개념 우주

교과서 PDF의 목차·찾아보기(색인)를 추출해 **은하(장) → 별자리(절) → 별(용어)** 로 탐색하는 학습 사이트입니다.
설계 배경은 `*개발설명서*.md`, 원래 화면 시안은 `*.html`(와이어프레임)을 참고하세요.

## 빠른 시작

```bash
uv venv .venv --python 3.13          # 또는 python3 -m venv .venv
uv pip install --python .venv/bin/python -r requirements.txt
.venv/bin/python -m server            # http://127.0.0.1:8000
```

- 처음 실행하면 `data/atlas.json`을 DB(`data/atlas.db`)로 가져오고, **교수자 계정**(아이디 `professor`)을 만들어 터미널에 아이디·비밀번호를 한 번 출력합니다.
  비밀번호는 `ATLAS_OWNER_PASSWORD`(또는 기존 `data/.owner_password`, 없으면 무작위)로 정하고, 계정을 만든 뒤에는 DB에 해시로만 저장합니다. 아이디·비밀번호는 관리 → 설정에서 바꿉니다.
- 학교 네트워크에 공개하려면 `--host 0.0.0.0`.

| 주소 | 용도 |
| --- | --- |
| `/` | 개념 우주 (검색·지도·목록·용어 상세·경로 찾기·비교·최근 탐색) |
| `/feedback` | 오류 신고 및 처리 현황 (누구나) |
| `/login` · `/signup` · `/account` | 로그인(학생·교수자 공용) · 가입 코드로 회원 가입 · 내 정보(반·학습 기록) |
| `/members` | 회원 관리 (교수자) |
| `/admin` | 관리: 대시보드, 피드백 처리, 용어·관계 편집/검수, 은하·단원, 설정, 수정 기록, 내보내기 |
| `/api/docs` | API 문서 |

## 데이터 흐름

```
교과서 PDF ──(pipeline)──> data/atlas.json ──(seed)──> data/atlas.db ──> 웹 화면
                                ▲                         │
     data/drafts/out_*.json ────┘          관리 화면·피드백으로 수정 (edited=1 → 재가져오기에도 보존)
```

```bash
.venv/bin/python -m pipeline.build    # PDF → data/atlas.json (약 30초)
.venv/bin/python -m server.seed       # atlas.json → DB (사람이 고친 항목은 유지)
```

- **교재**: `pipeline/config.py` 의 `BOOKS`. 은하는 2026 지역사회간호학 1·2권의 9개 장, 퍼시픽 5판·보건교육학은 보조 출처로 연결하고
  2026판 절에 배치합니다(배치가 추정이면 화면에 ‘배치 추정’ 표시).
- **자동 추출물은 모두 `검수 전(draft)`** 입니다: 교과서 정의 문장, 영문 동의어, 관계(목차 구조·정의 문장·이름 포함), 쉬운 뜻 초안.
  - 쉬운 뜻·사례 초안(`data/drafts/out_*.json`)은 교재 문장을 근거로 AI가 작성한 초안이며, 화면에 ‘교수자 검토 전’으로 표시됩니다.
  - 비교 개념 쌍·시안 예시는 `pipeline/curated.py`.
- **공개 범위**: 관리 → 설정에서 학생에게 보여줄 검수 상태(검수 전/검토 중/확정)를 정합니다. 저작권 때문에 학생 화면·공개 API에는 교과서 원문 문장·교재명·판·쪽수를 내보내지 않습니다(쉬운 뜻·사례·관계만). 교재 출처는 로그인한 교수자의 관리 화면에서만 보이며, PDF는 서버에 두지 않습니다.
  검수가 끝나면 ‘확정’만 공개하는 것을 권장합니다. 교재 PDF·문장 공개는 저작권을 확인하세요.

## 회원·반·문제

- 누구나: 지도·검색·쉬운 뜻·관계, 오류 신고. **회원**만: 사례(이런 장면을 떠올려 보세요)와 문제.
- 회원 가입: 교수자가 `/members` → 가입 코드에서 반을 지정해 코드를 만들고 수업에서 알려 줍니다. 학생은 `/account`에서 그 코드를 넣으면 **바로** 회원이 되어 그 반에 들어갑니다(승인 단계 없음). 코드마다 사용 횟수·만료일·켜기/끄기.
- `/members`(회원 관리): 회원 목록(검색·상태·반), 회원별 학습 기록, 반 변경·사용 중지·비밀번호 재설정, 가입 코드, 반, 반별 학습 현황.
- 문제: 쉬운 설명이 있는 용어로 자동 객관식(뜻→용어, 용어→뜻)을 만들고, 관리 → 문제에서 직접 출제(객관식·OX)도 합니다. 채점은 서버에서 하며 정답은 미리 내려보내지 않습니다.
- 관리 화면(`/admin`, `/members`)은 **교수자 계정**(아이디·비밀번호)으로만 들어갑니다. 로그인은 `/login`에서 학생과 같이 합니다.

## 오류 피드백 → 수정

1. 학생·교수자가 용어 화면의 **오류 신고** 또는 `/feedback` 에서 신고합니다.
   화면 JS 오류와 서버 오류는 자동으로 같은 목록(유형: 자동 수집 오류)에 쌓입니다(같은 오류는 횟수만 증가).
2. 관리 → 피드백에서 확인하고 용어 편집으로 바로 고치거나, 터미널에서 확인합니다:

```bash
.venv/bin/python -m server.cli feedback          # 처리 대기 목록
.venv/bin/python -m server.cli show 12           # 상세 + 대상 용어 현재 값·출처
.venv/bin/python -m server.cli resolve 12 "p.188 정의로 교체"
```

3. 추출 규칙 자체가 문제면 `pipeline/` 을 고친 뒤 build → seed (검수된 내용은 보존).

## macmini 배포 (Apple container, 포트 8088)

```bash
deploy/deploy-macmini.sh            # 동기화 → 이미지 빌드 → 컨테이너 교체 → 부팅 시 자동 시작 등록 (교재 PDF는 보내지 않음)
deploy/macmini.sh status|logs|restart|stop|password|backup   # password: 처음 만든 교수자 계정
deploy/macmini.sh feedback          # 오류 신고 목록 (컨테이너 안 server.cli)
deploy/macmini.sh cli show 12
```

- 주소: `http://macmini:8088` (SSH 별칭 `macmini`, 다른 호스트는 `SSH_HOST=… PORT=…`)
- macmini 쪽 폴더 `~/Community_Nursing_Atlas/`: `app/`(빌드 소스) `data/`(DB·관리자 비밀번호, 컨테이너 재생성에도 유지) `logs/`
- 데이터 갱신: 로컬에서 `pipeline.build` 후 다시 배포하면 컨테이너 시작 시 새 `atlas.json`을 가져옵니다(검수·편집한 내용은 보존).
- 부팅 시 자동 시작: `~/Library/LaunchAgents/com.nursing-atlas.container.plist`
- 공개 주소: `https://test.jsahn1026.synology.me` → 시놀로지 리버스 프록시 → `http://<macmini>:8088`.
  앱은 `X-Forwarded-For`/`X-Forwarded-Proto` 를 읽어 방문자 IP(신고 횟수 제한)와 https(관리자 쿠키 Secure)를 인식합니다.

## 테스트

```bash
.venv/bin/python -m pytest -q tests
node --test tests/search.test.mjs
```

## 구조

```
pipeline/   config.py(교재·은하) toc.py(목차) index.py(찾아보기) build.py(통합·정의·관계) curated.py
server/     app.py(API) db.py(스키마) seed.py(가져오기) auth.py(관리자) cli.py(피드백 CLI)
web/        index.html·feedback.html·admin.html, static/js(atlas·search·layout·admin·feedback·common), static/css
data/       atlas.json(파이프라인 결과) atlas.db(실행 DB) drafts/(쉬운 뜻 초안)
tests/      API·파이프라인·검색 테스트
```