Translate face alarm design doc to Chinese

docs/design/FaceRecognition_TrackAware_Alarm_Design.md

@@ -1,138 +1,138 @@
-# Face Recognition Track-Aware Alarm Design
+# 人脸识别按轨迹聚合告警设计
 
-## 1. Background
+## 1. 背景
 
-The current face recognition alarm path is:
+当前人脸识别告警链路为：
 
 `face_det -> face_recog -> alarm.face_rules -> actions`
 
-This path is already able to:
+现有链路已经具备以下能力：
 
-- recognize known persons from the gallery
-- classify single-frame results as `known` or `unknown`
-- generate `known_person` and `unknown_face` alarms
-- upload snapshots and clips through the existing alarm action chain
+- 从 gallery 中识别已知人员
+- 基于单帧识别结果判定 `known` 或 `unknown`
+- 生成 `known_person` 和 `unknown_face` 告警
+- 通过现有 alarm action 链路上传截图和视频片段
 
-However, current alarm behavior is still dominated by single-frame face recognition results. In workshop testing, the same known person can produce:
+但当前告警行为仍然主要由单帧人脸识别结果驱动。在车间测试中，同一个已知人员可能出现：
 
-- `known_person` alarms on close, high-quality frames
-- `unknown_face` alarms on far, small, or low-quality frames
+- 近距离、高质量帧触发 `known_person`
+- 远距离、小脸、低质量帧触发 `unknown_face`
 
-This is not acceptable for the target workshop scenario. In this scenario:
+这不符合目标场景要求。对当前车间场景来说：
 
-- low-quality face observations can be ignored
-- alarm accuracy is more important than alarm recall
-- alarm frequency must stay low
-- known-person alarms are used as attendance punch events
-- short leave-and-return behavior should not generate repeated punch alarms
+- 低质量人脸数据可以直接忽略
+- 告警准确率优先于告警召回率
+- 告警频率需要尽量低
+- 已知人员告警用于后台打卡
+- 人员短暂离场再进入，不应重复触发打卡告警
 
-The repository already has a person tracker and shoe-related logic that rely on `track_id`. This design reuses that capability instead of introducing a second face-specific tracker.
+仓库中已经有人体 tracker 和基于 `track_id` 的鞋子识别逻辑。本设计优先复用这套能力，而不是再新增一套独立的人脸 tracker。
 
-## 2. Goals
+## 2. 目标
 
-### 2.1 Functional Goals
+### 2.1 功能目标
 
-- Reuse existing person `track_id` for face identity aggregation.
-- Stop treating `unknown` as the direct opposite of `known`.
-- Ignore low-quality face observations instead of forcing them into `unknown_face`.
-- Generate face alarms per tracked person instead of per single frame.
-- Prevent duplicate alarms while the same person remains in the scene.
-- Prevent immediate repeated alarms after a short leave-and-return event.
+- 复用现有人体 `track_id` 进行人脸身份聚合
+- 不再把 `unknown` 简单视为 `known` 的反面
+- 对低质量人脸直接忽略，而不是强行归类为 `unknown_face`
+- 告警由“按单帧”改为“按人轨迹”
+- 同一个人持续在场时不重复触发告警
+- 人员短时离场再进入时不立即重复告警
 
-### 2.2 Non-Goals
+### 2.2 非目标
 
-- Do not replace the existing person tracker implementation.
-- Do not introduce a new standalone face tracker.
-- Do not change face embedding extraction or gallery search behavior.
-- Do not merge detection, recognition, tracking, and alarming into one plugin.
+- 不替换现有人体 tracker 实现
+- 不新增独立的人脸 tracker
+- 不修改人脸 embedding 提取和 gallery 检索逻辑
+- 不把检测、识别、跟踪、告警合并到一个插件中
 
-## 3. Current State Review
+## 3. 现状分析
 
-### 3.1 What Already Exists
+### 3.1 已有能力
 
 - `plugins/tracker/tracker_node.cpp`
