<!-- markdown -->
# 训练场景编辑器需求规格说明书
**Training Scenario Editor - Requirement Specification**
`Version 1.0 | 2025-07-10`
---
## 一、模块定位（Positioning）
- **核心目标**：为教练提供零代码的虚拟训练场景搭建工具
- **系统关系**：VOITS后台管理系统的独立子模块（输出.scene文件供VR主引擎加载）
- **技术约束**：
- 开发语言：**Python 3.10+**
- 图形界面：**PyQt5**
- 3D交互：**PyOpenGL + Pygame**
- 数据格式：**glTF 2.0模型 + JSON配置**
---
## 二、功能需求（Functional Requirements）
### **FR1：3D场景搭建**
| 子功能 | 详细要求 | 技术实现方案 |
|-----------------------|--------------------------------------------------------------------------|----------------------------------|
| 1.1 模型库加载 | 从本地目录加载glTF模型缩略图列表（自动生成200x200px预览图） | `pygltflib`库解析模型元数据 |
| 1.2 拖拽式装配 | 拖放模型到画布→自动吸附坐标网格→生成部件树（父子装配关系） | PyQt5 `QGraphicsScene`拖拽事件 |
| 1.3 基础位姿调整 | 选中模型后激活平移/旋转手柄（X/Y/Z轴） | PyOpenGL `glTranslatef/glRotatef`|
### **FR2：拆装流程设计**
| 子功能 | 详细要求 | 技术实现方案 |
|-----------------------|--------------------------------------------------------------------------|----------------------------------|
| 2.1 流程图编辑器 | 节点式编辑：<br>- 添加步骤节点（拆卸/装配/检测）<br>- 箭头连接定义顺序流 | 定制`PyQtNodeEditor`框架 |
| 2.2 步骤属性绑定 | 每个节点配置：<br>- 关联工具（从工具库选择）<br>- 安全规则（如"必须戴护目镜"）| SQLite本地数据库存储规则 |
| 2.3 错误逻辑注入 | 右键步骤节点→添加错误分支（如漏装垫片→触发虚拟泄露事件） | `transitions`库实现状态机 |
### **FR3：考核规则配置**
| 子功能 | 详细要求 |
|-----------------------|--------------------------------------------------------------------------|
| 3.1 时间评分 | 设置步骤最大允许耗时（超时自动扣分） |
| 3.2 工具误用惩罚 | 定义错误工具扣分权重（如用普通扳手代替扭矩扳手扣50分） |
| 3.3 关键步骤标记 | 设定强制顺序步骤（跳过则判定失败） |
### **FR4：场景导出与版本控制**
| 子功能 | 详细要求 |
|-----------------------|--------------------------------------------------------------------------|
| 4.1 一键打包 | 生成.scene包（含模型路径/流程图/考核规则JSON + 资源压缩zip） |
| 4.2 版本回溯 | 自动保存5个历史版本（按时间戳命名） |
| 4.3 操作日志 | 记录用户编辑动作（示例：`[2025-07-10 14:30] 用户A修改步骤3扭矩阈值`） |
---
## 三、非功能性需求（Non-Functional Requirements）
### **NFR1：性能指标**
| 项目 | 要求 | 测试方法 |
|----------------------|-------------------------------|-----------------------------|
| 模型加载速度 | 加载100个glTF模型缩略图<3s | `timeit`模块计时 |
| 场景导出响应 | 500MB资源压缩<15s | 监控系统资源占用 |
| 同时编辑元素数 | 支持画布显示≥200个流程节点 | 压力测试（生成虚拟节点流） |
### **NFR2：兼容性要求**
| 对象 | 标准/环境 |
|----------------------|-------------------------------|
| 操作系统 | Windows 10/11, macOS 12+ |
| Python依赖库 | 通过`requirements.txt`精准管理|
| VOITS主系统接口 | 符合JSON Schema验证规范 |
### **NFR3：安全要求**
- 模型文件沙箱机制：禁止加载非glTF格式文件
- 操作日志防篡改：SQLite数据库写入后加密哈希校验
---
## 四、用户界面规范（UI Specification）
### **布局与控件**
```mermaid
graph LR
A[主界面] --> B[1. 模型库面板]
A --> C[2. 3D预览画布]
A --> D[3. 流程图编辑器]
A --> E[4. 属性配置栏]
B --> B1[树状分类导航]
B --> B2[缩略图+搜索框]
D --> D1[节点工具箱]
D --> D2[连线吸附辅助]
E --> E1[步骤参数表单]
E --> E2[考核规则矩阵]
```
### **关键交互示例**
- **模型装配**：拖拽`涡轮叶片`模型到画布 → 自动吸附到`发动机转子`子节点
- **流程配置**：右击`拆卸螺栓`节点 → 绑定`扭矩扳手`工具 → 设置超时阈值120秒
---
## 五、交付物清单（Deliverables）
1. **可执行程序**：`VOITS_Editor.exe`（PyInstaller打包单文件）
2. **配置文件模板**：
```json
// scene_config_schema.json
{
"scene_name": "jet_engine_demo",
"model_paths": ["/models/rotor.gltf", "/models/blade.gltf"],
"procedure_steps": [
{"step_id": 1, "action": "disassemble", "tool": "torque_wrench"},
{"step_id": 2, "action": "inspect", "checklist": ["crack_detection"]}
],
"assessment_rules": {"time_penalty": 10, "tool_misuse": 50}
}
```
3. **用户手册**：Markdown格式操作指南（含截图）
4. **自动测试脚本**：`test_editor.py`（覆盖率≥80%）
---
## 六、验收标准（Acceptance Criteria）
| 编号 | 测试项 | 通过条件 |
|-------|----------------------------|-------------------------------------------|
| AC1 | 导入50个glTF模型 | 缩略图生成率100%且无崩溃 |
| AC2 | 创建含20步骤的拆装流程 | 导出.scene包被VOITS主系统成功加载并执行 |
| AC3 | 设置复杂考核规则 | 学员端操作后生成评分报告匹配预设扣分逻辑 |
| AC4 | 连续操作8小时 | 内存泄漏<5MB（Valgrind检测） |
