x11_template_vue2/SYSTEM_GUIDE.md

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

系统特性

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：

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：复制模板文件

mkdir templates/new_model
cp daping项目模板文件 templates/new_model/

步骤 3：前端自动识别

系统自动读取配置，无需修改前端代码。

6. 数据结构

{
  "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. 部署命令

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

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

或一键启动：

.\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 包含所需程序