-  - assigns stable `track_id` values to person detections in `frame->det`
+  - 会给 `frame->det` 中的人体检测框写入稳定的 `track_id`
 - `plugins/logic_gate/logic_gate_node.cpp`
-  - already consumes person `track_id` for shoe-related reasoning
-- `plugins/ai_face_det/*` and `plugins/ai_face_recog/ai_face_recog_node.cpp`
-  - already produce face detection and recognition results
+  - 已经基于人体 `track_id` 做鞋子关联与规则判断
+- `plugins/ai_face_det/*` 与 `plugins/ai_face_recog/ai_face_recog_node.cpp`
+  - 已经能输出人脸检测和人脸识别结果
 - `plugins/alarm/alarm_node.cpp`
-  - already supports face-specific rules and the existing alarm action chain
+  - 已经支持人脸规则和现有告警 action 链路
 
-### 3.2 Current Gap
+### 3.2 当前缺口
 
-The current face path does not actually reuse person tracking:
+当前人脸链路实际上没有接入人体跟踪能力：
 
-- `FaceDetItem` has a `track_id` field, but face detectors currently fill it with `-1`
-- `FaceRecogItem` only carries gallery identity fields such as `best_person_id`
-- face alarm vote keys currently use:
-  - `best_person_id` for known-person rules
-  - constant `unknown` for unknown-person rules
+- `FaceDetItem` 虽然有 `track_id` 字段，但当前人脸检测节点都填的是 `-1`
+- `FaceRecogItem` 只保留了 gallery 身份字段，如 `best_person_id`
+- 当前人脸告警投票 key 为：
+  - 已知人规则使用 `best_person_id`
+  - 陌生人规则直接使用固定值 `unknown`
 
-This means current face alarm behavior cannot answer:
+这意味着当前人脸告警链路无法回答以下问题：
 
-- whether two frames belong to the same physical person
-- whether a temporary low-score frame belongs to a person already recognized moments earlier
-- whether an alarm should be suppressed because the person is still on screen
+- 两帧是否属于同一个真实人
+- 某一帧的低分结果是否属于刚刚已经识别成功的那个人
+- 某人还在画面中时，是否应该抑制重复告警
 
-## 4. Design Summary
+## 4. 设计概述
 
-The design adds a track-aware identity aggregation layer on top of existing person tracking.
+本设计在现有人体跟踪之上增加“按轨迹聚合的人脸身份确认层”。
 
-The revised behavior is:
+改造后的行为如下：
 
-1. Person detections continue to receive `track_id` from the existing tracker.
-2. Each recognized face is associated with one tracked person in the same frame.
-3. The associated `person_track_id` is stored on face recognition results.
-4. Alarm logic aggregates recognition evidence per `person_track_id`.
-5. The alarm decision becomes three-state:
+1. 人体检测继续由现有 tracker 生成 `track_id`
+2. 每张识别出的人脸在同帧内关联到一个人体框
+3. 将关联后的人体 `track_id` 写入人脸识别结果
+4. `alarm` 按 `person_track_id` 聚合多帧识别证据
+5. 身份判定改为三态：
    - `known`
    - `unknown`
    - `uncertain`
-6. Only stable `known` or stable `unknown` states may trigger alarms.
-7. `uncertain` observations are ignored.
+6. 只有稳定的 `known` 或稳定的 `unknown` 才允许触发告警
+7. `uncertain` 状态直接忽略，不触发身份类告警
 
-This preserves the existing DAG architecture and keeps responsibilities separated:
+这样可以保持当前 DAG 架构和插件边界不变：
 
-- tracker tracks persons
-- face plugins produce recognition evidence
-- alarm node owns business-facing identity confirmation and deduplication
+- tracker 只负责跟踪人体
+- 人脸插件只负责输出识别证据
+- alarm 节点负责业务层面的身份确认、去重和抑制
 
-## 5. Data Flow
+## 5. 数据流设计
 
-The intended runtime path becomes:
+目标运行链路变为：
 
 `person_det -> tracker -> face_det -> face_recog(face-person association) -> alarm(track-aware face rules) -> actions`
 
