# KOKOPICK 바우처 · 프론트엔드 개발 패키지

의료 바우처(선물형) 서비스의 **사용자 / 병원 / 관리자** 3개 화면을 실제로 개발할 수 있도록
정리한 HTML · CSS · JS 소스와 개발 문서 모음입니다. 프레임워크 없이 동작하므로 그대로 써도 되고,
React · Vue 로 옮길 때 마크업/토큰/명세의 기준으로 삼아도 됩니다.

---

## 1. 구성

| 앱 | 경로 | 사용자 | 주요 기능 |
|---|---|---|---|
| 내 바우처 | `user/index.html` | 바우처를 선물 받은 사람 | 로그인, 8개 언어, QR·잔액, 사용내역, 내 정보/비밀번호 변경 |
| 병원용 결제 접수 | `hospital/index.html` | 제휴 병원 담당자 | 병원 로그인, QR 스캔, 금액 입력·결제 확정, 병원 사용내역 |
| 운영 백오피스 | `admin/index.html` | 서비스 운영자 | 매출, 상품, 판매자, 구매자(바우처 발급), 병원, 정산, 사용자 관리 |

```
kokopick-voucher/
├─ index.html               개발 런처(3개 앱 + 문서 링크)
├─ user/index.html          사용자 화면
├─ hospital/index.html      병원 화면
├─ admin/index.html         관리자 백오피스
├─ assets/
│  ├─ css/
│  │  ├─ tokens.css         디자인 토큰(색·타이포·간격·다크모드)
│  │  ├─ base.css           리셋 + 공통 컴포넌트(버튼/폼/표/칩/모달/필터바)
│  │  ├─ app.css            모바일 앱 셸(사용자·병원 공통)
│  │  ├─ user.css           사용자 전용
│  │  ├─ hospital.css       병원 전용
│  │  └─ admin.css          백오피스 전용
│  ├─ js/
│  │  ├─ common.js          공통 유틸 · REST 클라이언트 · QR · 토스트
│  │  ├─ i18n.js            다국어 사전(ko/en/zh/ru/fil/id/th/vi)
│  │  ├─ mock-data.js       목업 데이터(로컬 확인용 — 실사용 모드에서는 HTML에서 주석 처리됨)
│  │  ├─ user.js  hospital.js  admin.js   화면별 로직
│  └─ img/                  로고(logo.png, logo-mark.png)
└─ docs/
   ├─ 01-화면정의서.md
   ├─ 02-데이터모델.md
   ├─ 03-API명세.md
   ├─ 04-디자인시스템.md
   └─ 05-개발가이드.md
```

---

## 2. 실행 방법

정적 파일이라 서버만 있으면 됩니다. (`file://` 로 열면 일부 브라우저에서 폰트·이미지 경로가 막힐 수 있습니다.)

```bash
# 1) 파이썬
python3 -m http.server 8080

# 2) Node
npx serve .           # 또는 npx http-server -p 8080

# 브라우저에서
http://localhost:8080/            # 런처
http://localhost:8080/user/       # 내 바우처
http://localhost:8080/hospital/   # 병원용
http://localhost:8080/admin/      # 백오피스
```

**현재 이 패키지는 실사용 모드입니다** — `assets/js/common.js` 의 `USE_MOCK` 이 `false` 로
설정되어 있고, 각 HTML의 `mock-data.js` 스크립트 태그는 주석 처리되어 있어 로드되지 않습니다.
실제 백엔드(`kokopick-backend`, 같은 도메인의 `/api` 경로)가 떠 있어야 로그인/데이터 조회가
됩니다. 데모 계정은 `kokopick-backend/README.md` 의 시드 데이터 표를 참고하세요
(예: 내 바우처 `mj_kim0715` / `Kp3wm8ta`, 병원용 `sc_hospital` / `Sc48dqpx`, 백오피스
`kp_admin` / `Admin1234!`).

로컬에서 백엔드 없이 화면만 목업 데이터로 확인하고 싶다면:

1. `assets/js/common.js` 상단의 `USE_MOCK` 을 `true` 로 바꿉니다.
2. 각 HTML(`user/hospital/admin/index.html`)에서 주석 처리된
   `<script src="../assets/js/mock-data.js"></script>` 줄의 주석을 해제합니다.
3. 이 상태에서는 아이디/비밀번호에 아무 값이나 입력해도 진입됩니다.

---

## 3. 백엔드 연동 (이미 적용된 설정)

`assets/js/common.js` 상단 설정은 이미 실사용 모드로 맞춰져 있습니다.

```js
var CONFIG = {
  USE_MOCK: false,
  // 백엔드가 같은 도메인(voc.pulseent.net)의 /api 경로에 있으므로 상대경로만으로 충분합니다.
  API_BASE: '/api/v1',
  TOKEN_KEY: 'kokopick.token'
};
```

다른 도메인의 백엔드를 쓰게 되면 `API_BASE` 를 절대주소(`https://.../api/v1`)로 바꾸고,
백엔드 `config.php` 의 `CORS_ORIGIN` 도 이 프론트 도메인으로 맞춰야 합니다.

각 화면 로직(`user.js` / `hospital.js` / `admin.js`)에는 이미
`if (KP.CONFIG.USE_MOCK) { … } else { KP.API… }` 분기가 들어 있습니다.
API 응답 형태는 `docs/03-API명세.md` 와 동일하다고 가정합니다.

---

## 4. 핵심 도메인 규칙 (반드시 지킬 것)

- **바우처는 발급 건마다 유일합니다.** QR(바우처 번호)은 *선물한 분 · 선물 받는 분 · 금액* 조합으로
  생성되며, 한 사람이 여러 명에게 선물해도 각각 별도 번호로 저장·사용·정산됩니다.
- **선물한 분(결제자)** 과 **선물 받는 분(사용자)** 는 다른 주체입니다.
  로그인 계정은 *선물 받는 분* 에게만 발급됩니다.
- 사용자 계정(ID/PW)은 등록 시 자동 생성되어 문자로 전달되고, 사용자가 비밀번호를 바꾸면
  백오피스 목록에는 `사용자 변경됨` 으로만 표시됩니다(평문 노출 금지).
- 결제(사용) 1건마다 `usages` 레코드가 쌓이고, 관리자가 병원 계좌로 입금한 뒤
  **정산/미정산** 상태를 직접 전환합니다.
- 금액은 원 단위 정수로만 다룹니다(소수점 없음).

---

## 5. 다음 단계 체크리스트

- [ ] 백엔드 API 구현 (docs/03-API명세.md)
- [ ] 실제 QR 생성/스캔 라이브러리 적용 (docs/05-개발가이드.md §3)
- [ ] 문자(SMS/알림톡) 발송 연동 — 계정·링크·선물 메시지
- [ ] 사용 가능 병원 지도 페이지 (위도/경도 사용)
- [ ] 관리자 권한 분리(마스터/운영/정산) 및 작업 이력 로그
- [ ] 접근성·다국어 문구 검수, PWA(홈 화면 추가) 여부 결정