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

feat(statistics): holiday and event context for investor analytics #161

New issue
Closed
opened 2026-09-27 16:29:42 +00:00 by gabogg · 1 comment
gabogg commented 2026-09-27 16:29:42 +00:00
Owner
Copy link

Maintainer request

Open holidays must remain included in statistics. Add an events concept and deck presentation for holidays and events, giving investors and analysts context for unusual figures. Example: a major World Cup match draws crowds to the mall screens without changing opening hours or being a holiday.

An event annotation is distinct from a schedule exception: it may explain unusual traffic without changing hours or implying a sensor fault. Treat this as analytical context, not proof of causation.

Further triage required

  • Define event identity, kinds, dates/time intervals, ownership and editing permissions, and overlap/multiple-event behavior.
  • Decide holiday/event display across day, week and month views, filters, exports and useful event-related KPIs/comparisons.
  • Decide Usual Weekday Baseline eligibility separately from inclusion in period totals. Current glossary excludes holidays from that baseline; holidays must not be excluded wholesale from statistics.
  • Define the relation to Closed Days and schedule exceptions. An annotation alone must not silently imply closure.
  • Decide how annotations coexist with Data-Quality Markers and Cycle Verdicts; unusual traffic is not itself bad sensor data.
  • Define historical annotation/edit behavior and whether any edits affect calibration; coordinate the next-day calibration/time-change policy in #114.

Related: #108 (schedule terminology), #114 (scheduled configuration changes).

This captures an accepted product direction, not a completed implementation specification. Keep needs-triage until the interview settles these decisions.

Confirmed triage resolution — 2026-09-27

This resolution supersedes the further-triage list above. Maintainer confirmed the complete shared understanding and authorized publication.

Accepted scope and behavior

  • #108: use Schedule Exception as the umbrella for holiday hours, special hours
    and exceptional closures. Rename UI wording and documentation first; retain
    compatible API routes and storage names.
  • #161: holidays and events provide named context for atypical days. Open days
    remain in statistics. Holidays may have different operating hours; event
    annotations do not change hours or imply closure, faulty data or causation.
  • Support timed and whole-business-day event annotations, including overlapping
    events. Any overlap marks the entire facility business cycle as an Event Day.
    An event spanning the reset marks both cycles.
  • Holiday and event days do not contribute to automatic multiplier learning,
    uncertainty estimates, sample maturity or Usual Weekday Baselines. Independent
    integrity checks still run; passing days can remain trusted for statistics.
  • Historical annotations preserve existing calibration. Exclude affected days
    from future learning and usual comparisons; do not automatically recompute the
    existing calibration. A separately reviewed recalculation remains separate work.
  • Only admins create, edit and remove holiday and event annotations. Keep dated
    edit history and require a reason for changes affecting completed days.
    All users authorized to view statistics can read the annotations.
  • Initial presentation includes event names/times and holiday hours in day view,
    marked dates and a context list in week/month views, and context in statistics
    exports. Comparisons remain descriptive and do not claim event causation.
  • Holiday identity is separate from schedule overrides. A holiday is a named day
    marker that can optionally supply special hours. Renovations and emergency
    closures remain schedule exceptions without automatically becoming holidays.
    The current code's classification of every dated override as a holiday must
    not define the new domain distinction.
  • Event inputs require a name, allow an optional description, and support either
    a timed interval or a range of whole business days. Input uses facility time
    with its timezone shown. Timed intervals require start before end and exclude
    their end instant; an event ending exactly at reset does not mark the next cycle.
    Structured event categories are not required for the first release.
  • Removing or shortening an annotation restores future learning and usual-baseline
    eligibility to days no longer marked as holidays or events, subject to their
    independent quality checks. Preserve already-applied calibration and edit history.
  • An admin must classify existing mixed calendar entries before enabling the new
    eligibility rules. Preserve their operating hours and closure settings; do not
    infer holiday identity from entry names.
  • Holiday and event days may be compared against eligible ordinary weekdays with
    matching operating hours, while never supplying that baseline themselves. Show
    the existing insufficient-baseline reason when there are too few usable days.

Implementation and verification

