gabogg/hikcentral
Watch
1
0
Fork
You've already forked hikcentral
 0
Code Issues 113 Pull requests 8 Projects Releases Packages Wiki Activity Actions

refactor(statistics): deprecate EntranceStatistics.zone_name in favor of camera_group #200

New issue
Closed
opened 2026-10-02 14:55:50 +00:00 by gabogg · 3 comments
gabogg commented 2026-10-02 14:55:50 +00:00
Owner
Copy link

Follow-up from #99 and PR #168 review pass 1.

EntranceStatistics.zone_name (and related DB/service fields) conflicts with CONTEXT.md's glossary, where "Zone" is explicitly in the avoid-list for camera groupings:

Camera Group

The HikCentral people-counting resource group...
Avoid: Zone, portal group.

zone_name was preserved in PR #168 for backwards compatibility with frontend API contracts and documented as:
"Legacy name: the camera's Camera Group; not a domain Zone."

This issue tracks deprecating or aliasing zone_name to camera_group across the database, Pydantic schemas, and frontend adapters (app.js, command_deck_adapter.js).

Follow-up from #99 and PR #168 review pass 1. `EntranceStatistics.zone_name` (and related DB/service fields) conflicts with CONTEXT.md's glossary, where "Zone" is explicitly in the avoid-list for camera groupings: > ### Camera Group > The HikCentral people-counting resource group... > _Avoid_: Zone, portal group. `zone_name` was preserved in PR #168 for backwards compatibility with frontend API contracts and documented as: "Legacy name: the camera's Camera Group; not a domain Zone." This issue tracks deprecating or aliasing `zone_name` to `camera_group` across the database, Pydantic schemas, and frontend adapters (`app.js`, `command_deck_adapter.js`).
gabogg commented 2026-10-02 16:03:33 +00:00
Author
Owner
Copy link

Back to needs-triage (2026-10-02). PR #168's second review (r21) found an open design point: should zone_name be deprecated with an alias, or removed in favour of camera_group? It also found no acceptance criterion. Note: zone_name holds the Camera Group name only when HikCentral returns one; otherwise it is guessed from the camera name, with the default 'General'. Settle these, then restore ready-for-agent.

Back to `needs-triage` (2026-10-02). PR #168's second review (r21) found an open design point: should `zone_name` be deprecated with an alias, or removed in favour of `camera_group`? It also found no acceptance criterion. Note: `zone_name` holds the Camera Group name only when HikCentral returns one; otherwise it is guessed from the camera name, with the default `'General'`. Settle these, then restore `ready-for-agent`.
gabogg commented 2026-10-02 16:10:53 +00:00
Author
Owner
Copy link

This was generated by AI during triage.

Agent Brief

Category: enhancement (refactor)
Summary: Replace the camera's zone_name with its Camera Group name everywhere it is served or shown, and stop writing zone_name.

Delivery: fixed inside PR #168, as part of its pass-2 fixes, and closed by it (maintainer, 2026-10-02).

Current behavior:

  • Each counting camera carries a zone_name string. When HikCentral returns a people-counting group, discovery copies the group's name into it. In the fallback discovery from camera names, it is a guess from keywords in the camera's name. The database default is 'General'.
  • The camera already stores resource_group_code, which links to the registered group's resource_group_name.
  • zone_name is served by the camera and entrance response models (including EntranceStatistics) and shown in the admin camera lists and search, the command deck camera list, and the statistics entrances table, labelled with the i18n key occupancy.zoneLabel.
  • CONTEXT.md names this concept Camera Group, with _Avoid_: Zone, portal group.

Desired behavior:

  • Every response that served zone_name serves camera_group: str | None instead: the name of the camera's linked Camera Group, or null when the camera has no group (fallback discovery, or Empty/Unlisted group states). No alias, no deprecation period. Backend and frontend change together, since the only consumer is this repo's frontend.
  • Camera discovery stops writing zone_name and drops the keyword-based zone guess. Direction inference from the camera name stays.
  • The frontend shows the group name wherever the zone was shown. A camera with no group shows a localized "No camera group" / "Sin grupo de cámaras", and stays searchable by name. Search matches the group name instead of the zone.
  • The label key becomes "Camera group" / "Grupo de cámaras". Rename the key to fit, e.g. cameraGroupLabel, in EN and ES.
  • The counting_cameras.zone_name column stays in the table, unused, marked legacy in the schema code. Dropping it is a separate low-priority cleanup (see below).
  • docs/api/README.md describes camera_group, and any OpenAPI field description uses the glossary term.

Key interfaces:

  • Camera and entrance response models, including EntranceStatistics: zone_name: str → camera_group: str | None.
  • The repository reads of cameras and entrances join the camera's resource_group_code to its group's name.
  • CountingCameraItem and the discovery upsert: no zone_name input.

Acceptance criteria:

  • No response model or frontend module reads or serves zone_name, apart from the legacy column definition.
  • A camera in a registered group serves that group's current name, and renaming the group upstream changes it on the next sync.
  • A camera with no group serves camera_group: null, and the UI shows the localized "no camera group" text in EN and ES.
  • Camera search in the admin list matches the group name, and still matches camera name and code.
  • Discovery no longer writes zone_name, and no zone is guessed from the camera name. Direction inference is unchanged, with a test.
  • The OpenAPI schema and docs/api/README.md document camera_group with Camera Group wording.
  • Python and frontend tests updated: the fixtures use camera_group, plus a grouped case and an ungrouped case.

