# 릴리스 노트 — Web Configurator **v1.12.3**

- **배포일**: 2026-07-01
- **대상**: 디바이스 BSP 이미지 포함용 (DP World Smart Solutions · IoT 디바이스)
- **패키지**: 내부 git 태그 `v1.12.3` (커밋 히스토리가 없는 **클린 스냅샷**)
- **이전 전달**: v1.12.1 — 본 전달은 v1.12.2·v1.12.3 변경을 함께 포함합니다.

---

## 0. v1.12.1 → v1.12.3 신규/변경 (이번 전달의 핵심)

이번 전달은 v1.12.1 위에 **v1.12.2(신규/빈 디바이스 DB-init 안정화)** 와 **v1.12.3(Wi-Fi AP 채널 선택 + 네트워크 즉시적용 실측 검증)** 을 함께 반영한 것입니다.

### v1.12.2 — 신규/빈 디바이스 DB-init 안정화 (fail-soft)
펌웨어 업데이트 직후 동기화 문제로 `device_config`/`protocol_config` 가 비어 있을 때, **웹이 그 값을 생성·덮어쓰지 않도록** 하여 dpworldapp 의 시딩을 선점하지 않습니다. 단일 판정(`config_initialized`)을 아래에 일관 적용합니다.

| 경로 | 미초기화 시 동작 |
|---|---|
| 설정 조회(GET) | 빈 `{}` 를 정상 설정처럼 주지 않고 **204** 반환 |
| 설정 저장(POST) | **409 `not_initialized`** — 빈 폼 저장으로 실제 설정을 덮어쓰는 것 차단 |
| 네트워크 즉시적용 | DB 미러 쓰기는 **skip**(경고 기록)하되 **렌더 파일 적용은 계속**(연결 복구 보존) |
| 마이그레이션·서버 시작 | DB 부재/락에도 **크래시 없이 degraded** 로 계속 |

> ※ 협력사 자체 DB-init fix(`2ca0ac1`)를 **포함·강화**한 것입니다. 특히 미초기화 시 **예외를 던져 fresh device 를 중단시키던 부분**을, 렌더는 적용하고 DB 쓰기만 건너뛰는 **fail-soft** 로 대체했습니다.

### v1.12.3 — Wi-Fi AP 채널 선택 + 네트워크 즉시적용 검증
- **Wi-Fi AP DFS 인지 채널 선택**: STA(내부 클라이언트)가 DFS/NO-IR 5GHz 채널(52–64·100–144)에 있어도 AP 가 그 채널을 맹목 추종하지 않고 **비-DFS 채널을 선택**합니다(2.4GHz STA 는 ch1–13 만 추종). AP 상태에 라디오-다운 사유(`country_unset`/`channel_dfs`/`mcc_bi`)를 추가해 진단을 명확히 했습니다.
- **네트워크 즉시적용**: 기존 방식(`systemctl start dpworld-network-apply.service`)을 **유지**합니다. 디바이스 실측으로 정상 동작을 재확인했고, 관련 내부 재작업 시도는 검토 후 **원복**했습니다(순변화 없음).
- (참고) 즉시적용마다 boot-seed 스크립트가 한 번 더 실행되는 부수효과가 있으나 적용 자체는 성공합니다. 상세/불변식(하드닝본 필수 등)은 `BSP-INTEGRATION.md` 를 참조하세요.

---

## 1. (v1.12.1 참고) 한눈에 보기
아래 1~장은 **v1.12.1 전달 시점**의 내용입니다.

이번 릴리스는 **텔레메트리 Uplink(Ethernet 전환) 기능 추가 + 전체 안정화** 릴리스입니다.

- **신규 — 텔레메트리 Uplink**: dpworldapp 의 클라우드 텔레메트리(프로토콜·업데이트·RTCM 서버) 송신 경로를
  웹 UI 에서 **Wi-Fi ↔ Ethernet 으로 전환**합니다. OS 라우팅(호스트 라우트)만 사용하며, dpworldapp 과
  OS 네트워크 설정 파일은 **건드리지 않습니다**.
- **신규 — 라우팅 투명성**: 서버별 실제 송신 인터페이스를 표시하고, 인터페이스 선택이 로컬 LAN 호스트를
  가리는 등 충돌 가능성이 있으면 **적용 전에 경고**합니다(읽기 전용 — 포워딩/NAT 를 열지 않음).
