文档: 开发历程改为表格版

docs/开发历程.md

@@ -2,89 +2,58 @@
 
 > 依据 opencode 会话记录（12 个会话、3124 条消息、2026-08-11 → 2026-10-22）、
 > 原始工作目录 `/root/hd-ws`（rtsp / rtsp588 / rtsp568）以及 deploy 目录下的
-> 18 个部署包整理。
+> 22 个部署包整理。
 
-## 1. 项目背景与目录沿革
+## 1. 目录沿革
 
 | 目录 | 说明 | 时间 |
 |---|---|---|
 | `/root/hd-ws/rtsp` | 最早版本（RK3588 平台原版拷贝） | 2026-08 前 |
 | `/root/hd-ws/rtsp588` | 中间快照（RK3588 平台） | 2026-08 前 |
-| `/root/hd-ws/rtsp568` | **转 RK3568 后的正式版本**（8-11 定为正式版） | 2026-08-11 |
-| `/root/layoutx` | 2026-09-04 迁移并修复后的现行开发目录 | 2026-09-04 起 |
-
-项目：**多路 RTSP 视频流多画面合成显示系统**，运行于 Orange Pi / Rockchip SoC
-（RK3568），配合西门子 PLC 点位信号自动切换布局（车间随动监控）。
+| `/root/hd-ws/rtsp568` | **转 RK3568 后的正式版本**（08-11 定为正式版） | 2026-08-11 |
+| `/root/layoutx` | 09-04 迁移后的现行开发目录（git 仓库） | 2026-09-04 起 |
 
 ## 2. 开发时间线
 