Out of scope:

  • Dropping the zone_name column. That is a separate low-priority issue.
  • Changing how Camera Groups are discovered, counted or measured (ADR 0005).
  • Any multi-camera group behaviour.
> *This was generated by AI during triage.* ## Agent Brief **Category:** enhancement (refactor) **Summary:** Replace the camera's `zone_name` with its **Camera Group** name everywhere it is served or shown, and stop writing `zone_name`. **Delivery:** fixed inside **PR #168**, as part of its pass-2 fixes, and closed by it (maintainer, 2026-10-02). **Current behavior:** - Each counting camera carries a `zone_name` string. When HikCentral returns a people-counting group, discovery copies the group's name into it. In the fallback discovery from camera names, it is a guess from keywords in the camera's name. The database default is `'General'`. - The camera already stores `resource_group_code`, which links to the registered group's `resource_group_name`. - `zone_name` is served by the camera and entrance response models (including `EntranceStatistics`) and shown in the admin camera lists and search, the command deck camera list, and the statistics entrances table, labelled with the i18n key `occupancy.zoneLabel`. - CONTEXT.md names this concept **Camera Group**, with `_Avoid_: Zone, portal group`. **Desired behavior:** - Every response that served `zone_name` serves **`camera_group: str | None`** instead: the name of the camera's linked Camera Group, or `null` when the camera has no group (fallback discovery, or Empty/Unlisted group states). No alias, no deprecation period. Backend and frontend change together, since the only consumer is this repo's frontend. - Camera discovery **stops writing** `zone_name` and **drops the keyword-based zone guess**. Direction inference from the camera name stays. - The frontend shows the group name wherever the zone was shown. A camera with no group shows a localized **"No camera group" / "Sin grupo de cámaras"**, and stays searchable by name. Search matches the group name instead of the zone. - The label key becomes "Camera group" / "Grupo de cámaras". Rename the key to fit, e.g. `cameraGroupLabel`, in EN and ES. - The `counting_cameras.zone_name` column **stays in the table, unused**, marked legacy in the schema code. Dropping it is a separate low-priority cleanup (see below). - `docs/api/README.md` describes `camera_group`, and any OpenAPI field description uses the glossary term. **Key interfaces:** - Camera and entrance response models, including `EntranceStatistics`: `zone_name: str` → `camera_group: str | None`. - The repository reads of cameras and entrances join the camera's `resource_group_code` to its group's name. - `CountingCameraItem` and the discovery upsert: no `zone_name` input. **Acceptance criteria:** - [ ] No response model or frontend module reads or serves `zone_name`, apart from the legacy column definition. - [ ] A camera in a registered group serves that group's current name, and renaming the group upstream changes it on the next sync. - [ ] A camera with no group serves `camera_group: null`, and the UI shows the localized "no camera group" text in EN and ES. - [ ] Camera search in the admin list matches the group name, and still matches camera name and code. - [ ] Discovery no longer writes `zone_name`, and no zone is guessed from the camera name. Direction inference is unchanged, with a test. - [ ] The OpenAPI schema and `docs/api/README.md` document `camera_group` with Camera Group wording. - [ ] Python and frontend tests updated: the fixtures use `camera_group`, plus a grouped case and an ungrouped case. **Out of scope:** - Dropping the `zone_name` column. That is a separate low-priority issue. - Changing how Camera Groups are discovered, counted or measured (ADR 0005). - Any multi-camera group behaviour.
gabogg commented 2026-10-02 16:11:23 +00:00
Author
Owner
Copy link

This was generated by AI during triage.

The follow-up cleanup the brief mentions (dropping the unused zone_name column) is tracked in #209. It is low priority and blocked by this issue.

> *This was generated by AI during triage.* The follow-up cleanup the brief mentions (dropping the unused `zone_name` column) is tracked in #209. It is low priority and blocked by this issue.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
master
docs/test-policy-217
feat/historical-flow-publication
feat/historical-flow-curation
fix/holiday-stamping-followups
chore/schedule-p3-followups-186
fix/test-isolation
test/silent-camera-trace-199
feat/historical-flow-statistics
No results found.
Labels
Clear labels   
blocked
Waits on the issues listed in its "Blocked by:" line before implementation

  
bug
Category: something is broken; behaviour differs from the spec or docs

  
enhancement
Category: new feature or improvement, including refactors, chores and docs

  
high-priority
Address before ordinary-priority work; independent of triage readiness and blockers

  
low-priority
Address after ordinary-priority work; independent of triage readiness and blockers

  
needs-info
Waiting on reporter for more information

  
needs-triage
Maintainer needs to evaluate this issue

  
ready-for-agent
Fully specified, ready for an AFK agent

  
ready-for-human
Requires human implementation

  
referenced
Previously closed issue reopened or referenced by an open issue; visible history marker

  
research
Needs investigation (internet or local resources) before it can be triaged down; used alongside a category and a triage role

  
wontfix
Will not be actioned

No labels
blocked
bug
enhancement
high-priority
low-priority
needs-info
needs-triage
ready-for-agent
ready-for-human
referenced
research
wontfix
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
gabogg/hikcentral#200
No description provided.