web-map/README.md

# 场景接口

## 获取场景

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集合
  actions?: Array<string>; // 绑定动作点id集合
  isBlock?: boolean; // 是否禁行
  isForbidAvoid?: boolean; // 是否禁止避让
}
interface MapRouteInfo {
  type: MapRouteType; // 线路类型
  direction?: -1 | 1; // 方向
  pass?: MapRoutePassType; // 可通行类型
}
interface MapAreaInfo {
  type: MapAreaType; // 区域类型
  points?: Array<string>; // 绑定点位id集合
  routes?: Array<string>; // 绑定线路id集合
}

enum MapPointType {
  普通点 = 1,
  等待点,
  避让点,
  临时避让点,

  电梯点 = 11,
  自动门点,
  充电点,
  停靠点,
  动作点,
  禁行点,

  障碍点 = 99, // 待优化，后续将单独抽离
}

enum MapRouteType {
  直线 = 'line',
  三阶贝塞尔曲线 = 'bezier3',
}
enum MapRoutePassType {
  无,

  仅空载可通行,
  仅载货可通行,

  禁行 = 10,
}

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>; // 场景中的机器人组