-### 阶段一 2026-08-11 ~ 08-14（hd-ws/rtsp568）：RK3588 转 RK3568 与功能重构
-- RK3588 → RK3568 平台迁移：编译、依赖、字体缺失检查与修复
-- 移除推理（YOLO/检测器）相关无用功能与资源占用
-- 单通道 layout 自动使用主码流逻辑（原配置全为子码流）
-- 摄像头离线处理：不再卡死最后一帧 + 自动重连
-- PLC 离线右下角红字告警（出现"画面闪"问题后暂撤）
-- run_local 本地测试安装脚本；进程残余/CPU/闪/tearing 排查与修复
-- 布局系统大改造：多行自适应布局（第一行 N 个、第二行 M 个、按比例占高）、
-  大/小画面组合（layout0-4：1~3 个大画面 + 其余小画面）、字符占位配置、
-  总高度撑满、宽高比不变形
-- 网格线叠加
-- 海康 ISAPI 批量配置摄像头主/子码流（channels_isapi.conf）
-- 画面撕裂（tearing）修复
-
-### 阶段二 2026-08-25：管线优化调研（只读分析）
-- 视频管线核心模块（decoder/composer/display）与应用层审计，输出优化点清单
-
-### 阶段三 2026-09-04 ~ 09-05（layoutx 新目录）：部署化准备
-- 目录迁移 `/root/hd-ws/rtsp568` → `/root/layoutx`，build.sh 修复、花屏修复
-- plc_server.sh 改为前台运行，Ctrl+C 可完全退出全部服务
-- 新增 `deploy/` 与 `pack.sh` 一键生成部署包（首次打包 20260904）
-- PLC DB 块地址解析与 plc_sim 同步修正
-- 自动重启设备功能（日/周周期 + 重启时间，channels.conf 可配）
-- 一键部署到新主机脚本（默认 192.168.1.243 / root / 123456）+ README 更新
-
-### 阶段四 2026-09-05 ~ 10-13：部署实战与网页配置
-- 离线依赖问题暴露（现场板子不便联网），依赖安装方案调整
-- 部署后标题 logo 缺失修复、PLC 未监听 0.0.0.0 修复
-- 上下分割布局落地：第一行 30%（5 路小画面）/第二行 70%（1~3 路，随 PLC 切换，
-  按宽高比居中放置）
-- PLC 规则语义重写（最具体者胜）：点位组的"任一触发/全部触发"规则、
-  无匹配时回退默认布局、恢复后回到默认
-- web 配置页面（端口 8080，密码 3730）：PLC 地址、摄像头地址、layout、
-  tsap 参数可视化修改；中文页面；保存格式（等号空格/多余键）修复
-- 断线重连机制完善（摄像头掉线/PLC 离线再上线）
-- 现场根目录写满事件（kern.log/syslog 各 12G）：日志清理与治理结论
-- 现场闪屏根治：RGA "MMU unsupported memory larger than 4G" → 输出缓冲改用
-  `system-uncached-dma32` 优先分配（其次 cma，再普通内存）
-- 无显示器开机只显示桌面修复：display_init 参与等待显示器重试，
-  HDMI 分配器/录像机切换场景排查，`display: AtomicCommit EINVAL` 修复
-- `--hdmi` 参数调研后取消，start.sh 还原，不改现场 service
-- 紫色画面问题：HDMI RGB 输出 `color_format` 代码硬编码 `display_set_color_format(1)`
-
-### 阶段五 2026-10-13 ~ 10-22：生产板部署与稳定性
-- **部署到生产板 216**：标题栏字体问题修复、TSAP（西门子 1200）、
-  PLC 连接状态角标（右上角绿/红）、网页可配 tsap
-- **216 / 217 双板部署**：完全离线安装（install.sh 依赖自检 ldd+gst-inspect）
-- **布局防抖**：`plc_debounce_ms`（默认 300ms，连续稳定才切换），
-  修复"点位瞬间触发闪切"；网页可配防抖参数
-- **网页添加多网段 IP 改走 NetworkManager**（nmcli con mod + reapply，
-  持久化到 /etc/NetworkManager/system-connections/），
-  替换 ifupdown 旧路径（/etc/network/interfaces）
-- **systemctl stop 卡 90 秒修复**：display_init 等显示器循环增加 `g_running`
-  检查，SIGTERM 及时退出（实测 90s → 363ms）
-- **安装包内置静态 IP 步骤**：给 eth0 追加 `192.168.100.245/24`（保留 DHCP）
-- **画面左下角 IP 角标**：显示 eth0 全部 IPv4（每秒刷新），
-  忘记 IP 时直接从画面读出
-- **拔插显示器死机修复（核心修复）**：根因=启动时按当时显示器模式分配的
-  NV12 缓冲区（如 1280x720）在拔插后显示器改为首选模式（1920x1080），
-  `drmModeAddFB2(NV12)` 用模式尺寸+缓冲区 stride → EINVAL 死循环；
-  修复：重建时优先选与缓冲区匹配的模式 + plane SRC/CRTC 几何分离（支持缩放）
-- 换新显示器仍需重新上电才出原生分辨率（缓冲区只建一次，用户决定保持现状）
+| 日期 | 阶段 | 开发内容 |
+|---|---|---|
+| 08-11 ~ 08-12 | ① RK3588→RK3568 迁移 | 编译/依赖/字体缺失修复；移除推理（YOLO）功能与资源占用 |
+| 08-11 | ① | 单通道 layout 自动使用主码流；测试跳转 10s→5s；摄像头离线不卡帧+自动重连；画幅切换时 nosignal 显示 |
+| 08-11 | ① | 软件标题命名建议；本目录定为正式版本 |
+| 08-12 | ① | PLC 离线右下角红字告警（出现闪屏，后续撤回）；run_local 本地测试安装脚本 |
+| 08-12 | ① | importbuffer_fd 报错/画面闪排查；进程残余、CPU 高占用修复；plc 改用远程服务 |
+| 08-12 ~ 08-14 | ① layout 重构 | 多行自适应布局（首行 N 个/各行按比例占高、撑满）；大/小画面组合设计（layout0-4：1~3 个大画面+其余小画面）；字符占位配置；宽高比不变形 |
+| 08-13 | ① | 网格线叠加；海康 ISAPI 批量配置主/子码流（channels_isapi.conf）；调试进程清理 |
+| 08-13 ~ 08-14 | ① | importbuffer_fd 修复 |
+| 08-25 | ② 只读调研 | 视频管线核心模块与应用层审计，输出优化点清单 |
+| 09-04 | ③ 目录迁移 | `/root/hd-ws/rtsp568`→`/root/layoutx`；build.sh 修复；花屏/importbuffer 修复 |
+| 09-04 | ③ 部署化 | plc_server.sh 前台运行（Ctrl+C 全退出）；deploy/ 目录 + pack.sh 打包（首批 20260904） |
+| 09-04 | ③ PLC | DB 块地址解析修正；plc_sim 同步更新 |
+| 09-04 ~ 09-05 | ③ | 自动重启设备（日/周+时间，conf 可配）；一键部署新主机脚本（192.168.1.243/root/123456）；README 更新 |
+| 09-05 | ④ 部署实战 | 离线依赖问题暴露调整；部署后标题/字体修复；PLC 未监听 0.0.0.0 修复 |
+| 09-14 | ④ PLC | PLC 连接日志排查；TSAP/Rack/Slot 解答；DB1000 读点测试；bool 位解析定位 |
+| 09-15 | ④ 网页配置 | web 页面上线（8080/密码 3730）：改 PLC/摄像头地址、layout、tsap；中文页面；保存格式修复 |
+| 09-15 ~ 09-16 | ④ 布局 | 上下分割布局（上 30% 五路小画面+下 70% 按点位 1~3 路，宽高比居中）；plc_rules 语义重写（任一触发/全部触发、无匹配回退默认、恢复回默认） |
+| 09-19 | ④ 稳定性 | 黑框+fps=0 修复；断线重连机制（摄像头/PLC 重上线）；网页中文乱码修复；批量拷贝部署脚本化 |
+| 09-21 | ④ 现场闪屏 | 根因 RGA “4G MMU 不支持” → 输出缓冲优先走 dma32 heap（其次 cma、普通内存）；根目录写满（kern/syslog 各 12G）治理 |
+| 09-21 | ④ 无显示器开机 | 先启动服务后接显示器只显示桌面 → display_init 等显示器重试；HDMI 分配器/录像机切换场景排查（与分配器无关）；systemd 自启动适配 |
+| 09-21 | ④ PLC 规则修正 | 按用户改动的 [plc_rules] 语义改代码；触发后恢复回默认布局修复 |
+| 09-21 | ④ 网页 IP | 网页查看/修改设备 IP（多网段添加）；网页保存配置；定时重启功能与每天凌晨重启确认 |
+| 10-13 | ⑤ 拔插稳定性 | 频繁拔插 AtomicCommit EINVAL/第二次回桌面修复；紫色画面排查 |
+| 10-13 | ⑤ color_format | HDMI RGB 值 `display_set_color_format(1)` 代码硬编码；diag.sh 诊断脚本 |
+| 10-13 | ⑤ 生产部署 | 216 生产板部署：标题栏字体修复、TSAP、PLC 连接状态角标、网页可配 tsap |
+| 10-14 | ⑤ 离线部署 | install.sh 依赖自检（ldd+gst-inspect），完全离线安装，无需联网 |
+| 10-14 | ⑤ 防抖 | plc_debounce_ms（300ms 连续稳定才切换，防点位瞬间触发闪切）；网页可配 |
+| 10-14 | ⑤ 网络管理 | 网页添加 IP 走 NetworkManager（nmcli con mod+reapply 持久化）；两块板各加 192.168.100.x |
+| 10-14 | ⑤ service 秒停 | display_init 等显示器循环加入 g_running 检查，stop 卡 90s→363ms |
+| 10-14 | ⑤ 静态 IP | install.sh 内置给 eth0 追加 192.168.100.245/24（保留 DHCP） |
+| 10-14 | ⑤ 画面 IP 角标 | 左下角显示 eth0 全部 IPv4（每秒刷新）；防忘 IP |
+| 10-20 | ⑤ 拔插根治 | NV12 缓冲区 vs 显示模式 mismatch → einval 死循环；修复=重建优先选匹配模式+SRC/CRTC 几何分离（支持缩放） |
+| 10-20 | ⑤ 定版 | 换分辨率屏需重新上电（用户决定保持不动）；打包 20261020_010600 |
+| 10-22 | ⑥ 版本管理 | 汇总开发历程；git 仓库初始化并打 v1.0-prod 标签 |
 
 ## 3. 部署包（平台版本）沿革
 
