NewWebConfigurator/README.md

# IoT Web Configurator

> **파트너 전달 안내 (한글)** — 먼저 이 순서로 보세요:
> [`RELEASE-NOTES.md`](RELEASE-NOTES.md) (이번 버전·변경·주의·배포) →
> [`BSP-INTEGRATION.md`](BSP-INTEGRATION.md) (설치 경로·샘플 recipe·의존성) →
> [`DELIVERABLE-MANIFEST.txt`](DELIVERABLE-MANIFEST.txt) (패키지 구성).

IoT 디바이스 설정을 위한 웹 인터페이스를 제공하는 경량 Python stdlib HTTP 서버입니다.
원래 Java Spring Boot 애플리케이션이었으나, 순수 Python(stdlib만 사용)으로 재작성되어
메모리 사용량이 ~436 MB에서 10–30 MB로 줄었습니다. 모든 설정은 디바이스 내
SQLite 데이터베이스(`board_config` 테이블)에 저장됩니다.

---

## 저장소 구조

| 경로 | 설명 |
|---|---|
| `src/` | 애플리케이션 소스 — 서버, DB 매니저, 유효성 검사기, 로그 매니저, 네트워크 적용 엔진(`src/network/`), 펌웨어 OTA(`src/firmware/`), Wi-Fi AP(`src/network/ap_*`), 프론트엔드 SPA(`src/static/js/pages/` 하위 ~18개 페이지 모듈) |
| `docs/` | 설계 문서, 사양서, 운영 가이드 (`docs/DEPLOY.md` 참조) |
| `scripts/` | 라이브 배포 도구 (`deploy.ps1`) |
| `CHANGELOG.md` | 버전 변경 이력 |

---

## 로컬 실행

```bash
# From the repo root
python src/server.py
```

서버는 기본적으로 `0.0.0.0:8080`에 바인딩됩니다 (로컬 개발용). 환경 변수로 재정의할 수 있습니다:

| 변수 | 기본값 | 설명 |
|---|---|---|
| `HOST` | `0.0.0.0` | 바인딩 주소 |
| `PORT` | `8080` | 수신 포트 |
| `DB_PATH` | `/home/root/db/dynamic_data.db` | SQLite 데이터베이스 경로 |
| `LOG_DIR` | `/opt/log/dpworldapp` | 로그 파일 디렉터리 |

> **포트 안내:** `8080`은 로컬 개발 환경에서만 사용하는 기본값입니다. 디바이스에서는
> systemd 유닛(`deploy/web-configurator.service`)이 `PORT=9090`으로 설정하므로,
> 배포된 configurator는 **9090** 포트에서 수신합니다 — [docs/DEPLOY.md](docs/DEPLOY.md) §7 참조.

예시:

```bash
PORT=8888 DB_PATH=./dev_data.db python src/server.py
```

---

## 배포

디바이스 배포는 `scripts/deploy.ps1` (PowerShell, Windows 개발 호스트)을 사용합니다.
전체 절차는 **[docs/DEPLOY.md](docs/DEPLOY.md)** 를 참조하세요. 다음 내용을 다룹니다:

- 버전 정책(`vMAJOR.MINOR.PATCH`) 및 릴리즈 절차
- 사전 요건 및 사용 방법
- 스크립트 동작 순서 (아카이브 → 전송 → 백업 → 교체 → 버전 스탬프 → 재시작 → 검증)
- 배포 검증 및 디바이스에서 `DEPLOYED_VERSION` 확인
- 롤백 (`-Rollback` 플래그)
- 디바이스 아키텍처 (포트, 경로, 서비스 이름)
- 문제 해결

빠른 참조:

```powershell
.\scripts\deploy.ps1 192.168.55.56          # deploy a tagged release
.\scripts\deploy.ps1 192.168.55.56 -Rollback  # restore last backup
```

`deploy.ps1`은 nginx를 설치하거나 수정하지 않습니다. `deploy/nginx.conf`는
`:80` 리버스 프록시를 통해 앱을 노출하는 제품을 위한 선택적 BSP 샘플일 뿐이며,
디바이스는 `:9090`으로 앱에 직접 접근할 수도 있습니다.

---

## API 엔드포인트

### 디바이스 설정

| 메서드 | 경로 | 설명 |
|---|---|---|
| `GET` | `/setting/get-device` | 디바이스 설정 읽기 (비어있으면 204 반환) |
| `POST` | `/setting/device` | 디바이스 설정 저장 |
| `GET` | `/setting/get-protocol` | 프로토콜 설정 읽기 (비어있으면 204 반환) |
| `POST` | `/setting/protocol` | 프로토콜 설정 저장 |
| `GET` | `/api/mac` | WiFi MAC 주소 읽기 |

### 로그 관리

