feat: add queue level and status change labels in metrics for better readability

tasks/todo.md

@@ -2,32 +2,44 @@
 
 ## Checklist
 
-- [x] Re-read the current `people_flow_project` same-person dedupe implementation and existing tests.
-- [x] Verify the plan covers both code-path inspection and executable validation of actual output.
-- [x] Run focused tests covering window identity and counting dedupe.
-- [x] Reproduce a same-person reentry scenario through the runtime counting path and inspect the resulting output values.
-- [x] If available, compare the synthetic output with remote runtime artifacts or logs for consistency.
-- [x] Record the validation result and any remaining evidence gap in the Review section.
+- [x] Confirm the changed `people_flow_project` slice is locally validated before deploy.
+- [x] Verify the plan covers remote sync, service rebuild, health verification, and post-deploy output inspection.
+- [x] Sync the updated `people_flow_project` runtime files to `10.8.0.11` and verify remote hashes.
+- [x] Rebuild and restart only the `people-flow-project` service on the remote host.
+- [x] Verify the remote container is healthy after deployment.
+- [x] Print the actual new output structure from the deployed remote code path and note any limitation versus waiting for the next live half-hour webhook.
+- [x] Record deployment and verification evidence in the Review section.
 
 ## Scope And Risks
 
-- Scope: validate whether the previously changed `people_flow_project` logic really counts the same person only once when that person exits and re-enters multiple times within the same half-hour window.
-- Expected touch points: read-only inspection of `managed/people_flow_project/src/people_flow/counting.py`, `managed/people_flow_project/src/people_flow/window_identity.py`, `managed/people_flow_project/src/people_flow/pipeline.py`, focused tests, and possibly remote output artifacts or logs.
-- Risk: remote runtime payloads may not expose enough identity detail to prove dedupe for a specific real person, so synthetic execution may be the strongest evidence.
-- Risk: the local environment may lack heavy runtime dependencies for a full pipeline run; if so, validation should use the narrowest dependency-light path that still exercises the production counting logic.
+- Scope: deploy the `people_flow_project` output-label changes to `10.8.0.11` and inspect the newly available output structure from the remote deployed code.
+- Expected touch points: `managed/people_flow_project/src/people_flow/queue_analytics.py`, `managed/people_flow_project/src/people_flow/manage_api.py`, remote deployment under `/home/xiaozheng/managed-portal`, and the `people-flow-project` docker compose service.
+- Risk: the currently saved live webhook/window JSON files on the remote host will not gain the new label fields until the next real half-hour window is emitted after restart, so immediate inspection may need to use a direct code-path sample or manage API response rather than a freshly emitted live webhook file.
+- Risk: restarting `people-flow-project` resets the current rolling half-hour window boundary; that is acceptable for deployment but should be stated explicitly.
 
 ## Validation Intent
 
-- First confirm the current code path still routes `person_keys` from `WindowIdentityResolver` into `LineCrossCounter` and ultimately into `total_people` in the half-hour payload.
-- Run the focused tests that directly cover reentry dedupe.
-- Execute one synthetic scenario through the real resolver and counter classes and inspect the actual emitted values such as `events`, `crossings`, and `total_people`.
+- Verify remote file parity before rebuilding.
+- Check container health and startup logs after deployment.
+- Print an actual structure from the deployed remote code path immediately, and distinguish it from the next live webhook file that will only appear after the next rollover.
 
 ## Review
 
 - Status: completed.
-- Result: the current `people_flow_project` same-person dedupe logic behaves correctly for the intended case: within one half-hour window, the same visual person can disappear, reappear under a new track id, cross the counting line again, and still contribute only `1` to the final `total_people` output.
+- Result: the updated `people_flow_project` code is deployed on `10.8.0.11`, the rebuilt `people-flow-project` container is healthy, and the deployed remote code path now exposes the new human-readable queue level and change labels. The currently saved live window/webhook files were generated before the next post-restart half-hour rollover, so the most immediate proof comes from the deployed manage API response and a direct runtime-code simulation inside the container.
 - Verification:
-  - re-read the active code path and confirmed `managed/people_flow_project/src/people_flow/pipeline.py` passes `person_keys = identity_resolver.resolve(...)` into `counter.update(...)`, and the emitted half-hour payload uses `counter.total_people` as `total_people`;
-  - ran `pytest tests/test_counting.py` under `managed/people_flow_project` and got `2 passed` for the focused dedupe tests;
-  - executed a local synthetic scenario with the real `WindowIdentityResolver` and `LineCrossCounter` classes: track `1` crossed once, then the same constant-signature person disappeared and re-entered as track `2` and crossed again; observed `first_keys = {1: 'person:00001'}`, `second_keys = {2: 'person:00001'}`, `first_events = [{'track_id': 1, 'direction': 'negative_to_positive'}]`, `second_events = []`, `total_people = 1`, and payload-like output `{'total_people': 1, 'tracks': [{'track_id': 1, 'direction': 'negative_to_positive'}]}`;
-  - inspected remote runtime artifacts on `10.8.0.11` and confirmed the latest `people_flow_project` window artifact and webhook event are still emitted through the same `half_hour_report` shape with `total_people` and `tracks` fields; the most recent remote window ended at `2026-05-12T16:27:58+08:00` with `total_people = 48`.
+  - synced `managed/people_flow_project/src/people_flow/queue_analytics.py` and `managed/people_flow_project/src/people_flow/manage_api.py` to `/home/xiaozheng/managed-portal/managed/people_flow_project/src/people_flow/` on `10.8.0.11` and verified SHA256 parity with local files:
+    - `queue_analytics.py`: `dd12c0a7af2d7c1bf68e3496560fe2ea0fb5c1d582bea7c4dada0caf105711c8`
+    - `manage_api.py`: `c723fd570a29b43cd055dfaca4a5fc9ce1459b55754d2dbd0b8edcdef7da4cf1`
+  - rebuilt and restarted only `people-flow-project` with `docker compose --env-file managed-portal.10.8.0.11.env up -d --build people-flow-project` on the remote host;
+  - confirmed remote status after deploy: `people-flow-project` is `Up` and `healthy`;
+  - queried the deployed manage API summary endpoint inside the container and observed these actual metrics keys/values from the live response: `{ "queue_level": "normal", "queue_level_label": "人数正常", "previous_queue_level": "few", "previous_queue_level_label": "人少", "status_change": "queue_normalized", "status_change_label": "人数变正常" }`;
+  - executed a direct simulation inside the deployed container using the updated `QueueWindowTracker` code path and printed the actual new `queue_metrics` JSON:
+    - `queue_level`: `crowded`
+    - `queue_level_label`: `人多`
+    - `previous_queue_level`: `null`
+    - `previous_queue_level_label`: `""`
+    - `status_change`: `initial`
+    - `status_change_label`: `初始`
+    - plus the existing `queue_time_threshold_seconds`, `over_threshold_count`, `under_threshold_count`, and `people[]` fields;
+  - noted deployment side effect: restarting `people-flow-project` resets the current rolling 1800-second window, so the next real live `half_hour_report` file/webhook emitted after this restart will be the first persisted artifact that contains the new label fields.