完整版产品需求文档 (PRD): “Orion” 沉浸式培训流程编辑器

• 版本: 1.1
• 日期: 2025年9月23日
• 文档状态: 最终版

---

1. 产品愿景与目标

1.1 产品愿景

“Orion” 编辑器旨在赋能各行业的培训专家，使其能够通过一个直观、无代码的图形化界面，快速设计、构建和管理复杂的培训与考核流程。本产品是连接专业领域知识与沉浸式三维培训体验的核心桥梁。

1.2 目标与要解决的问题

• 目标用户: 企业内训师、行业专家、教学设计师、模拟仿真工程师。
• 解决的问题:
  1. 高昂的开发成本: 传统沉浸式培训内容的创建需要专业的程序员和三维艺术家紧密配合，开发周期长，成本高。
  2. 专业知识壁垒: 行业专家无法直接将他们的知识和流程转化为可执行的培训程序。
  3. 流程迭代困难: 对现有培训流程的任何微小修改都需要重新编程和编译，响应速度慢。

1.3 V1.0 核心目标

交付一个功能完备、稳定可靠的纯前端单机版编辑器。它能够让用户独立完成培训流程的创建、编辑，并导出标准化的 YAML 配置文件，为下游的三维引擎加载端提供清晰、可执行的指令。

---

2. 用户画像 (User Personas)

• 安娜 (Anna) - 培训设计师:
  • 背景: 某大型制造企业的资深培训师，精通设备操作规程，但没有编程背景。
  • 痛点: 每次更新培训内容，都需要向IT部门提需求，沟通成本高，效率低下。
  • 期望: “我希望能有一个像画流程图一样简单的工具，让我自己就能把操作步骤、考核要点都设计好，然后直接在我们的VR模拟器里跑起来。”
• 大卫 (David) - 3D引擎开发者:
  • 背景: 负责公司Unity/Unreal项目的技术开发。
  • 痛点: 经常需要花费大量时间将业务部门提供的Word文档或流程图“翻译”成代码逻辑。
  • 期望: “我希望业务部门能给我一个标准化的、机器可读的数据文件。我只需要写一个通用的解析器，就能自动生成培训场景，而不是为每个培训项目都硬编码逻辑。”

---

3. 系统架构与设计

3.1 总体架构

本系统为纯客户端单页面应用 (SPA)，无需后端支持。所有数据处理和文件操作均在用户浏览器端完成。

• 部署方式: 静态网站托管 (如 Vercel, Netlify, GitHub Pages)。
• 核心交互: 用户通过图形化界面编排流程 -> 系统在内存中维护状态 -> 用户导出流程为 .yaml 文件 -> 用户将文件提供给三维引擎加载端使用。

---

4. 功能需求 (Functional Requirements)

4.1 模块一: 可视化流程编辑器 (画布 Canvas)

• FR-1.1: 画布应支持无限拖拽平移和滚轮缩放，提供流畅的导航体验。
• FR-1.2: 用户可以在画布内的任意位置拖拽和移动节点。
• FR-1.3: 用户可以从节点的连接桩 (Handle) 拖拽出连线，并连接到另一个节点的连接桩上。
• FR-1.4: 系统应能自动对齐节点，并提供对齐辅助线。
• FR-1.5: 用户可以框选多个节点和连线进行批量操作（移动、删除）。

4.2 模块二: 组件库面板 (Component Library)

• FR-2.1: 面板应以列表或网格形式清晰地展示所有可用的节点类型（如：开始、结束、播放视频、单项选择题、操作提示等）。
• FR-2.2: 用户可以从该面板拖拽一个节点类型到画布的任意位置，松手后在该位置创建一个新的节点实例。

4.3 模块三: 属性配置面板 (Properties Panel)

• FR-3.1: 当用户在画布上选中一个节点或连线时，该面板应自动显示其对应的可配置属性。
• FR-3.2: 面板应根据所选元素的属性定义（Schema）动态生成配置表单（如文本输入框、下拉选择、文件上传按钮等）。
• FR-3.3: 用户在面板中修改的属性值应实时反映到画布中的节点数据上。
• FR-3.4: 面板应对用户输入进行实时校验（如：必填项、URL格式等），并提供清晰的错误提示。