- **안정화 — 전체 소스 리뷰 41건 반영**: 정직성(점검되지 않은 상태를 정상으로 표시하던 경로 제거),
  안전성(일부 실패 상황에서 설정이 빈 값으로 덮어써지던 경로 차단, 로그 아카이브 과삭제 방지),
  구조(중복 로직 통합) 개선. **dpworldapp 공유 DB(device/protocol 설정)·원자적 쓰기 계약은 무변경.**
- v1.12.0 의 설치 경로(`/usr/lib/web-configurator`)·기본 포트(`:9090`)는 **그대로 유지**됩니다.
- Python 3 **표준 라이브러리(stdlib)만** 사용 — 외부 pip 패키지 없음.

---

## 2. 주요 변경 (v1.12.0 → v1.12.1)

| 항목 | 변경 |
|---|---|
| **텔레메트리 Uplink (신규)** | dpworldapp 클라우드 텔레메트리 송신을 웹 UI 에서 Wi-Fi↔Ethernet 전환. 선택한 인터페이스의 게이트웨이를 통해 대상 서버 IP 에 대한 **호스트 라우트(/32)** 를 설치하는 방식 — relay·dpworldapp·OS 네트워크 파일 무변경. 적용은 비동기로 즉시 반환하고, 워치독이 라우트 유실 시 **자가복원**합니다. 관리 인터페이스가 끊기지 않도록 안전장치를 포함합니다. |
| **라우팅 투명성 + 사전 경고 (신규)** | 서버별 라우팅 상태와 실제 송신 인터페이스를 표시하고, 인터페이스 선택의 영향(로컬 LAN 호스트 가림 등)을 **적용 전에 경고**. 읽기 전용 — 포워딩/NAT 를 열지 않습니다. |
| **전체 소스 리뷰 41건 반영 (안정화)** | 정직성·안전성·구조 개선. 대표적으로: 점검 전 상태를 정상으로 표시하던 대시보드 경로 수정, 설정 로드 실패 시 빈 값 저장으로 인한 설정 손실 차단, 로그 자동정리의 마지막 아카이브 과삭제 방지, 중복된 경로/보안 로직 통합. **dpworldapp 공유 DB·계약·타입은 무변경.** |

> v1.12.0 에서 이전한 설치 경로(`/usr/lib`)·기본 포트(`:9090`)는 본 릴리스에서도 유지됩니다.

---

## 3. 네트워크-적용 하드닝 — 통합 방식 (중요)

디바이스 펌웨어는 다음 base 구성을 제공합니다(firmware-native):
- `dpworld-network-apply.service` / `dpworld-network-seed.service` (유닛)
- `/usr/bin/dpworld-network-apply.sh` (base 스크립트)

이 base 스크립트에는 WiFi 국가 코드 변경 시 `modprobe -r wlan` 으로 모듈을 라이브 재로드하는
경로가 있어, QCA6490(cnss_pci)에서 **PMU 워치독 재부팅 루프**를 유발한 이력이 있습니다.
본 패키지의 `dpworld-network-apply-hardened.sh` 가 이 문제를 제거한 **완전 대체본**입니다.

**① 권장 — BSP 베이킹(직접 교체):** 펌웨어 이미지를 빌드하는 협력사는
`deploy/dpworld-network-apply-hardened.sh` 의 내용을 **`/usr/bin/dpworld-network-apply.sh`
원본 이름으로 설치**(펌웨어 원본 교체)하면 됩니다. base 서비스/시드 유닛이 이미 그 경로를
호출하므로 apply·`--boot` 모두 자동으로 하드닝 동작을 탑니다. **드롭인은 베이킹하지 않습니다.**

**② Fallback — 라이브 후적용(override):** 이미 구워진 디바이스에 펌웨어 교체 없이 얹을 때만,
하드닝본을 별도 파일로 두고 `dpworld-network-apply.service.d/` + `dpworld-network-seed.service.d/`
드롭인으로 ExecStart를 교체합니다. (우리 개발용 `scripts/deploy.ps1` 가 이 방식을 사용)

→ 단계별 절차는 `docs/firmware-boot-hardening.md` "펌웨어 베이킹 (BSP) — 원본 교체 방법" 참조.

---

