Smart Dog Scratch 编程平台

基于 Scratch 的可视化编程平台，专注于工作区数据和自定义积木块管理，用于控制智能小狗机器人。

🎯 核心功能

1. Scratch 积木块编程界面

• 拖拽式编程：类似 MIT Scratch 的直观界面
• 小狗控制积木块：前进、转向、叫、等待等基础控制
• 逻辑运算积木块：条件判断、循环控制、数学运算
• 文本和数组处理：字符串操作、数组管理功能
• 变量和函数：支持变量定义和函数创建

2. 数据管理功能（新增）

• 工作区数据管理：实时保存 Blockly 工作区状态
• 自定义积木块系统：创建、编辑、删除自定义积木块
• 自动保存机制：工作区变化自动保存到浏览器本地存储
• 文件导入/导出：支持 JSON 格式和 Blockly XML 格式
• 工作区统计：实时显示积木块数量、变量、函数等统计信息

3. 小狗控制面板

• 实时连接状态：显示与智能小狗的连接状态
• 状态监控：电量、位置、方向等实时数据
• 传感器显示：距离、声音、温度传感器数据
• 快速控制：手动控制按钮和命令发送

4. 代码生成与调试

• 实时代码生成：将积木块转换为 JavaScript 代码
• 调试工具：代码调试和错误检测功能
• 代码助手：智能代码建议和优化

📁 项目结构

smartdog-scratch/
├── src/                          # React前端应用
│   ├── components/              # 组件目录
│   │   ├── ScratchEditor.tsx    # Scratch编程编辑器
│   │   ├── DogControlPanel.tsx  # 小狗控制面板
│   │   ├── CodeOutput.tsx       # 代码输出面板
│   │   ├── CustomBlockManager.tsx # 自定义积木块管理器
│   │   ├── DebugPanel.tsx       # 调试工具面板
│   │   ├── CodeAssistant.tsx    # 代码助手面板
│   │   ├── FileManager.tsx      # 文件管理组件（新增）
│   │   └── FileManager.css      # 文件管理样式（新增）
│   ├── services/                # 服务层
│   │   ├── dogService.ts       # 小狗通讯服务
│   │   └── dataService.ts      # 数据管理服务（新增）
│   ├── App.tsx                 # 主应用组件
│   └── App.css                 # 全局样式
├── backend/                     # 后端API服务
│   ├── server.js              # Express服务器
│   └── package.json           # 后端依赖
├── 数据管理功能说明.md          # 详细数据管理文档（新增）
└── README.md                  # 项目文档

🚀 快速开始

1. 安装依赖

# 安装前端依赖
cd smartdog-scratch
npm install

2. 启动应用

详细启动步骤

方法 1：Python 脚本启动（推荐）

# 确保已安装Python 3
python start.py
# 或
python3 start.py

方法 2：Windows 批处理启动

# 双击 start.bat 或运行：
start.bat

方法 3：原始 Shell 脚本启动

# Linux/macOS
chmod +x start.sh  # 首次运行需要添加执行权限
./start.sh

手动启动（适用于开发者）

# 安装后端依赖
cd backend
npm install
cd ..

# 启动后端服务
cd backend
npm start &
cd ..

# 启动前端服务
npm start

3. 访问应用

打开浏览器访问：http://localhost:3000

注意：如果需要连接实际的智能小狗硬件，请同时启动后端服务

📖 使用指南

1. 开始编程

1. 打开应用后，会自动创建一个新的工作区
2. 从左侧工具箱拖拽积木块到工作区
3. 连接积木块创建程序逻辑

2. 数据管理操作

使用"文件"菜单进行数据管理：

工作区操作

• 新建工作区：创建空白工作区
• 保存到本地存储：保存当前工作区到浏览器
• 导出为文件：将工作区导出为 JSON 格式文件
• 从文件导入：从 JSON 文件恢复工作区

XML 格式兼容