-### 5.1 Face-to-Person Association
+### 5.1 人脸与人体关联
 
-For each recognized face in a frame, associate it to one person detection from `frame->det` that already has a valid `track_id`.
+对每一张识别出的人脸，在同一帧的 `frame->det` 中寻找一个已经具备有效 `track_id` 的人体框进行关联。
 
-Recommended matching order:
+建议采用以下匹配顺序：
 
-1. Prefer person boxes that contain the face center point.
-2. If multiple person boxes qualify, choose the one with the highest overlap quality.
-3. If no containing person box exists, optionally fall back to IoU / overlap ratio matching.
-4. If no reliable match exists, leave the face unassociated.
+1. 优先选择“人脸中心点落在人框内”的人体框
+2. 若存在多个候选，则选择重叠关系最合理的那个
+3. 若不存在包含关系，可选地退化到 IoU / overlap ratio 匹配
+4. 若仍无可靠匹配，则该人脸视为未关联成功
 
-This keeps the matching logic simple and aligned with the workshop camera scenario, where one face should usually lie inside one person box.
+这个方案简单、稳定，也更适合当前车间摄像头场景，因为正常情况下一个人脸应当落在一个人体框内部。
 
-### 5.2 Result Enrichment
+### 5.2 结果增强
 
-Extend face recognition results with the associated person track metadata.
+对人脸识别结果增加与人体轨迹关联后的字段。
 
-Recommended additions to `FaceRecogItem`:
+建议给 `FaceRecogItem` 增加：
 
 - `int person_track_id = -1`
-- optional future field: `float person_match_score`
+- 可选预留字段：`float person_match_score`
 
-This lets downstream plugins consume face identity evidence with person continuity information, without coupling them to raw person detections.
+这样下游插件可以直接消费“带有人体连续性信息的人脸识别结果”，而不用再次读取原始人体框做推断。
 
-## 6. Identity State Model
+## 6. 身份状态模型
 
-Per `person_track_id`, maintain a short-lived identity aggregation state in the alarm node.
+在 `alarm` 节点中，按 `person_track_id` 维护一份短生命周期的人脸身份聚合状态。
 
-Recommended tracked fields:
+建议维护的字段包括：
 
 - `track_id`
 - `first_seen_ms`
@@ -148,144 +148,144 @@ Recommended tracked fields:
 - `reported_unknown`
 - `last_report_ms`
 
-The state exists only while the track is active, plus a short retention window needed for re-entry suppression.
+这份状态在轨迹有效期间存在，并在短暂 retention 窗口内保留，用于实现短时离场重入抑制。
 
-## 7. Three-State Decision Model
+## 7. 三态判定模型
 
-### 7.1 States
+### 7.1 状态定义
 
-Each person track may be in one of three states:
+每个 `person_track_id` 只能处于以下三种状态之一：
 
 - `uncertain`
-  - insufficient quality or insufficient evidence
+  - 质量不足，或证据不足
 - `known`
-  - stable evidence for one known gallery identity
+  - 已经稳定确认属于某个已知人员
 - `unknown`
-  - stable evidence that the tracked person is not matching known identities
+  - 已经稳定确认无法归属到已知人员
 
-### 7.2 Why `uncertain` Is Required
+### 7.2 为什么必须引入 `uncertain`
 
-`uncertain` is the key change for this scenario.
+`uncertain` 是本方案的关键。
 
-Examples that should remain `uncertain`:
+以下情况都应保持为 `uncertain`：
 
-- face too small
-- poor alignment
-- temporary blur
-- far-distance observations
-- unstable similarity fluctuations
-- too few valid observations for the current track
+- 人脸太小
+- 对齐质量差
+- 运动模糊
+- 距离过远
+- 相似度波动明显
+- 当前轨迹累计证据不足
 
-These observations should not generate any identity alarm.
+这些观察结果都不应直接触发身份类告警。
 