## 4. 호환성 · 주의사항
- **텔레메트리 Uplink**: 인터페이스 전환은 **호스트 라우트(/32)** 만 설치/제거하며 dpworldapp·OS 설정
  파일을 변경하지 않습니다. 전환을 즉시 반영하려면 dpworldapp 재시작 또는 디바이스 재기동이 필요할 수
  있습니다(기존 TCP 연결은 전환 시점에 자동 이전되지 않음).
- **디바이스 적용 시점**: dpworldapp 재시작 시 새 계약값으로 config 가 재적용됩니다.
- **nginx optional**: `deploy/nginx.conf`는 BSP에서 `:80` reverse proxy를 제공할 때 쓰는 sample입니다. `scripts/deploy.ps1`는 nginx를 설치/수정하지 않으며, 디바이스가 앱을 `:9090`으로 직접 접근하면 없어도 됩니다. sample을 쓸 경우 `proxy_pass`를 앱 포트 `:9090`으로 맞추세요.
- **런타임 의존성**: python3 stdlib만 필요 (RDEPENDS 목록은 `BSP-INTEGRATION.md` 참조). 외부 패키지 없음.
- **dpworldapp**(텔레메트리 바이너리)는 firmware-native.

---

## 5. 배포 방법 (BSP)
1. **패키지 입수**: 내부 git 태그 `v1.12.1` (또는 동봉 스냅샷)
2. **레시피 작성**: `BSP-INTEGRATION.md`의 샘플 bitbake recipe + 설치 경로표 사용
   - `src/` → `${libdir}/web-configurator/src/` (`${libdir}` = `/usr/lib`)
   - `deploy/*.service` → systemd 유닛 디렉토리
   - `deploy/dpworld-network-apply-hardened.sh` → **`/usr/bin/dpworld-network-apply.sh`** (펌웨어 원본 교체, §3 ①)
   - `deploy/nginx.conf` → optional nginx sample site config
   - `web-configurator.service` enable
3. **검증**: 이미지 부팅 후 `systemctl status web-configurator` + `curl http://127.0.0.1:9090/`

---

## 6. 품질/검증
- 본 릴리스는 내부 테스트 스위트(Python + 프런트 `.mjs`)로 검증되었으며, 텔레메트리 Uplink 기능과
  41 건의 리뷰 수정이 모두 회귀 테스트를 통과했습니다.
- 텔레메트리 Uplink·라우팅 투명성은 운영 디바이스에서 동작 확인되었습니다(dpworldapp·공유 설정 무접촉).
- 테스트 스위트는 내부 저장소에서 관리되며 **본 배포물에는 포함되지 않습니다**.
- 패키지는 **커밋 히스토리 없음**(`git archive` 스냅샷) + 내부 분석/개발 자료 제외 (`DELIVERABLE-MANIFEST.txt` 참조).

---

## 7. 롤백
- BSP recipe의 버전 핀(태그/SRCREV)을 **v1.12.0**으로 되돌리면 이전 버전 배포.
- 마이그레이션은 **멱등 + 변경 전 자동 백업**(config_safety)으로 보호됩니다.

---

## 버전 이력 (요약)
| 버전 | 일자 | 요약 |
|---|---|---|
| **v1.12.1** | 2026-06-29 | 텔레메트리 Uplink(Ethernet 전환) + 라우팅 투명성 추가 + 전체 소스 리뷰 41건 안정화 (설치 경로·포트는 v1.12.0 유지) |
| v1.12.0 | 2026-06-25 | 앱 코드 설치 경로 `/opt/web-configurator` → `/usr/lib/web-configurator` 이전 + 기본 포트 8080→9090 (앱 기능 무변경) |
| v1.11.16 | 2026-06-23 | MemoryMax 48M→128M + BSP 베이킹(직접 교체) 가이드 1차 정비 |
| v1.11.15 | 2026-06-23 | 사이드바 System 그룹 monitor 아이콘 정리 |
| v1.11.14 | 2026-06-23 | 사이드바 부모 그룹(System=Dashboard+Log / Firmware) 재편 |
| v1.11.11 | 2026-06-23 | config 쓰기 경로를 디바이스 config-reader 계약에 정렬 + 자동 마이그레이션 |
| v1.11.10 | 2026-06-20 | 전체 코드리뷰 fix (37건) |