From 7081d3dfa8f968fdd43be8cbe97946b41e3ee6d8 Mon Sep 17 00:00:00 2001
From: chndfang <chndfang@outlook.com>
Date: Tue, 6 May 2025 17:29:20 +0800
Subject: [PATCH] md

---
 README.md | 157 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 154 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 33895ab..b90a4d0 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,156 @@
-# Vue 3 + TypeScript + Vite
+# 场景接口
 
-This template should help get you started developing with Vue 3 and TypeScript in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.
+## 获取场景
 
-Learn more about the recommended Project Setup and IDE Support in the [Vue Docs TypeScript Guide](https://vuejs.org/guide/typescript/overview.html#project-setup).
+POST /scene/getById
+
+请求体：
+{ id: string }
+
+响应体：
+SceneDetail
+
+示例：
+
+```json
+{
+  "code": 200,
+  "success": true,
+  "data": {
+    "id": "mock-scene-1",
+    "label": "模拟场景A",
+    "json": "{\"x\":0,\"y\":0,\"scale\":1,\"pens\":[],\"origin\":{\"x\":0,\"y\":0},\"center\":{\"x\":0,\"y\":0},\"paths\":{},\"template\":\"4c2a10f\",\"locked\":10,\"version\":\"1.0.78\",\"dataPoints\":[],\"robotGroups\":[{\"id\":\"mock-robot-group-1\",\"label\":\"模拟机器人组A\",\"robots\":[\"mock-robot-1\",\"mock-robot-2\",\"mock-robot-3\"]},{\"sid\":\"mock-scene-1\",\"id\":\"mock-robot-group-2\",\"label\":\"模拟机器人组B\",\"robots\":[\"mock-robot-4\"]}],\"robots\":[{\"gid\":\"mock-robot-group-1\",\"id\":\"mock-robot-1\",\"label\":\"模拟机器人A\",\"brand\":\"模拟品牌A\",\"type\":1,\"ip\":\"127.0.1.1\"},{\"gid\":\"mock-robot-group-1\",\"id\":\"mock-robot-2\",\"label\":\"模拟机器人B\",\"brand\":\"模拟品牌A\",\"type\":2,\"ip\":\"127.0.1.2\"},{\"gid\":\"mock-robot-group-1\",\"id\":\"mock-robot-3\",\"label\":\"模拟机器人C\",\"brand\":\"模拟品牌A\",\"type\":3,\"ip\":\"127.0.1.3\"},{\"gid\":\"mock-robot-group-2\",\"id\":\"mock-robot-4\",\"label\":\"模拟机器人D\",\"brand\":\"模拟品牌B\",\"type\":1,\"ip\":\"127.0.2.1\"}]}"
+  },
+  "message": "模拟提示"
+}
+```
+
+# 数据结构
+
+1. 场景相关
+
+```typescript
+interface SceneDetail {
+  id: string; // 场景id
+  label: string; // 场景名称
+  json?: string; // 场景JSON
+}
+```
+
+2. 机器人相关
+
+```typescript
+interface RobotGroup {
+  id: string; // 机器人组id
+  label: string; // 机器人组名称
+  robots?: Array<string>; // 机器人列表
+}
+
+interface RobotInfo {
+  gid?: string; // 机器人组id
+  id: string; // 机器人id
+  label: string; // 机器人名称
+  brand: RobotBrand; // 机器人品牌
+  type: RobotType; // 机器人类型
+  ip: string; // 机器人ip
+  battery?: number; // 机器人电量
+  isConnected?: boolean; // 机器人连接状态
+  state?: RobotState; // 机器人状态
+  canOrder?: boolean; // 接单状态
+  canStop?: boolean; // 急停状态
+  canControl?: boolean; // 控制状态
+}
+
+enum RobotBrand {
+  '先工' = 1,
+}
+enum RobotType {
+  叉车机器人 = 1,
+  AMR机器人,
+  料箱机器人,
+}
+enum RobotState {
+  任务执行中 = 1,
+  充电中,
+  停靠中,
+  空闲中,
+}
+```
+
+3. 地图相关
+
+```typescript
+interface MapPen {
+  id: string; // 唯一标识
+  name: string; // 唯一名称（用于识别图元，包含点位-point、线路-line、区域-area）
+  x: number; // 横坐标
+  y: number; // 纵坐标
+  width: number; // 宽度
+  height: number; // 高度
+
+  label?: string; // 展示名称
+  desc?: string; // 描述
+
+  point?: MapPointInfo; // 点位信息
+  route?: MapRouteInfo; // 线路信息
+  area?: MapAreaInfo; // 区域信息
+
+  attrs?: Record<string, unknown>; // 额外属性
+  activeAttrs?: Array<string>; // 已激活的额外属性
+}
+
+interface MapPointInfo {
+  type: MapPointType; // 点位类型
+  robots?: Array<RobotInfo['id']>; // 绑定机器人id集合
+}
+interface MapRouteInfo {
+  type: MapRouteType; // 线路类型
+  direction?: -1 | 1; // 线路方向
+}
+interface MapAreaInfo {
+  type: MapAreaType; // 区域类型
+  points?: Array<string>; // 绑定点位id集合
+  routes?: Array<string>; // 绑定线路id集合
+}
+
+enum MapPointType {
+  普通点 = 1,
+  等待点,
+  避让点,
+  临时避让点,
+
+  电梯点 = 11,
+  自动门点,
+  充电点,
+  停靠点,
+  动作点,
+  禁行点,
+
+  障碍点 = 99, // 待优化，后续将单独抽离
+}
+enum MapRouteType {
+  直线 = 'line',
+  三阶贝塞尔曲线 = 'bezier3',
+}
+enum MapAreaType {
+  库区 = 1,
+
+  互斥区 = 11,
+  非互斥区,
+}
+```
+
+# 场景文件格式
+
+1. 场景文件格式为json格式，包含以下字段：
+   template: string; // 模板id（只读）
+   locked: number; // 锁定状态（后端无需处理）
+   version: string; // 版本号（后端无需处理）
+   x: number; // 地图在画布中的横坐标
+   y: number; // 地图在画布中的纵坐标
+   scale: number; // 地图缩放比例
+   origin: { x: number; y: number; }; // 地图原点坐标
+   center: { x: number; y: number; }; // 地图中心点坐标
+   pens: Array<MapPen>; // 地图元素（包含点位、线路、区域）
+   robots: Array<RobotInfo>; // 场景中的机器人
+   robotGroups: Array<RobotGroup>; // 场景中的机器人组