4.4 模块四: 文件管理与导出

• FR-4.1: 用户应能点击“导出”按钮，将当前画布上的完整流程（包括所有节点、连线及其属性）序列化为一个 .yaml 文件并下载到本地。
• FR-4.2: 用户应能点击“导入”按钮，通过文件选择器加载一个本地的 .yaml 文件，并将其内容完整地还原到画布上。
• FR-4.3: 提供“新建”功能，用于清空当前画布，开始一个全新的流程设计。

4.5 模块五: 全局工具栏 (Toolbar)

• FR-5.1: 提供撤销 (Undo) 和 重做 (Redo) 功能，支持多步操作历史。
• FR-5.2: 提供“保存”（即导出）和“打开”（即导入）的快捷按钮。
• FR-5.3: 提供“自动布局”功能，可一键整理画布上所有节点的布局。

---

5. 非功能性需求 (Non-Functional Requirements)

• NFR-1 (性能): 在画布上存在200个节点时，拖拽、缩放等操作应保持流畅，无明显卡顿。
• NFR-2 (易用性): 界面应简洁直观，无编程经验的用户通过简单的引导即可上手使用。所有交互应符合主流图形编辑软件的习惯。
• NFR-3 (兼容性): 应兼容最新版本的 Chrome, Firefox, Edge 浏览器。
• NFR-4 (可扩展性): 添加一种新的节点类型应是低耦合的，仅需定义其外观、属性Schema和连接规则即可，无需改动编辑器核心代码。

---

6. 技术栈推荐

分类	技术/库	备注
前端框架	React (使用 Vite 构建)	业界主流，生态完善
UI 组件库	Ant Design (AntD)	提供高质量的企业级组件
状态管理	Zustand	轻量、简洁、高效
可视化编辑器	React Flow	功能强大且高度可定制的节点库
拖拽功能	dnd-kit	现代化的React拖拽库，用于从组件库拖拽
动态表单	react-jsonschema-form	根据Schema自动生成属性配置面板
YAML处理	js-yaml	用于YAML的解析与序列化

---

7. 数据格式规范 (YAML Schema)

导出的 orion.flow.yaml 文件应遵循以下结构。该结构是前端编辑器与三维加载端之间的核心契约。

# Orion 沉浸式培训流程配置文件
# 版本: 1.0
# 流程名称: 某型号压缩机启动安全检查
# 创建时间: 2025-09-23T10:00:00Z

# --- 元数据 ---
metadata:
  version: "1.0"
  flowName: "某型号压缩机启动安全检查"
  author: "Anna"

# --- 节点列表 ---
# 定义了流程中的每一个步骤
nodes:
  - id: "node-1" # 节点的唯一标识符
    type: "startNode" # 节点类型，加载端根据此类型执行不同逻辑
    position: { x: 50, y: 100 } # 节点在画布上的位置，仅供编辑器使用
    data:
      label: "开始流程"

  - id: "node-2"
    type: "instructionNode"
    position: { x: 250, y: 100 }
    data:
      label: "穿戴个人防护装备"
      # 指令节点的详细文本，支持Markdown
      text: "请确保您已正确穿戴以下装备：\\n- 安全帽\\n- 防护手套\\n- 护目镜"
      # 可选：关联一个三维模型进行高亮提示
      targetModelId: "ppe_equipment_model"

  - id: "node-3"
    type: "quizSingleChoiceNode"
    position: { x: 500, y: 100 }
    data:
      label: "安全知识考核"
      question: "启动设备前，必须按下的紧急停止按钮应处于什么状态？"
      options:
        - id: "opt-a"
          text: "A. 按下状态"
        - id: "opt-b"
          text: "B. 弹起状态"
      correctOptionId: "opt-b" # 正确答案的ID

# --- 边列表 ---
# 定义了节点之间的连接关系和流程走向
edges:
  # 从“开始”到“穿戴装备”
  - id: "edge-1-2"
    source: "node-1" # 源节点ID
    target: "node-2" # 目标节点ID
    sourceHandle: "sh-1-out" # 源节点的哪个连接桩
    targetHandle: "th-2-in" # 目标节点的哪个连接桩

  # 从“穿戴装备”到“安全考核”
  - id: "edge-2-3"
    source: "node-2"
    target: "node-3"
    sourceHandle: "sh-2-out"
    targetHandle: "th-3-in"

