silver_pose/docs/05-coding-rules.md

编码规则

每次动代码前先读完本文件，并以 需求、技术栈 和 架构设计 为事实约束。

黄金法则

1. 不臆造摄像头、模型、数据集、事件字段或指标；不确定就检查或询问。
2. 一轮只完成一个任务；不顺手提前实现 V2、云端、多摄像头或模型训练。
3. 推理、跟踪、事件判断、UI 和报警副作用必须按架构分离。
4. 每次实现先写失败测试，再做最小实现，再运行通过测试。
5. 完成以真实验证证据为准，并记录到 ../progress.md。

模型与视频规则

• best.pt 只代表 Pose 模型；禁止把 Pose 置信度、关键点可见率或单帧规则分数命名为“摔倒概率”。
• 关键点有效性不得使用 confidence > 0 作为唯一标准；阈值、可见性要求和退化行为必须由配置与测试覆盖。
• 几何计算保留浮点精度；所有反余弦输入夹紧到 [-1, 1]；不因零向量崩溃。
• 事件确认使用单调时间和秒，不能依赖视频固定 FPS。
• 同一 track_id 的报警必须幂等；同一事件不得逐帧重复弹窗、播放声音或覆盖截图。
• RTSP 断流、空帧、无人员、低质量姿态是明确状态，绝不当作摔倒。

配置与隐私规则

• 配置中所有影响判断的阈值必须真正传入事件逻辑；UI 显示的值必须就是生效值。
• 真实 RTSP URL、用户名、密码、摄像头序列号和客户视频不得入库、不得输出到日志。
• 只提交 config.example.json；config.local.json、事件截图、ONNX/模型导出物和客户录像须由 .gitignore 排除。
• 保存截图前只保留演示所需的时间、ID、状态和画面，不在文件名中写个人身份信息。

UI 视觉规则

• V1 默认使用浅色 Windows 风格：浅灰蓝页面背景、白色卡片和语义化边框；不得沿用深色控制台作为默认主题。
• 红色只表示 CONFIRMED 摔倒事件及其关联弹窗和事件证据。普通操作、保存成功、设置校验、截图错误和连接异常不得使用红色。
• UI 颜色必须通过集中 QSS 主题令牌定义，并同时提供文字、图标或形状语义；不得以颜色作为唯一状态信息。

V1 / V2 迁移规则

• V2 开始前，V1 必须有通过的正反例录像回归与现场 RTSP 验收记录。
• Go 不直接加载 .pt；导出 ONNX 后必须锁定模型哈希、输入尺寸、预处理、NMS 和关键点格式。
• V2 只有在同一回归录像集上满足约定的事件数量、确认时间和无报警案例后才能标为可演示。
• 不以“Go 更稳定”替代压力、断流和回归证据。

完成前检查

• 任务验收命令通过。
• 正反例或单元测试覆盖当前改动。
• 文档、配置和事件字段与代码一致。
• 没有提交凭证、客户视频、模型大文件或运行工件。
• 06-tasks.md、current-state.md 和 progress.md 已同步。
• 已过 clean-state-checklist.md。