inspect-nvr/docs/superpowers/plans/2026-07-13-hik-nvr-playback-rtsp-compatibility-fix.md

Hikvision NVR RTSP Playback Compatibility Fix Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Make the playback-search endpoint return an RTSP URL that the target Hikvision NVR can actually play while retaining SDK channel 33 for recording lookup.

Architecture: Extend the existing Hikvision login cache value with immutable device channel metadata read from NET_DVR_DEVICEINFO_V40. The playback service uses that metadata to map SDK channel numbers to RTSP display-channel numbers, then passes the resolved RTSP channel to a pure URL builder. RTSP query timestamps keep Beijing clock digits because the target firmware was verified to interpret them as device-local time.

Tech Stack: Java 8, Spring Boot 2.3.4, HCNetSDK/JNA, Caffeine, JUnit 4, Mockito, Maven.

Execution constraint: Modify the local master worktree only. Do not stage or commit any file.

---

File map

• Create src/main/java/com/inspect/nvr/service/HikLoginSession.java — immutable login handle and channel-layout mapping.
• Modify src/main/java/com/inspect/nvr/service/HikLoginService.java — cache HikLoginSession and capture login device metadata while preserving existing login(NvrInfo) callers.
• Modify src/main/java/com/inspect/nvr/hik/service/HikNvrPlaybackService.java — use the login session for the SDK handle and resolved RTSP channel.
• Modify src/main/java/com/inspect/nvr/hik/service/HikPlaybackUrlBuilder.java — accept an RTSP channel explicitly and retain Beijing clock digits.
• Create src/test/java/com/inspect/nvr/service/HikLoginSessionTest.java — pure channel mapping coverage.
• Create src/test/java/com/inspect/nvr/service/HikLoginServiceTest.java — verify SDK device metadata is captured into the cached session.
• Modify src/test/java/com/inspect/nvr/hik/service/HikPlaybackUrlBuilderTest.java — reproduce 3301 and UTC-conversion regressions.
• Modify src/test/java/com/inspect/nvr/hik/service/HikNvrPlaybackServiceTest.java — prove SDK search still uses 33 while the URL uses 101.

Task 1: Lock down corrected RTSP behavior

• Add a URL-builder test that calls build(request, 1, start, end) for SDK channel 33 and expects /Streaming/tracks/101?starttime=20260713T120000Z&endtime=20260713T130000Z.
• Add mapping tests asserting pure-NVR 33 -> 1, pure-NVR 34 -> 2, hybrid-DVR 33 -> 17, and analog-channel ordinal mapping.
• Add a login-service test whose mocked NET_DVR_Login_V40 returns byChanNum=0, byIPChanNum=8, and byStartDChan=33, then assert the returned session maps 33 -> 1.
• Add a playback-service test asserting NET_DVR_FILECOND_V40.lChannel == 33 while the response URL contains /Streaming/tracks/101?.
• Run mvn -Dtest=HikPlaybackUrlBuilderTest,HikLoginSessionTest,HikLoginServiceTest,HikNvrPlaybackServiceTest test and confirm RED failures are caused by the missing session API, explicit RTSP-channel builder signature, and old UTC behavior.

Task 2: Implement the minimal production fix

• Implement HikLoginSession with the existing user ID plus unsigned analog/digital channel counts and starts. Map a covered digital SDK channel after the analog channel count; map a covered analog SDK channel to its ordinal; otherwise return the original channel as a compatibility fallback.
• Change HikLoginService to cache HikLoginSession, add loginSession(NvrInfo), and keep login(NvrInfo) delegating to it so existing callers retain the same API.
• Change HikNvrPlaybackService to use loginSession, keep the original request channel in NET_DVR_FILECOND_V40, resolve the RTSP channel once, and pass it into every generated record URL.
• Change HikPlaybackUrlBuilder to calculate trackId from the explicit RTSP channel and format the supplied LocalDateTime directly as yyyyMMdd'T'HHmmss'Z' without converting to UTC.
• Re-run the four focused test classes and confirm all are GREEN.

Task 3: Verify regression safety and the real device

• Run mvn test -DskipTests=false and confirm zero failures/errors.
• Restart only the user-controlled application if explicitly permitted; otherwise use a temporary port to validate the endpoint without stopping the existing 8080 process.
• POST the known channel=33 query and verify the response URL contains track 101 and Beijing digits 120000Z to 130000Z, with credentials redacted from diagnostic output.
• Probe that returned URL with VLC using the default RTSP transport and require PLAY 200 OK plus decoded H.264 NAL units.
• Run scoped git diff --check, inspect git status --short, and confirm no new staging or commit occurred.