# 问题分析：启动门口屏模拟设备失败 — BaseSimulator 参数不匹配

> **分析日期**: 2026-08-20
> **相关模块**: 设备模拟（门口屏）
> **问题现象**: `启动模拟设备失败: BaseSimulator.__init__() takes from 5 to 8 positional arguments but 9 were given`

---

## 一、问题描述

启动门口屏模拟设备时，后端报错：

```
BaseSimulator.__init__() takes from 5 to 8 positional arguments but 9 were given
```

无纸化设备（paperless）启动不受影响，中控（central）和集控客户端（client）未验证。

---

## 二、问题复现

1. 在设备模拟页面 → 门口屏 → 选择环境配置 → 点击启动单台或多台门口屏设备
2. 后端 API 返回 500 错误，错误信息为上述参数不匹配异常
3. 无纸化设备在同一环境配置下启动正常

---

## 三、根因分析

### 3.1 部署遗漏

`deploy_door_http_final.py` 部署脚本（由会话 G 创建，commit `695460eb`）仅上传了 2 个后端文件：

| 文件 | 是否部署 |
|------|----------|
| `backend/app/simulators/door_token_client.py` | ✅ 已部署 |
| `backend/app/simulators/door_simulator.py` | ✅ 已部署 |
| `backend/app/simulators/base_simulator.py` | ❌ **遗漏，未部署** |

### 3.2 参数不匹配链条

完整的历史链路：

```
commit ff749e33 (Token获取，未部署)
  ├─ base_simulator.py: __init__ 增加 token_api_host 参数
  ├─ door_simulator.py:  super().__init__() 传 token_api_host
  └─ __init__.py:        create_simulator() 透传 token_api_host

commit 003ee7c9 (MQTT修复 + 消息列表，未部署)
  ├─ paperless_simulator.py:  __init__ 增加 token_api_host 参数
  ├─ central_simulator.py:   __init__ 增加 token_api_host 参数
  └─ client_simulator.py:    __init__ 增加 token_api_host 参数

commit 695460eb (人脸页面 + 全局配置，已部署)
  ├─ door_simulator.py:  ✅ 部署到服务器（含 token_api_host 参数传递）
  └─ door_token_client.py:  ✅ 部署到服务器
```

**服务器现状**：

| 文件 | 服务器版本 | 有无 token_api_host |
|------|-----------|-------------------|
| `base_simulator.py` | 旧版（未部署） | ❌ 无 |
| `door_simulator.py` | 新版（已部署） | ✅ 有，`super().__init__()` 传 8 个参数 |
| `paperless_simulator.py` | 旧版（未部署） | ❌ 无，`super().__init__()` 传 7 个参数 |
| `central_simulator.py` | 旧版（未部署） | ❌ 无，`super().__init__()` 传 7 个参数 |
| `client_simulator.py` | 旧版（未部署） | ❌ 无，`super().__init__()` 传 7 个参数 |
| `__init__.py` | 旧版？ | 待确认 |

### 3.3 为什么无纸化不受影响

旧版 `paperless_simulator.py` 的 `super().__init__()` 调用为：

```python
# 旧版（服务器上正在运行的版本）
super().__init__(device_id, env_config_id, "paperless", mqtt_manager,
                 report_config, topics, topic_params)
# 传 7 个位置参数，匹配旧版 BaseSimulator 的 7 个参数（不含 self）
```

新版 `door_simulator.py` 的 `super().__init__()` 调用为：

```python
# 新版（已部署到服务器）
super().__init__(device_id, env_config_id, "door", mqtt_manager,
                 report_config, topics, topic_params, token_api_host)
# 传 8 个位置参数，但旧版 BaseSimulator 只有 7 个参数（不含 self）
```

因此只有门口屏报错，其他设备类型不受影响。

---

## 四、影响范围

| 设备类型 | 是否受影响 | 原因 |
|----------|-----------|------|
| 门口屏（door） | ✅ **受影响** | `door_simulator.py` 已更新但 `base_simulator.py` 未同步 |
| 无纸化（paperless） | ❌ 不受影响 | 服务器上仍是旧版 `paperless_simulator.py` |
| 中控（central） | ❌ 不受影响 | 同上 |
| 集控客户端（client） | ❌ 不受影响 | 同上 |

---

## 五、修复方案

### 方案 A（推荐）：部署全部缺失文件

上传所有缺少 `token_api_host` 参数的后端文件到服务器：

| 文件 | 原因 |
|------|------|
| `backend/app/simulators/base_simulator.py` | **核心修复** — 必须部署 |
| `backend/app/simulators/__init__.py` | `create_simulator()` 透传 `token_api_host` |
| `backend/app/simulators/paperless_simulator.py` | 统一 `token_api_host` 参数签名 |
| `backend/app/simulators/central_simulator.py` | 同上 |
| `backend/app/simulators/client_simulator.py` | 同上 |

### 方案 B（快速修复，不推荐）：仅部署 `base_simulator.py`

只部署 `base_simulator.py` 一个文件即可修复门口屏错误，但其他 3 个模拟器的 `__init__` 签名不完整，后续如果其他设备启动流程也需要 `token_api_host` 时仍会出问题。

---

## 六、预防措施

1. **部署脚本应包含完整依赖分析**：修改 `deploy_door_http_final.py` 时，应检查修改文件是否依赖其他未修改但需同步部署的文件
2. **部署前增加集成测试**：部署后应验证所有设备类型（door/paperless/central/client）的启动均正常
3. **统一部署脚本命名和职责**：当前有多个部署脚本（`deploy_to_560_stats.py`、`deploy_frontend_only.py`、`deploy_door_http_final.py`），职责分散，建议统一为一个通用部署脚本

---

*本文档由 Claude Code 生成，2026-08-20*