---

8. V1.0 范围之外 (Future Roadmap)

• 用户认证与云端项目存储
• 多人实时协作编辑
• 版本历史与回滚
• 与三维资源库的集成（直接在编辑器中选择和预览3D模型）
• 流程逻辑的条件分支与变量系统
• 发布为可复用的流程模板

---

附录A: 技术设计规范

---

9. 程序结构设计 (Program Structure Design)

为保证项目的可维护性、可扩展性和团队协作效率，项目采用功能模块化的目录结构。

9.1 推荐目录结构 (基于Vite + React)

orion-editor/
├── public/                  # 静态资源 (favicon, etc.)
├── src/
│   ├── assets/              # 图片, SVG, 字体等项目资源
│   ├── components/          # 全局可复用UI组件
│   │   ├── common/          # 基础原子组件 (Button, Input, Modal...)
│   │   └── layout/          # 页面布局组件 (Header, Sidebar, CanvasContainer...)
│   ├── features/            # **核心功能模块目录**
│   │   ├── editor-canvas/   # 画布核心功能
│   │   ├── node-library/    # 节点库面板
│   │   ├── properties-panel/ # 属性配置面板
│   │   └── file-handler/    # 文件导入导出逻辑
│   ├── hooks/               # 自定义React Hooks (e.g., useDebounce)
│   ├── store/               # 全局状态管理 (Zustand)
│   │   └── flowStore.ts     # 负责管理节点、边的核心状态
│   ├── types/               # 全局TypeScript类型定义
│   │   └── index.ts         # (e.g., INode, IEdge)
│   ├── utils/               # 通用工具函数 (e.g., yamlParser.ts, idGenerator.ts)
│   ├── App.tsx              # 应用主组件
│   └── main.tsx             # 应用入口文件
├── .eslintrc.cjs            # ESLint 配置文件
├── .prettierrc.json         # Prettier 配置文件
├── package.json
└── tsconfig.json

9.2 组件设计哲学

• 函数式组件与Hooks: 所有组件必须使用函数式组件 (Functional Components) 配合 Hooks 编写。
• 关注点分离: 遵循“容器(Container)”与“展示(Presentational)”组件的分离思想。
• 高内聚，低耦合: 每个功能模块 (features/下的目录) 应尽可能独立。

9.3 状态管理策略

• 全局状态 (Zustand): 用于管理整个流程图的核心数据（所有节点、边），作为唯一的数据信任源。
• 组件本地状态 (useState): 用于管理与UI相关的、不影响全局数据的状态。

10. 编码规范 (Coding Standards)

10.1 语言与工具

• 语言: TypeScript。强制使用，确保类型安全。
• 代码格式化: Prettier。在代码提交时自动格式化。
• 代码质量检查: ESLint。用于发现代码中的潜在问题和不规范写法。

10.2 命名规范

• 组件文件/函数: PascalCase (e.g., PropertiesPanel.tsx)。
• 变量/函数/Hooks: camelCase (e.g., const nodeData, useFlowState)。
• TypeScript类型/接口: PascalCase 并使用 I 或 T 前缀 (e.g., interface INodeConfig)。

10.3 注释规范

• 复杂函数: 必须添加 JSDoc 注释，说明函数功能、参数 (@param) 和返回值 (@returns)。
• 业务逻辑: 必须添加注释，解释“为什么”这么做。

10.4 Git 工作流

• 分支模型: 推荐使用 GitHub Flow。从 main 创建特性分支 feat/xxx 或 fix/xxx。
• 提交信息 (Commit Message): 必须遵循 Conventional Commits 规范。
  • 格式: <type>(<scope>): <subject>
  • 示例: feat(editor): add new quiz node type

---

---

以上便是为您整合的完整版PRD。它包含了从产品战略到工程实现的全方位规划，可以作为您项目启动和开发的核心指导文件。