Separate schedule overrides, holiday identity, event annotations, calibration learning eligibility and statistical data quality. Preserve #113's historical schedule rules and #114's effective-date rules: historical context edits do not silently change operating hours or applied calibration; prospective holiday hours follow the existing schedule activation rules.

Acceptance checks cover reset-boundary overlap, overlapping events, whole-business-day ranges, independent integrity verdicts, exclusion from every learning/uncertainty/maturity/baseline source, eligible atypical-day comparisons, historical edits and removals, admin authorization and edit reasons, classification of existing calendar entries, all three deck views and context-bearing statistics exports. Initial comparisons use the usual-weekday behavior specified above; no additional event KPI or event-filter feature is required by this resolution.

#108 owns the UI/docs terminology rename. Record #113/#114 as prerequisites for affected schedule-history and activation behavior; ready-for-agent denotes a settled specification and does not waive these dependencies. Application implementation remains follow-up work.

## Maintainer request Open holidays must remain included in statistics. Add an events concept and deck presentation for holidays and events, giving investors and analysts context for unusual figures. Example: a major World Cup match draws crowds to the mall screens without changing opening hours or being a holiday. An event annotation is distinct from a schedule exception: it may explain unusual traffic without changing hours or implying a sensor fault. Treat this as analytical context, not proof of causation. ## Further triage required - Define event identity, kinds, dates/time intervals, ownership and editing permissions, and overlap/multiple-event behavior. - Decide holiday/event display across day, week and month views, filters, exports and useful event-related KPIs/comparisons. - Decide Usual Weekday Baseline eligibility separately from inclusion in period totals. Current glossary excludes holidays from that baseline; holidays must not be excluded wholesale from statistics. - Define the relation to Closed Days and schedule exceptions. An annotation alone must not silently imply closure. - Decide how annotations coexist with Data-Quality Markers and Cycle Verdicts; unusual traffic is not itself bad sensor data. - Define historical annotation/edit behavior and whether any edits affect calibration; coordinate the next-day calibration/time-change policy in #114. Related: #108 (schedule terminology), #114 (scheduled configuration changes). This captures an accepted product direction, not a completed implementation specification. Keep needs-triage until the interview settles these decisions. ## Confirmed triage resolution — 2026-09-27 This resolution supersedes the further-triage list above. Maintainer confirmed the complete shared understanding and authorized publication. ### Accepted scope and behavior - #108: use Schedule Exception as the umbrella for holiday hours, special hours and exceptional closures. Rename UI wording and documentation first; retain compatible API routes and storage names. - #161: holidays and events provide named context for atypical days. Open days remain in statistics. Holidays may have different operating hours; event annotations do not change hours or imply closure, faulty data or causation. - Support timed and whole-business-day event annotations, including overlapping events. Any overlap marks the entire facility business cycle as an Event Day. An event spanning the reset marks both cycles. - Holiday and event days do not contribute to automatic multiplier learning, uncertainty estimates, sample maturity or Usual Weekday Baselines. Independent integrity checks still run; passing days can remain trusted for statistics. - Historical annotations preserve existing calibration. Exclude affected days from future learning and usual comparisons; do not automatically recompute the existing calibration. A separately reviewed recalculation remains separate work. - Only admins create, edit and remove holiday and event annotations. Keep dated edit history and require a reason for changes affecting completed days. All users authorized to view statistics can read the annotations. - Initial presentation includes event names/times and holiday hours in day view, marked dates and a context list in week/month views, and context in statistics exports. Comparisons remain descriptive and do not claim event causation. - Holiday identity is separate from schedule overrides. A holiday is a named day marker that can optionally supply special hours. Renovations and emergency closures remain schedule exceptions without automatically becoming holidays. The current code's classification of every dated override as a holiday must not define the new domain distinction. - Event inputs require a name, allow an optional description, and support either a timed interval or a range of whole business days. Input uses facility time with its timezone shown. Timed intervals require start before end and exclude their end instant; an event ending exactly at reset does not mark the next cycle. Structured event categories are not required for the first release. - Removing or shortening an annotation restores future learning and usual-baseline eligibility to days no longer marked as holidays or events, subject to their independent quality checks. Preserve already-applied calibration and edit history. - An admin must classify existing mixed calendar entries before enabling the new eligibility rules. Preserve their operating hours and closure settings; do not infer holiday identity from entry names. - Holiday and event days may be compared against eligible ordinary weekdays with matching operating hours, while never supplying that baseline themselves. Show the existing insufficient-baseline reason when there are too few usable days. ### Implementation and verification Separate schedule overrides, holiday identity, event annotations, calibration learning eligibility and statistical data quality. Preserve #113's historical schedule rules and #114's effective-date rules: historical context edits do not silently change operating hours or applied calibration; prospective holiday hours follow the existing schedule activation rules. Acceptance checks cover reset-boundary overlap, overlapping events, whole-business-day ranges, independent integrity verdicts, exclusion from every learning/uncertainty/maturity/baseline source, eligible atypical-day comparisons, historical edits and removals, admin authorization and edit reasons, classification of existing calendar entries, all three deck views and context-bearing statistics exports. Initial comparisons use the usual-weekday behavior specified above; no additional event KPI or event-filter feature is required by this resolution. #108 owns the UI/docs terminology rename. Record #113/#114 as prerequisites for affected schedule-history and activation behavior; ready-for-agent denotes a settled specification and does not waive these dependencies. Application implementation remains follow-up work.
gabogg commented 2026-10-02 14:57:43 +00:00
Author
Owner
Copy link