-## 8. Quality Gating
+## 8. 质量门控
 
-Only quality-qualified face observations should participate in identity aggregation.
+只有通过质量门控的人脸观测，才允许进入身份聚合逻辑。
 
-Recommended quality checks:
+建议质量条件包括：
 
-- associated `person_track_id >= 0`
-- face area ratio above configured minimum
-- face aspect ratio within configured bounds
-- landmarks available when alignment is required
-- optional minimum bbox size in pixels
-- optional minimum confidence from face detection
+- 已关联到有效 `person_track_id`
+- 人脸面积占比达到下限
+- 人脸长宽比处于合理范围
+- 当需要对齐时，必须具备有效 landmarks
+- 可选：人脸最小像素宽高门限
+- 可选：最小人脸检测置信度
 
-If a frame fails quality gating:
+若某一帧未通过质量门控：
 
-- do not count it toward `unknown`
-- do not count it toward `known`
-- keep the track state as `uncertain`
+- 不计入 `unknown`
+- 不计入 `known`
+- 保持该轨迹状态为 `uncertain`
 
-This directly matches the workshop requirement: low-quality data can be ignored.
+这与当前车间场景的业务要求一致：低质量数据可以直接忽略。
 
-## 9. Known-Person Confirmation
+## 9. 已知人确认策略
 
-Known-person confirmation should require repeated evidence for the same gallery identity on the same tracked person.
+已知人确认必须基于“同一人体轨迹内，对同一 gallery 身份的持续命中”。
 
-Recommended conditions:
+建议条件如下：
 
-- face passed quality gating
+- 当前帧通过质量门控
 - `best_person_id >= 0`
 - `best_sim >= known_accept`
 - `(best_sim - second_sim) >= known_margin`
-- same `best_person_id` observed at least `known_min_hits` times inside `known_hit_window_ms`
+- 在 `known_hit_window_ms` 时间窗内，同一个 `best_person_id` 至少命中 `known_min_hits` 次
 
-Optional improvement:
+可选增强：
 
-- allow a peak-sim shortcut when `best_sim` is very high and consistent
+- 若 `best_sim` 足够高且连续稳定，可允许 peak-sim 快速确认
 
-Once the track reaches stable `known`:
+一旦某条轨迹稳定进入 `known`：
 
-- trigger `known_person`
-- mark the track as `reported_known`
-- suppress all later known alarms for the same active track
+- 触发一次 `known_person`
+- 标记该轨迹 `reported_known = true`
+- 在该轨迹存活期间不再重复触发已知人告警
 
-## 10. Unknown-Person Confirmation
+## 10. 陌生人确认策略
 
-Unknown-person confirmation must be stricter than known-person confirmation.
+陌生人确认必须比已知人确认更保守。
 
-Unknown should not mean:
+陌生人不应被定义为：
 
-- "this frame is not known"
+- “这一帧不是 known”
 
-Unknown should mean:
+陌生人应被定义为：
 
-- "this tracked person has been observed long enough, at sufficient quality, and still cannot be confirmed as any known person"
+- “这个人已经被持续观察了足够长时间，且人脸质量足够，但始终无法稳定归入任何已知身份”
 
-Recommended conditions:
+建议条件如下：
 
-- face passed quality gating
-- valid `person_track_id`
-- track age exceeds `unknown_min_track_age_ms`
-- quality-qualified observations reach `unknown_min_quality_hits`
-- no stable known identity has been confirmed for this track
-- recognition remains below known confirmation thresholds during the window
+- 当前帧通过质量门控
+- 存在有效 `person_track_id`
+- 轨迹存活时间超过 `unknown_min_track_age_ms`
+- 质量合格帧数达到 `unknown_min_quality_hits`
+- 该轨迹尚未稳定确认过已知人
+- 在观察窗口内始终未满足已知人确认条件
 
-Optional additional conditions:
+可选附加条件：
 
