silver_pose/docs/review/2026-07-21-t101-t105-review.md

T-101〜T-105 代码审核记录

• 日期：2026-07-21
• 范围：T-101（安全配置）、T-102（视频源）、T-103（Pose 适配器）、T-104（跟踪与证据）、T-105（时序状态机）
• 视角：全栈开发工程师
• 基线验证：python -m pytest v1/tests -q → 20 passed
• 结论：单模块工艺整体偏高，问题集中在系统装配——五个 task 的单元测试各自通过，但当前拼不成一条能判摔倒的完整链路。进入 T-201 之前应先补第 1–3 项。

总体评价

• 模块职责与 04-architecture.md 的模块表严格对应；边界克制得当：Pose 不做业务结论、evidence 不报警、状态机不做副作用。
• 防御性校验到位：SHA-256 锁模型、pose/person/17×3 契约校验、config 拒绝内嵌 RTSP 凭证。
• 依赖注入（capture_factory / model_factory）使单元测试无需真实权重或摄像头，TDD 流程真实。
• 跨重连的时间戳单调性已正确处理（VideoSource._last_timestamp 不在重连时重置）。

问题清单（按优先级）

P1 · 两个 Evidence 类型没有桥接，摔倒判定核心逻辑缺失

• v1/evidence.py 产出 PoseEvidence（horizontal_pose、rapid_vertical_change、horizontal_angle_degrees…）。
• v1/fall_state.py 消费另一个 Evidence（is_fall_candidate、is_recovery_candidate）。
• 全仓库无任何代码把前者映射为后者。即"什么几何证据算 is_fall_candidate / is_recovery_candidate"这一真正的领域决策目前为空。
• 影响：看似完成度高，实际把最有业务风险的一环留在无人负责的缝隙。
• 建议：在 T-201 之前明确它落在 app.py 还是 evidence.py，并为该映射单独写正反例测试，不要混入 GUI task。

P2 · config 有两个字段被解析校验但从不消费（配置-现实漂移）

• event.suspect_window_seconds 与 event.cooldown_seconds 在 v1/config.py 完整解析并出现在 config.example.json，但全仓库无消费点。
• cooldown_seconds 尤其冲突：04-architecture.md 状态模型写"经配置冷却与恢复稳定站立 → RECOVERING"，而 fall_state.py 中 CONFIRMED→RECOVERING 一收到 recovery 证据即转，无任何 cooldown。
• 违反项目纪律"需求或代码现实变化时必须同步"。
• 建议：要么接线实现，要么从 config 与示例中删除，避免"看似可配、实则无效"的旋钮。

P3 · FallEvent 缺 config_version

• 04-architecture.md 要求 FallEvent 记录 config_version，使截图/JSONL 可追溯实际阈值。
• 当前 v1/fall_state.py 的 FallEvent 无该字段。
• 建议：现在就在 dataclass 补上，避免 T-202 写 JSONL 时无法追溯。

P4 · 轨迹过期(2s) 与确认窗口(最长3s)互相打架

• PersonTracker 默认 max_age_seconds=2.0，确认窗口可配到 3.0s。
• 摔倒过程恰是遮挡、姿态最不稳、Pose 最易丢的时刻。Pose 丢失 >2s 时此人拿到新 track_id，状态机视为新人从 NORMAL 起算，之前累积的 SUSPECT 时间丢失 → 漏报。
• 建议：max_age 至少对齐/大于确认窗口，或让状态在短暂 track 断裂中存活。

P5 · 贪心最近邻跟踪，顺序依赖

• _nearest_available_track 按 pose 出现顺序逐个抢最近 track，非全局最优（非匈牙利匹配）。两人靠近/交叉时可能换 ID。
• 固定机位、稀疏大厅场景大概率够用，属已知局限。
• 建议：在文档写明限制，避免后期误判为 bug；多人密集场景再考虑升级匹配算法。

P6 · 回放默认 reconnect=True 是使用陷阱

• VideoSource 默认 reconnect=True 面向 RTSP。对有限本地录像，EOF 时会无限重试重开（从第 0 帧重放）而非报 EOF。
• 回归测试/smoke 必须显式传 reconnect=False。
• 建议：对文件路径做启发式默认，或在文档强调。

P7 · RTSP 时间戳可靠性未验证

• 状态机 1–3s 判定依赖 CAP_PROP_POS_MSEC，实况 RTSP 上该值常为 0 或乱跳。虽有 frame_index/fps 与 wall-clock 回退，但真实流上窗口计时准确性未验证。
• 建议：列为 T-203 关键风险，接入真实流后专项验证窗口计时。

建议处理顺序

1. 先补 P1 / P2 / P3（属事件引擎本身，非 GUI 活），再开 T-201。
2. P4 / P6 改动成本低，可顺手处理。
3. P5 / P7 记入已知风险，分别在多人场景与 T-203 真实流阶段处置。

独立复核补充与处理建议

复核结论：上述 P1、P2、P5、P6、P7 的事实判断成立；P3、P4 也成立，但实现方式需要避免引入新的事件一致性或身份错配问题。当前 20 项测试均通过，只能证明各模块的局部契约，不能证明完整数据流能对摔倒作出正确判定。