• 导出工作区 XML：导出为 Blockly XML 格式
• 导入工作区 XML：从 XML 文件导入工作区

数据管理

• 清除本地存储：删除所有保存的数据
• 查看工作区信息：查看统计信息和自定义积木块

3. 自定义积木块

1. 点击"管理自定义积木块"按钮
2. 在管理器中创建新的积木块定义
3. 设置名称、分类、颜色和输入参数
4. 定义代码生成模板
5. 新的积木块会自动出现在工具箱中

4. 连接与控制

1. 在控制面板输入小狗的 IP 地址和端口
2. 点击"连接小狗"按钮建立连接
3. 使用积木块编程或快速控制按钮
4. 点击"生成代码"查看生成的 JavaScript
5. 点击"执行程序"发送程序到小狗

🔧 数据管理功能详解

核心数据实体

工作区数据 (Workspace Data)

包含 Blockly 工作区的完整状态：

• XML 格式：Blockly 工作区布局
• 积木块信息：所有积木块的序列化数据
• 变量定义：用户定义的变量列表
• 函数定义：自定义函数信息

自定义积木块 (Custom Blocks)

用户创建的可重用积木块：

• 唯一标识：每个积木块的唯一 ID
• 显示名称：用户友好的名称
• 分类归属：组织到特定分类
• 颜色标识：视觉区分
• 输入参数：支持多种参数类型
• 代码模板：JavaScript 代码生成规则

数据持久化策略

自动保存机制

• 实时保存：工作区变化时自动保存
• 防抖处理：避免频繁保存影响性能
• 本地存储：使用浏览器 localStorage
• 崩溃恢复：支持从意外关闭中恢复

文件格式

• JSON 格式 (.smartdog)：完整数据保存
• XML 格式 (.xml)：兼容 Blockly 标准
• 版本控制：支持未来数据迁移

🛠️ 开发指南

扩展数据管理功能

添加新的数据实体

1. 在 dataService.ts 中定义新的接口
2. 添加相应的 CRUD 操作方法
3. 更新 WorkspaceData 接口包含新实体
4. 在 FileManager 中添加对应的 UI 操作

自定义积木块开发

1. 在 ScratchEditor.tsx 的 registerCustomBlocks 函数中定义积木块
2. 注册积木块类型到 Blockly
3. 添加 JavaScript 代码生成器
4. 更新工具箱配置包含新积木块

样式自定义

• 全局样式：编辑 App.css 文件
• 组件样式：各组件有自己的 CSS 文件
• 响应式设计：支持移动端和桌面端

📊 技术栈

前端技术

• React 19 + TypeScript：现代前端框架
• Blockly：Google 可视化编程库
• CSS3 + Flexbox：响应式布局和样式
• localStorage API：浏览器数据存储

后端技术（可选）

• Node.js + Express：API 服务器
• WebSocket：实时通讯支持
• RESTful API：标准接口设计

📄 许可证

MIT License - 详见 LICENSE 文件

🤝 贡献指南

1. Fork 项目：创建个人分支
2. 创建功能分支：基于开发需求
3. 提交更改：遵循代码规范
4. 推送到分支：保持提交记录清晰
5. 创建 Pull Request：详细描述更改内容

🐛 问题反馈

如果遇到问题或有改进建议：

1. 查看文档：阅读 数据管理功能说明.md 获取详细说明
2. 提交 Issue：在项目仓库创建 Issue
3. 联系维护者：通过项目联系方式获取帮助

🔮 未来规划

计划功能

• 云同步：跨设备工作区同步
• 版本历史：工作区历史版本管理
• 项目模板：预定义项目模板库
• 协作编辑：多人实时协作功能

技术改进

• 增量保存：优化保存性能
• 数据压缩：减少存储空间占用
• PWA 支持：渐进式 Web 应用特性

---

Smart Dog Scratch 致力于为智能小狗编程提供直观、可靠的可视化编程体验，专注于工作区数据和自定义积木块管理，确保用户数据的完整性和可访问性。