# 多机型语音播报模板管理系统

## 系统特性

### 1. 全面兼容 daping_rec_online_api

- ✅ **机型配置同步**：完全复刻 daping 项目的机型定义（type_id、zone_id）
- ✅ **模板映射一致**：Redis key 格式与 daping 项目 100% 匹配
- ✅ **程序名称映射**：内置 program_name_map，支持预览时自定义
- ✅ **模板复用机制**：支持一个模板被多个 key 引用（write_multi_key）

### 2. 支持的机型（8种）

| 机型标识 | 机型名称 | 设备类型 | 区域数 | 模板类型数 |
|---------|---------|---------|-------|----------|
| x11 | X11 洗衣机 | wash | 2 | 8 |
| x11_dry | X11 干衣机 | dry | 1 | 6 |
| hplus | Hplus | wash+dry | 2 | 3 |
| ultra | Ultra | wash | 6 | 9 |
| f2_multi | F2 Multi | wash | 1 | 9 |
| seeker | Seeker | wash+dry | 4 | 6 |
| seeker_dry | Seeker 干衣机 | dry | 1 | 6 |
| x11_ultra | X11 Ultra | dry | 3 | 6 |

### 3. 模板类型（10种）

- `common` - 通用模板
- `time_popular` - 人气推荐
- `time_custom` - 用户定制
- `time_season` - 季节推荐
- `time_season_storage` - 季节收纳（多卡）
- `time_season_in` - 季节上新（多卡）
- `time_care` - 关怀提醒
- `time_environmental` - 环保错峰
- `time_weather` - 天气建议
- `time_health` - 健康清洁
- `time_health_2` - 杀菌模板（Ultra）

### 4. 核心功能

#### 4.1 模板管理
- 创建/编辑/删除模板
- 按机型/设备类型/模板类型筛选
- 模板分组展示（洗涤/干衣 × 模板类型）

#### 4.2 模板复用
- 选择复用已有模板内容
- 自动维护 reuse_targets 关系
- 复用模板显示🔄标记
- 源模板显示📦标记和被复用数量

#### 4.3 实时预览
- 内置 program_name_map 编辑器
- 支持所有 Jinja2 语法
- 变量填充和参数预览
- 即时渲染结果展示

#### 4.4 导出对接
- 模板可直接复制到 daping 项目
- Redis key 格式自动生成
- 支持 write_multi_key 批量写入

### 5. 扩展新机型

只需 3 步：

#### 步骤 1：添加机型配置
编辑 `backend/app/config/machine_config.py`：

```python
MACHINE_MODELS["new_model"] = MachineModel(
    model_id="new_model",
    model_name="新机型",
    type_id="201c51890c31c308...",  # Redis type_id
    zones=[
        ZoneConfig(zone_id="1", zone_name="洗衣机", device_type="wash"),
    ],
    template_mappings=[
        TemplateMapping(
            template_type="common",
            redis_key_pattern="broadcast-template-jinja:single_card:wash:common",
            description="通用模板"
        ),
        # 添加其他模板类型...
    ]
)
```

#### 步骤 2：复制模板文件
```bash
mkdir templates/new_model
cp daping项目模板文件 templates/new_model/
```

#### 步骤 3：前端自动识别
系统自动读取配置，无需修改前端代码。

### 6. 数据结构

```json
{
  "id": "template_id",
  "name": "X11洗衣机-通用模板",
  "category": "单卡洗涤",
  "device_type": "wash",
  "machine_model": "x11",
  "template_type": "common",
  "reusable_from": "",  // 复用来源（空=独立模板）
  "reuse_targets": [],  // 被哪些模板复用
  "template_body": "{% macro ... %}",
  "input_variables": [...],
  "description": "...",
  "created_at": "2026-09-08T00:00:00Z",
  "updated_at": "2026-09-08T00:00:00Z"
}
```

### 7. API 接口

#### 模板管理
- `GET /api/templates?machine_model=x11&device_type=wash&template_type=common`
- `GET /api/templates/{id}`
- `POST /api/templates`
- `PUT /api/templates/{id}`
- `DELETE /api/templates/{id}`

#### 筛选接口
- `GET /api/templates/machine-models` - 所有机型
- `GET /api/templates/device-types?machine_model=x11` - 设备类型
- `GET /api/templates/template-types?machine_model=x11&device_type=wash` - 模板类型

#### 渲染接口
- `POST /api/templates/preview` - 预览（含 program_name_map）
- `POST /api/templates/render` - 渲染已保存模板

### 8. 部署命令

```bash
# 后端
conda activate rec
cd backend
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 前端
cd frontend
npm install  # 首次
npm run dev
```

或一键启动：
```powershell
.\start.ps1
```

### 9. 文件结构

```
x11_template_vue/
├── backend/
│   ├── app/
│   │   ├── config/
│   │   │   └── machine_config.py  # 机型配置（核心）
│   │   ├── services/
│   │   │   ├── template_store.py  # 模板存储（支持复用）
│   │   │   └── renderer.py        # 渲染器（含 program_name_map）
│   │   ├── schemas.py             # 数据模型
│   │   └── main.py                # API 路由
│   └── data/
│       └── templates.json         # 模板数据
├── frontend/
│   └── src/
│       ├── App.vue                # 主界面
│       └── services/
│           └── api.js             # API 调用
├── templates/                     # 原始模板文件（按机型分）
│   ├── x11/
│   ├── hplus/
│   ├── ultra/
│   ├── f2_multi/
│   ├── seeker/
│   ├── x11Ultra/
│   └── seekerR2/
└── start.ps1                      # 一键启动
```

### 10. 与 daping 项目对接流程

1. 在本系统创建/编辑模板
2. 点击"保存修改"
3. 复制模板正文（template_body）
4. 在 daping 项目的 `write_jinja_*.py` 中粘贴
5. 运行 Python 脚本写入 Redis

或直接导出 JSON，用脚本批量导入 Redis。

### 11. 注意事项

- ✅ 不修改 daping_rec_online_api 任何代码
- ✅ 模板格式 100% 兼容
- ✅ program_name_map 可随时编辑
- ✅ 支持模板复用减少重复维护
- ⚠️ 新增机型需更新 machine_config.py
- ⚠️ 预览时需确保 program_name_map 包含所需程序