# 配置模板化与渲染设计

## 目标

以模板为核心管理 RK3588 设备配置，避免为了设备差异、测试参数或临时调参复制完整配置文件。

第一阶段采用离线渲染方式：模板、设备 profile、测试 overlay 合成为一个 root config，再由现有 `media-server -c` 加载。这样不改变运行入口，也能复用已有 `templates / instances` 展开逻辑。

## 目录约定

```text
configs/
  templates/       # 长期维护的 pipeline 模板
  profiles/        # 设备、现场、摄像头差异参数
  overlays/        # 测试或运行场景覆盖
  generated/       # 渲染产物，不手工维护
```

## 当前标准模板

`configs/templates/workshop_face_shoe_alarm.json` 从 `configs/full_pipeline_1080p_test_alarm.json` 提炼而来，包含当前最完整链路：

- RTSP 输入
- RGB 预处理
- SCRFD 滑窗人脸检测
- MobileFaceNet 人脸识别
- YOLOv8n 人体检测
- 人体跟踪
- 动态 ROI 鞋检测
- 鞋人关联和颜色判断
- OSD
- HLS/RTSP 发布
- 告警、截图、录像、MinIO 上传、External API 上传

模板中只保留 DAG 和插件结构，设备差异通过占位符表达，例如 `${rtsp_url}`、`${face_gallery_path}`、`${minio_endpoint}`、`${external_get_token_url}`。

## Profile

`configs/profiles/local_3588_test.json` 描述具体设备或测试盒子的参数。多台设备或多路相机应新增 profile 或在同一 profile 中新增 instances，而不是复制完整 pipeline。

## Overlay

Overlay 用于测试或运行场景覆盖：

- `configs/overlays/face_debug.json`：打开人脸识别和陌生人候选诊断日志。
- `configs/overlays/shoe_debug.json`：打开鞋子关联和颜色判断 debug。
- `configs/overlays/production_quiet.json`：关闭高频 debug 日志，适合正式运行。

Overlay 支持 `instance_overrides."*"`，可以一次覆盖所有 instance；也可以使用具体 instance 名只覆盖单路相机。

## 渲染命令

```bash
python tools/render_config.py \
  --template configs/templates/workshop_face_shoe_alarm.json \
  --profile configs/profiles/local_3588_test.json \
  --overlay configs/overlays/face_debug.json \
  --out configs/generated/local_3588_face_debug.json
```

设备运行：

```bash
./build/media-server -c configs/generated/local_3588_face_debug.json
```

`configs/generated/*.json` 是生成物，不纳入 git，不应手工修改。

## 运行时展开

渲染工具输出的是包含 `templates / instances` 的 root config。`media-server` 加载时继续使用现有 `ExpandRootConfig` 展开成 `graphs`。

本次补充了 template `executor` 保留逻辑，确保从完整配置提炼模板时不会丢失 graph executor 参数。