-deploy/ 下共 18 个 tar.gz（20260904 → 20261020），关键版本：
-
 | 部署包时间戳 | 二进制 md5 | 主要变化 |
 |---|---|---|
 | 20260904_092418 / 093406 | - | 首批打包（部署化试行） |
@@ -101,15 +70,20 @@ deploy/ 下共 18 个 tar.gz（20260904 → 20261020），关键版本：
 
 ## 4. 当前版本状态（2026-10-22）
 
-- 开发机（232）编译产物：`63252ff9afca147bd89edd1c3907280d`
-- 生产板 216：`63252ff9…`（最新，含拔插修复）
-- 生产板 217：`d2b642cc…`（缺拔插修复，离线待更新）
-- 现场约定：换不同分辨率显示器后**重新上电**即可出原生分辨率
+| 项 | 状态 |
+|---|---|
+| 开发机（232）编译产物 | `63252ff9afca147bd89edd1c3907280d` |
+| 生产板 216 | `63252ff9…`（最新，含拔插修复） |
+| 生产板 217 | `d2b642cc…`（缺拔插修复，离线待更新） |
+| 现场约定 | 换不同分辨率显示器后**重新上电** |
 
 ## 5. git 版本管理
 
-- 仓库位置：`/root/layoutx`（自 2026-10-22 起）
-- 忽略项（.gitignore）：build/、build_asan/、deploy/*.tar.gz、models/（143M 权重文件，
-  教程见 convert_yolov8_rknn.py；推理已移除）、plc_sim/capture_fb 二进制、运行日志
-- ⚠️ channels.conf* 内含摄像头验证账号（URL 中）与网页密码，仓库仅限内网/离线保存
-- 原始历史（/root/hd-ws 三个目录）保持原样不纳入 git，如需可作为分支导入
+| 项 | 说明 |
+|---|---|
+| 仓库位置 | `/root/layoutx`（自 2026-10-22 起） |
+| 基线提交 | `a7697d4`（main 分支） |
+| 标签 | `v1.0-prod`（对应部署包 20261020_010600） |
+| 忽略项 | build/、build_asan/、deploy/*.tar.gz、models/（143M 权重，推理已移除）、二进制、运行日志 |
+| ⚠️ 注意 | channels.conf* 内含摄像头凭证与网页密码，仓库仅限内网/离线保存 |
+| 原始历史 | `/root/hd-ws` 三个目录保持原样，如需可导入为分支 |