P0 · 缺失 Pose 尚未中断“连续证据”

• FallStateMachine.update() 只会在某个 track_id 有输入时更新时间；跟踪器和状态机都没有“本帧该人员缺失”的显式合约。
• 某人已进入 SUSPECT 后，若短暂丢失 Pose、但仍未超过 tracker 的 2 秒过期时间，下一次以同一 ID 回来时，状态机可能把缺失的时间算入确认窗口。这与“倒地证据持续”的需求不符，可能造成误确认。
• 处理：事件管线必须为已知但本帧缺失或低质量的人员输入拒绝证据，或定义并测试独立的 max_evidence_gap_seconds；不得把 tracker 的身份保留时间当作证据连续时间。

对原建议的工程化校正

• P1：规则应落在领域层，不落在 GUI。 建议保留 evidence.py 输出的几何事实，新增明确的领域规则/管线层，将每人连续的 PoseEvidence 映射为状态机 Evidence。该层必须覆盖突然倒地、持续倒地、坐下、弯腰、捡物、短暂低姿态和短暂丢 Pose 的正反例。
• P2：先定义字段语义，再接线。 suspect_window_seconds 应明确描述“突发下移到持续倒地”可接受的时间关系；cooldown_seconds 应明确描述确认后何时允许进入恢复或产生下一事件。若不能定义可验收语义，应从公开配置中移除，不能保留无效旋钮。
• P3：先统一事件契约。 04-architecture.md 要求 FallEvent 记录 config_version，而 api.md 说 T-202 的报警记录补充配置版本，二者目前不一致。应将不可变的 config_version 纳入 FallEvent 或统一定义的事件记录，并同步 V1/V2 合约；不能只在 JSONL 写入时临时拼接。
• P4：不能只把 max_age_seconds 调大。 这样可能在遮挡后把另一人错误延续为原 ID。身份保留、短时遮挡和证据连续性必须分别建模；P0 的缺失证据处理是其前提。
• P6：使用显式来源模式，而非隐式默认。 应由“录像回放”明确产生 EOF，由“实时流”明确允许重连；仅靠调用者记住 reconnect=False 或按字符串猜测路径都容易造成回归测试与生产行为漂移。
• P7：T-203 应验证并区分计时源。 录像使用容器 PTS/帧序号时间轴；实时 RTSP 使用成功收帧时的 time.monotonic() 作为事件计时依据。不能只假设 CAP_PROP_POS_MSEC 在实况流上可靠。

推荐的任务调整

不建议把上述工作混入 T-201 的 GUI 实现。应在 T-105 后插入一个独立的事件集成任务，例如：

ID	任务	依赖	验收要点
T-106	装配事件管线与固化事件契约	T-105	Pose → 跟踪 → 质量/几何证据 → 领域规则 → 按 ID 状态机可回放运行；P0 的缺失证据行为受测试保护；所有公开事件参数均生效；事件含实际配置版本；录像 EOF 不会重放。

完成 T-106 后，T-201 才接收真实管线输出的画面、骨架、ID、连接状态和 NORMAL/SUSPECT/CONFIRMED 状态。GUI 只负责显示与配置草稿，不能承载摔倒判定规则。P5 作为当前稀疏人员固定机位的已知限制记录；P7 则作为 T-203 接入真实海康流时的阻断验收项。

第二轮复核补充（全栈视角）

对上一节独立复核的结论予以确认：P0 事实成立且优先级判断正确，P3/P4/P6 是对首轮建议的有效纠偏。以下两点为在此基础上的工程细化，建议一并纳入 T-106。

P0 的修法首选状态机内建守卫，而非依赖调用者注入拒绝证据

• 上一节给出两个方向：① 管线为“本帧缺失/低质量”的已知人员喂拒绝证据；② 定义并测试 max_evidence_gap_seconds。
• 方向 ① 要求编排层每帧枚举所有存活 track（不仅是本帧检测到的），漏掉任何一个就退化为误确认；正确性依赖调用者每次都记得注入，防呆性差。
• 方向 ② 是调用者无关的内建守卫：状态机记录 last_fall_candidate_at，当 now - last_fall_candidate_at 超过 max_evidence_gap_seconds 时，即使本次是 fall candidate 也必须重置 SUSPECT 计时、不得把间隔折算进确认窗口。
• 建议：以 ② 为主、① 为辅，并在 T-106 验收中固化“SUSPECT 中间出现超过 gap 阈值的证据空档 → 不确认”的正反例测试。

乱序时间戳应降级处理，不应直接抛异常

• 当前 FallStateMachine.update() 对 now < last_updated_at 直接 raise ValueError("timestamps must be monotonic per track")。
• 一旦 P7 落实后计时源切换，或某 track 以重置时钟复现，这个硬 raise 会让整条实时管线崩溃，而不是容错降级——对一个需要长时间无人值守运行的告警 demo 是不可接受的失败模式。
• 建议：把乱序帧改为丢弃该帧并记录状态（不推进时间、不产生事件、可选计一次告警计数），而非中断。该改动与 P7 的显式计时源在 T-106 一并处理。