-- require the top candidate identity to remain inconsistent
-- require multiple low-confidence or ambiguous frames before final unknown confirmation
+- top1 候选身份长期不稳定
+- 多帧均处于低置信或模糊匹配状态后，才允许最终确认陌生人
 
-Once the track reaches stable `unknown`:
+一旦某条轨迹稳定进入 `unknown`：
 
-- trigger `unknown_face`
-- mark the track as `reported_unknown`
-- suppress all later unknown alarms for the same active track
+- 触发一次 `unknown_face`
+- 标记该轨迹 `reported_unknown = true`
+- 在该轨迹存活期间不再重复触发陌生人告警
 
-## 11. Alarm Deduplication and Re-Entry Control
+## 11. 告警去重与重入抑制
 
-### 11.1 Active-Track Deduplication
+### 11.1 轨迹内去重
 
-Within one active `person_track_id`:
+在同一个活跃 `person_track_id` 内：
 
-- `known_person` may trigger at most once
-- `unknown_face` may trigger at most once
+- `known_person` 最多只允许触发一次
+- `unknown_face` 最多只允许触发一次
 
-### 11.2 Re-Entry Suppression
+### 11.2 离场重入抑制
 
-The workshop scenario treats known-person alarms as punch events. Therefore:
+当前场景中的已知人告警，本质上是打卡行为，因此：
 
-- if the same known employee remains on screen, do not re-alarm
-- if the same known employee briefly leaves and re-enters, do not re-alarm immediately
+- 同一个员工仍在画面中时，不应重复打卡
+- 同一个员工短暂离开又回来时，也不应立即重复打卡
 
-Recommended suppression keys:
+建议引入两类抑制 key：
 
-- known person: keyed by `gallery person_id`
-- unknown person: keyed by recent track history or a future stronger fingerprint
+- 已知人：按 `gallery person_id` 做冷却
+- 陌生人：按最近轨迹历史做冷却，后续可再增强为更稳定的陌生人指纹
 
-Recommended timers:
+建议增加两个可配置时间：
 
 - `known_reentry_cooldown_ms`
 - `unknown_reentry_cooldown_ms`
 
-Known-person suppression should be relatively long, because attendance punching should be sparse.
+对于已知人，冷却时间应当相对较长，因为打卡行为本来就应当是稀疏的。
 
-## 12. Configuration Design
+## 12. 配置设计
 
-Introduce a dedicated face track aggregation config section under the alarm face-rule path or a sibling alarm section.
+建议在 `alarm` 侧新增一组专门的人脸轨迹聚合配置。可以挂在 face rule 相关路径下，或作为 alarm 的一个同级子配置。
 
-Recommended fields:
+建议字段如下：
 
 ```json
 {
@@ -317,164 +317,164 @@ Recommended fields:
 }
 ```
 
-Notes:
+说明：
 
-- exact placement may be adjusted to match current config conventions
-- existing face rule fields should remain supported where practical
-- migration should minimize breaking existing configs
+- 具体挂载位置可再根据现有配置风格微调
+- 尽量保留现有 face rule 字段，避免一次性破坏旧配置
+- 迁移时应优先保证兼容性和平滑切换
 
-## 13. File-Level Changes
+## 13. 文件级改动建议
 
-### 13.1 Data Model
+### 13.1 数据结构
 
-Modify:
+修改：
 
 - `include/face/face_result.h`
 
-Changes:
+改动内容：
 
-- add `person_track_id` to `FaceRecogItem`
-- optionally add future-friendly metadata for association confidence
+- 给 `FaceRecogItem` 增加 `person_track_id`
+- 可选预留后续关联置信度等扩展字段
 
-### 13.2 Face Recognition Node
+### 13.2 人脸识别节点
 
-Modify:
+修改：
 
 - `plugins/ai_face_recog/ai_face_recog_node.cpp`
 
-Changes:
+改动内容：
 
-- associate each recognized face to a tracked person from `frame->det`
-- write `person_track_id` into `FaceRecogItem`
-- extend debug log output to include `person_track_id`
+- 对每张识别结果做人脸与人体关联
+- 将关联后的人体 `track_id` 写入 `FaceRecogItem`
+- 扩展 debug 日志，输出 `person_track_id`
 