Maintainer decisions, 2026-10-02 (from PR #178's first review, r11)

  1. Existing calendar entries stay holidays. Dated overrides already marked as holidays in the old system remain holidays: closed all day, or open with their own holiday business hours.
    • This replaces the triage line "do not infer holiday identity" for existing data. No admin classification step is needed before the new eligibility rules apply.
    • Business-day schedule records already stamped for those days must carry is_holiday = 1 as well, so past holidays stay out of the Usual Weekday Baseline. There must be one source of holiday identity, not two that can disagree.
    • New closures (renovations, emergency closures) still don't become holidays automatically. The admin chooses this when creating them, and the default is not a holiday.
  2. Counter-spike check.
    • Holiday and Event Days are excluded from the spike-detection reference (the last trusted cycles' entries, trust_spike_window).
    • The spike check is skipped on Holiday and Event Days themselves.
    • Their other integrity checks still run: ratio, negative net, ingestion gaps and stalls, and burst flush. That keeps the "independent integrity verdict" without mislabelling genuine crowds as counter faults.

Whether holidays should be excluded from statistics at all is a separate open question, tracked in #202 (needs-triage). It doesn't change the rules above for now.

🤖 Generated with Claude Code

## Maintainer decisions, 2026-10-02 (from PR #178's first review, r11) 1. **Existing calendar entries stay holidays.** Dated overrides already marked as holidays in the old system remain holidays: closed all day, or open with their own holiday business hours. - This replaces the triage line *"do not infer holiday identity"* for **existing** data. No admin classification step is needed before the new eligibility rules apply. - Business-day schedule records already stamped for those days must carry `is_holiday = 1` as well, so past holidays stay out of the Usual Weekday Baseline. There must be one source of holiday identity, not two that can disagree. - **New** closures (renovations, emergency closures) still don't become holidays automatically. The admin chooses this when creating them, and the default is not a holiday. 2. **Counter-spike check.** - Holiday and Event Days are excluded from the spike-detection reference (the last trusted cycles' entries, `trust_spike_window`). - The spike check is skipped on Holiday and Event Days themselves. - Their other integrity checks still run: ratio, negative net, ingestion gaps and stalls, and burst flush. That keeps the *"independent integrity verdict"* without mislabelling genuine crowds as counter faults. Whether holidays should be excluded from statistics at all is a separate open question, tracked in #202 (`needs-triage`). It doesn't change the rules above for now. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
master
feat/historical-flow-statistics
feat/historical-flow-publication
docs/test-policy-217
feat/historical-flow-curation
fix/holiday-stamping-followups
chore/schedule-p3-followups-186
fix/test-isolation
test/silent-camera-trace-199
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
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#161
No description provided.