feat(occupancy): retrieve and stage historical HikCentral flow #162

New issue

Closed

opened 2026-09-27 23:29:26 +00:00 by gabogg · 0 comments

gabogg commented

2026-09-27 23:29:26 +00:00

Owner

Part of #160.

Result

An admin can fetch a completed facility-calendar month of HikCentral people-counting history into durable staging without changing live events, calibration, or published statistics. One-time manual runs are supported; automatic future gap repair is outside scope.

Acceptance

Use deployed Artemis POST /artemis/api/aiapplication/v1/people/statisticsTotalNumByTime at hourly resolution, collecting every expected people-counting camera. Default to the current count of 12 cameras for historical months; surface and require validation of a count or identity mismatch without assuming today's camera membership was always present.
Respect the documented limit of 10 camera IDs per request. Chunk the month into bounded time ranges. On the deployed 2.6.3 service, start/end hour rows can both appear and pages 1 and 2 repeated rows despite pageSize: 1; never use page progression alone as a termination rule. Deduplicate by source, camera and hour.
Store source-attributed camera-hour counts, retrieval revision, response status, coverage evidence and request range in a durable staging schema. Retain prior snapshots when a re-fetch changes counts; unchanged re-fetches are idempotent. Do not fabricate timestamped passage events or route this through live ingestion.
Retain successfully retrieved rows when a month is incomplete and allow safe retry. An empty response is not proof of zero traffic; report generation/availability and gaps remain reviewable. Report limits or failures without silently marking a day complete.
Restrict fetch to admins and completed facility-calendar months. Staging is not read by statistics and is not subject to the live-event 180-day pruning policy.
Add deterministic offline tests for signing/client responses, duplicate boundaries/pages, camera batching, revision/idempotency, partial failures, and no changes to live/published data.

Primary reference: Hikvision people-counting OpenAPI guide. The deployed route and July/August 2026 hourly rows were verified read-only in #160. Follow repository controller/service/repository seams.

Part of #160. ## Result An admin can fetch a completed facility-calendar month of HikCentral people-counting history into durable staging without changing live events, calibration, or published statistics. One-time manual runs are supported; automatic future gap repair is outside scope. ## Acceptance - Use deployed Artemis `POST /artemis/api/aiapplication/v1/people/statisticsTotalNumByTime` at hourly resolution, collecting every expected people-counting camera. Default to the current **count** of 12 cameras for historical months; surface and require validation of a count or identity mismatch without assuming today's camera membership was always present. - Respect the documented limit of 10 camera IDs per request. Chunk the month into bounded time ranges. On the deployed 2.6.3 service, start/end hour rows can both appear and pages 1 and 2 repeated rows despite `pageSize: 1`; never use page progression alone as a termination rule. Deduplicate by source, camera and hour. - Store source-attributed camera-hour counts, retrieval revision, response status, coverage evidence and request range in a durable staging schema. Retain prior snapshots when a re-fetch changes counts; unchanged re-fetches are idempotent. Do not fabricate timestamped passage events or route this through live ingestion. - Retain successfully retrieved rows when a month is incomplete and allow safe retry. An empty response is not proof of zero traffic; report generation/availability and gaps remain reviewable. Report limits or failures without silently marking a day complete. - Restrict fetch to admins and completed facility-calendar months. Staging is not read by statistics and is not subject to the live-event 180-day pruning policy. - Add deterministic offline tests for signing/client responses, duplicate boundaries/pages, camera batching, revision/idempotency, partial failures, and no changes to live/published data. Primary reference: [Hikvision people-counting OpenAPI guide](https://www.hikvisioneurope.com/eu/portal/portal/Technology%20Partner%20Program/03-How%20to/How%20to%20get%20people%20counting%20data%20from%20HCP%20via%20OpenAPI.pdf). The deployed route and July/August 2026 hourly rows were verified read-only in #160. Follow repository controller/service/repository seams.

gabogg added the

ready-for-agent

label

2026-09-27 23:29:26 +00:00

gabogg referenced this issue

2026-09-27 23:29:46 +00:00

feat(occupancy): curate monthly historical flow drafts #163

gabogg referenced this issue

2026-09-27 23:33:18 +00:00

feat(occupancy): reviewed monthly historical passenger-flow backfill #160

~~gabogg referenced this issue 2026-09-27 23:39:54 +00:00~~

feat(occupancy): retrieve and stage historical HikCentral flow #166