managed-portal/docs/plans/2026-05-15-host-lan-webdevice-scan.md

Host LAN Web Device Scan Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Scan the server host LAN for web devices even when users access the portal through 10.8.0.x:13000, and open devices through the portal proxy.

Architecture: The Go backend will derive scan interfaces from the server host LAN instead of the request host. The frontend will open /proxy/web/<ip>/ first so clients do not need direct LAN reachability.

Tech Stack: Go backend, Vue frontend, Docker Compose deployment.

---

Task 1: Backend Scan Source

Files:

• Modify: internal/webdevice/service.go
• Test: internal/webdevice/service_test.go

Steps:

1. Add tests for filtering Docker/VPN interfaces and retaining physical LAN interfaces.
2. Add a host interface discovery helper that can parse host network data.
3. Use host LAN interfaces in Scan, falling back to existing interface discovery if none are found.
4. Keep scanning TCP port 80 and the existing /24 cap.

Task 2: Frontend Proxy Open

Files:

• Modify: web/src/views/WebDevices.vue

Steps:

1. Make openDevice prefer proxy_url.
2. Fall back to direct_url only if no proxy URL exists.

Task 3: Verify And Deploy

Commands:

• go test ./internal/webdevice ./internal/server
• pnpm --dir web build
• rsync changed files to xiaozheng@10.8.0.18:/home/xiaozheng/code/managed-portal/
• docker compose --env-file managed-portal.env up -d --build managed-portal managed-portal-web