-### 13.3 Alarm Node
+### 13.3 告警节点
 
-Modify:
+修改：
 
 - `plugins/alarm/alarm_node.cpp`
 
-Changes:
+改动内容：
 
-- add track-aware face identity aggregation state
-- replace per-frame unknown alarm behavior with track-based unknown confirmation
-- change face vote key logic to prefer `person_track_id`
-- add deduplication and re-entry suppression based on track-aware identity state
+- 增加按轨迹聚合的人脸身份状态
+- 用按 `track_id` 的持续观察，替代当前单帧驱动的陌生人确认逻辑
+- face vote key 优先使用 `person_track_id`
+- 增加已知人 / 陌生人的按轨迹去重和离场重入抑制
 
-### 13.4 Tests
+### 13.4 测试
 
-Modify or add:
+建议新增或修改以下平台无关测试：
 
-- platform-independent unit tests for association logic
-- platform-independent unit tests for track-aware known confirmation
-- platform-independent unit tests for track-aware unknown suppression
-- platform-independent unit tests for re-entry cooldown behavior
+- 人脸与人体关联逻辑测试
+- 按轨迹已知人确认测试
+- 按轨迹陌生人抑制测试
+- 离场重入冷却测试
 
-## 14. Compatibility and Migration
+## 14. 兼容性与迁移策略
 
-The design should be introduced in a backward-aware way.
+该设计应以“向后兼容优先”的方式落地。
 
-Recommended compatibility strategy:
+建议策略：
 
-1. keep existing face recognition output fields unchanged
-2. add new fields instead of renaming old ones
-3. keep current config behavior available when track-aware aggregation is disabled
-4. allow current face rules to coexist with the new aggregation mode during rollout
+1. 保留现有 face recognition 输出字段
+2. 用新增字段而不是重命名旧字段
+3. 当 track-aware aggregation 未开启时，继续支持当前旧行为
+4. 在 rollout 期间允许旧 face rules 与新聚合模式并存，用于对比效果
 
-This enables:
+这样可以实现：
 
-- safer staged rollout
-- easier comparison between old and new behavior
-- simpler troubleshooting on RK3588
+- 更安全的分阶段上线
+- 便于对比新旧逻辑行为差异
+- 更容易在 RK3588 上做联调和回归
 
-## 15. Validation Strategy
+## 15. 验证策略
 
-### 15.1 Local Code-Level Validation
+## 15.1 本地代码级验证
 
-Local validation should focus on platform-independent logic only:
+本地验证只聚焦平台无关逻辑：
 
-- face-to-person association behavior
-- aggregation state transitions
-- known confirmation window logic
-- unknown suppression logic
-- re-entry cooldown behavior
-- config parsing and backward compatibility
+- 人脸与人体关联行为
+- 聚合状态机状态转换
+- 已知人确认窗口逻辑
+- 陌生人抑制逻辑
+- 离场重入冷却逻辑
+- 配置解析与兼容性
 
-### 15.2 RK3588 Device-Side Validation
+## 15.2 RK3588 设备侧验证
 
-Final validation must be completed on RK3588:
+最终验证必须在 RK3588 上完成：
 
-- known person from far to near
-  - expect delayed but stable known-person alarm
-  - no unknown false alarm
-- known person brief leave and quick re-entry
-  - expect no repeated punch alarm
-- known person long leave and re-entry after cooldown
-  - expect one new punch alarm
-- truly unknown person with adequate face quality
-  - expect one unknown alarm after evidence accumulation
-- low-quality unknown face
-  - expect no alarm
-- multiple persons in frame
-  - verify face-person association uses the correct person track
+- 已知人从远到近进入画面
+  - 预期：延迟但稳定触发 `known_person`
+  - 预期：不出现 `unknown_face` 误报
+- 已知人短暂离场并快速重入
+  - 预期：不重复触发打卡
+- 已知人长时间离场并超过冷却后再进入
+  - 预期：允许再次打卡
+- 真正陌生人且人脸质量足够
+  - 预期：经过持续观察后触发一次 `unknown_face`
+- 低质量陌生人
+  - 预期：不触发告警
+- 同帧多个人体
+  - 预期：人脸与人体关联正确，不串轨
 
