# 执行计划 — 修复 metadata 字段错误

> **文档类型**: 执行计划文档  
> **创建日期**: 2026-08-03  
> **作者**: Claude Code  
> **优先级**: P0（阻塞）  
> **版本**: v5.60  
> **状态**: ✅ 全部完成  

---

## 一、执行概述

### 1.1 目标

修复创建模拟设备时的多个关联错误，恢复设备创建功能。

### 1.2 范围

- 修改 `backend/app/services/device_sim_service.py` 字段名
- 修改 `backend/app/schemas/device_sim.py` 添加验证器和缺失字段
- 数据库迁移添加 `topic_params` 列
- 更新 PRD 文档版本至 v5.60

### 1.3 实际工时

30 分钟

---

## 二、执行步骤

### Step 1: 修复 service 层字段名（✅ 已完成）

**文件**: `backend/app/services/device_sim_service.py:389`

```python
# 修改前
extra_attrs=data.metadata or {},

# 修改后
extra_attrs=data.extra_attrs or {},
```

---

### Step 2: 添加 field_validator（✅ 已完成）

**文件**: `backend/app/schemas/device_sim.py`

1. 添加导入：`field_validator`
2. 在 `SimulatorResponse` 中添加 `ignore_sqlalchemy_metadata` 验证器
3. 添加 `metadata` 字段声明（`exclude=True`）

---

### Step 3: 恢复缺失字段（✅ 已完成）

**文件**: `backend/app/schemas/device_sim.py`

1. `SimulatorBase` 添加 `topic_params` 字段
2. `SimulatorUpdate` 添加 `topic_params` 字段
3. 添加 `TopicTemplateResponse` 和 `TopicTemplateListResponse` 类

---

### Step 4: 数据库迁移（✅ 已完成）

```sql
ALTER TABLE device_simulators ADD COLUMN topic_params TEXT
```

---

### Step 5: 重启服务并验证（✅ 已完成）

- 后端服务已重启
- 创建门口屏设备：201 ✓
- 创建无纸化设备：201 ✓
- 创建中控设备：201 ✓
- 主题模板 API：200 ✓

---

### Step 6: 更新版本标记（✅ 已完成）

PRD 文档已更新为 v5.60。

---

## 三、修改文件清单

| 文件 | 变更类型 | 说明 |
|------|----------|------|
| `backend/app/services/device_sim_service.py` | 修改 | 第 389 行：字段名修正 |
| `backend/app/schemas/device_sim.py` | 修改 | 添加验证器、缺失字段、主题模板 Schema |
| `backend/data/test_platform.db` | 修改 | 添加 `topic_params` 列 |
| `Docs/PRD/需求文档/设备模拟/_PRD_需求文档_设备模拟模块.md` | 修改 | 更新版本至 v5.60 |
| `Docs/PRD/需求文档/设备模拟/_问题处理_创建模拟设备失败_metadata字段错误.md` | 新建 | 问题处理文档 |
| `Docs/PRD/需求文档/设备模拟/_执行计划_修复metadata字段错误_v5.60.md` | 新建 | 本文档 |

---

## 四、验收标准

- [x] service 层字段名修正
- [x] Schema 添加 field_validator
- [x] Schema 恢复缺失字段
- [x] 数据库迁移完成
- [x] 后端服务重启
- [x] 创建设备 API 返回 201
- [x] 不同设备类型均可创建
- [x] 主题参数配置功能正常
- [x] 无其他副作用

---

## 五、相关文档

- 问题处理文档: `_问题处理_创建模拟设备失败_metadata字段错误.md`
- PRD 文档: `_PRD_需求文档_设备模拟模块.md`
- 交接文档: `HANDOFF_设备模拟_主题配置改造.md`

---

*本文档为修复 metadata 字段错误的执行计划，版本 v5.60，全部完成。*