| 메서드 | 경로 | 설명 |
|---|---|---|
| `GET` | `/setting/log-files` | 로그 파일 목록 조회 (크기, 수정 일시, 유형) |
| `GET` | `/setting/log-stats` | 로그 디렉터리 통계 |
| `POST` | `/setting/log-download` | 선택한 파일을 tar.gz로 다운로드 |
| `POST` | `/setting/log-compress` | 비활성 로그 파일 수동 압축 |
| `POST` | `/setting/log-delete` | 선택한 로그 파일 삭제 |
| `GET`  | `/setting/kernel-bundle` | 커널 로그 번들 `.tar.gz` 다운로드 (journalctl 텍스트 내보내기 + `/opt/log` 커널 로그 + 부팅 이력 + pstore) — v1.1.0에서 추가 |

### 대시보드 / 모니터링

| 메서드 | 경로 | 설명 |
|---|---|---|
| `GET` | `/api/health` | 서버 상태 (가동 시간, DB 백엔드) |
| `GET` | `/api/system-status` | 홈 대시보드 페이로드 — 최상위 키: `core_app`, `communication`, `network`, `system` (v1.0.x~); `hardware_modules` GNSS + WiFi 펌웨어 (v1.2.0에서 추가); `dpworldapp_status` 7단계 시작 추적기 + 5-상태 결과 + 런타임 설정 필드 6개 (v1.3.0에서 추가) |
| `GET` | `/api/support-bundle` | 진단 zip (상태 + 마스킹된 설정 + 최근 로그 + OS 진단) |
| `POST` | `/api/action/test-connections` | 설정된 서버 엔드포인트 TCP 프로브 |
| `POST` | `/api/action/restart-dpworldapp` | systemctl을 통해 dpworldapp 재시작 |

### 네트워크 적용 엔진 (v1.6.0+)

30초 watchdog를 사용하여 OS 상의 네트워크 설정을 적용/검증/롤백합니다.
전체 내용: **[docs/network-apply-engine-guide.md](docs/network-apply-engine-guide.md)**.

| 메서드 | 경로 | 설명 |
|---|---|---|
| `GET`  | `/api/network/state` | 라이브 인터페이스 + drift + watchdog + 최종 적용 + `country_pending` |
| `GET`  | `/api/network/drift` | 전역 미적용 변경 수 (경량) |
| `GET`  | `/api/network/apply/status?id=<apply_id>` | 진행 중인 적용 폴링 (confirm TTL도 이 요청으로 갱신) |
| `GET`  | `/api/network/journal?limit=<n>` | 적용 저널 tail |
| `GET`  | `/api/network/config` | 유효한 `net_config` 읽기 (watchdog 킬스위치) |
| `POST` | `/api/network/apply` | 네트워크 필드 적용 (또는 `dry_run`) — 비동기, `apply_id` 반환 |
| `POST` | `/api/network/apply/confirm` | TTL 내에 eth1 단절성 적용 확인 |
| `POST` | `/api/network/rollback` | 이전 적용 스냅샷으로 롤백 |
| `POST` | `/api/network/config` | `net_config` watchdog 키 쓰기 |

### Wi-Fi AP

현장 프로비저닝을 위한 Soft-AP(`ap0`) 관리. 전체 내용:
**docs/wifi-ap-guide.md**.

| 메서드 | 경로 | 설명 |
|---|---|---|
| `GET`  | `/api/network/ap/status` | AP 런타임 상태 |
| `POST` | `/api/network/ap/config` | `ap_config` 쓰기 |
| `POST` | `/api/network/ap/apply` | AP 설정 적용 (ap0 시작/중지) |

### 펌웨어 OTA

dpworldapp 펌웨어 채널을 통한 업로드 → 사전 검증 → 플래시 → 복원 확인 흐름.
전체 내용: **docs/firmware-ota-guide.md**.

| 메서드 | 경로 | 설명 |
|---|---|---|
| `GET`  | `/api/firmware/status` | 현재 OTA 상태 스냅샷 |
| `POST` | `/api/firmware/preflight` | 업로드 전 사전 검증 |
| `POST` | `/api/firmware/upload` | 펌웨어 ZIP 업로드 |
| `POST` | `/api/firmware/flash` | 플래시 실행 |
| `POST` | `/api/firmware/restore-check` | 플래시 후 복원 검증 |

> 서브시스템 내부 구조 (상태 머신, byte-exact 렌더링, 부팅 강화)는
> [docs/architecture.md](docs/architecture.md) 및 위에 링크된 서브시스템별 가이드에 문서화되어 있습니다.

---

## 기술 스택

- Python 3.10 (stdlib만 사용 — 외부 의존성 없음)
- SQLite3 (기본 설정 저장소)
- 멀티스레드 HTTP 서버 (`ThreadingMixIn`)
- Vanilla ES-module SPA 프론트엔드 (빌드 단계 없음) — **Two Faces** 사용자/고급 보기 전환 기능을 포함한 ~18개 페이지 모듈 (`src/static/js/view-mode.js`)
- 주요 서브시스템: 네트워크 적용 엔진, Wi-Fi AP, 펌웨어 OTA (API 섹션 및 서브시스템별 가이드 참조)