-## 16. Risks and Mitigations
+## 16. 风险与缓解
 
-### Risk 1: Incorrect face-person association
+### 风险 1：人脸与人体关联错误
 
-Impact:
+影响：
 
-- identity evidence may be attached to the wrong tracked person
+- 识别证据可能被挂到错误的人体轨迹上
 
-Mitigation:
+缓解：
 
-- start with simple center-in-box matching
-- log `person_track_id` and association decisions in debug mode
-- validate on multi-person RK3588 scenes
+- 初版先采用简单稳定的 center-in-box 匹配
+- 在 debug 模式下输出 `person_track_id` 与关联决策
+- 在 RK3588 多人场景中重点验证
 
-### Risk 2: Unknown confirmation becomes too conservative
+### 风险 2：陌生人确认过于保守
 
-Impact:
+影响：
 
-- unknown alarms may be delayed or reduced
+- 陌生人告警触发变慢，或数量减少
 
-Mitigation:
+缓解：
 
-- make unknown thresholds configurable
-- prefer under-reporting over false workshop alerts in early rollout
+- 所有陌生人阈值均做成可配置
+- 在早期 rollout 阶段宁可少报，也不要在车间场景中误报
 
-### Risk 3: Re-entry suppression too aggressive
+### 风险 3：离场重入抑制过强
 
-Impact:
+影响：
 
-- valid repeated attendance events may be skipped
+- 合法的重复打卡事件可能被压掉
 
-Mitigation:
+缓解：
 
-- make re-entry cooldown configurable
-- document business interpretation clearly as punch-style attendance
+- 冷却时间全部做成可配置
+- 在文档与配置说明中明确“当前业务语义是打卡型告警，而不是持续在场播报”
 
-## 17. Rollout Recommendation
+## 17. 推荐落地顺序
 
-Recommended rollout order:
+建议按以下顺序逐步落地：
 
-1. add `person_track_id` propagation and debug logs
-2. add track-aware known confirmation
-3. add conservative track-aware unknown confirmation
-4. add re-entry suppression tuning
-5. validate behavior on RK3588 with known and unknown workshop videos
+1. 增加 `person_track_id` 传递和 debug 日志
+2. 实现按轨迹的已知人确认
+3. 实现保守的按轨迹陌生人确认
+4. 加入离场重入抑制
+5. 在 RK3588 上用已知人 / 陌生人视频做回归验证
 
-This staged rollout reduces risk and allows behavior comparison at each step.
+分阶段落地可以降低风险，也更方便逐步对比行为变化。
 
-## 18. Expected Outcome
+## 18. 预期效果
 
-After this design is implemented, the system should behave as follows in the workshop face-recognition scenario:
+设计实现后，车间人脸识别告警行为应达到以下效果：
 
-- poor-quality face observations are ignored
-- the same known employee is confirmed from accumulated evidence, not single-frame luck
-- transient low-score frames do not become stranger alarms
-- a person who stays in scene triggers at most one identity alarm
-- short leave-and-return behavior does not trigger repeated punch alarms
-- stranger alarms become rarer but more trustworthy
+- 低质量人脸观测被直接忽略
+- 已知员工通过多帧聚合而非单帧偶然命中被确认
+- 同一个已知人不会因为个别低分帧被误报为陌生人
+- 同一个人在场期间最多触发一次身份类告警
+- 人员短时离场再进入时不会重复打卡
+- 陌生人告警数量减少，但可信度明显提高
 
-This is the intended trade-off for the workshop deployment: lower alarm frequency and higher alarm precision.
+这正是当前车间部署所需要的取舍方向：降低告警频率，提高告警精度。