> 本示例文档以物体移动为例，代码参考 `packages-user/data-common/src/common/mover.ts`。文档较为简略，实际编写的时候可以更丰富一些。

# 需求综述

为提供更便捷的物体移动接口，故进行本设计。本设计提供统一的移动接口 `IObjectMover`，并完成其抽象实现 `abstract class ObjectMover`，以方便具体拓展。

# 需求理解

## 明确需求

1. 移动与物体分离。移动与物体是独立的两个系统，二者之间不应存在任何耦合，移动单方面调用物体。
2. 移动计划。移动器需要包含移动计划及其执行两个阶段，先形成计划，再进行执行。
3. 移动流程控制。移动时需要提供相应的接口干预移动本身。

## 隐含需求

1. 异步执行。移动自然需要动画，因此移动本身必然是异步的。
2. 移动物体。不是所有的物体都能够移动，只有某些可以，这些应该被称为可移动物体。

## 未确定需求

1. 一个物体能不能绑定两个移动器？

# 设计前提

1. 网格移动。所有移动均基于离散网格，不支持连续空间移动。
2. 允许自定义拓展。允许自定义移动策略，不是所有的移动都由某一个类统一实现。

# 核心概念定义

> 这里是一个示例，实际情况中可以更丰富一些。

## 移动

一个物体的坐标从一点改变至另一点的行为称为移动。

## 可移动物体

所有可以被移动器移动的物体都可以被称为可移动物体，它们的核心特征是包含坐标信息，并拥有设置其坐标的接口。最常见的可移动物体是地图上的动态图块以及玩家操控的勇士。

## 移动器

一种对移动的抽象接口，可以通过调用可移动物体的坐标接口来操控可移动物体，但其提供的接口往往更加丰富，且拥有计划机制，允许进行连续移动。

# 接口设计分析

默认场景下，移动主要发生在两种物体上：地图动态图块及玩家操控的勇士。二者的主要差别在于后者由玩家操控，需要进行移动判定，例如需要进行通行性判定，事件触发判定等，而前者通常由系统代码控制，且常用于演出，并不需要进行判定。

## IObjectMover

### 设计思路

> 这部分应当分析需求，并写明接口是如何设计出来的，而不是简单地阐述接口内容。

对于玩家操控，判定往往发生在移动前，因此为统一接口，设计出 `onStepStart` 与 `onStepEnd` 两个接口，前者进行判定，后者根据判定结果进行相应的操作。为了让后者知道判定结果，将 `onStepStart` 的返回值设计为 `Promise<number>`，`onStepEnd` 接收之并执行操作。

在实际情况中，常见的使用场景是先规划好线路，然后让物体移动，因此接口需要设计成计划式，计划完成后通过 `start` 接口开始移动，故需要两个接口 `onMoveStart` 和 `onMoveEnd` 分别在移动开始前和结束后执行某些操作。

为了能够在开始移动后对移动进行干预及监听，`start` 应返回 `IMoveController` 作为返回值，其中应包含临时在当前步后插入一步、在当前移动队列后插入一步、下一步结束后立刻停止移动、当移动结束后兑现的 `Promise` 等内容。

接下来考虑移动计划，最通用的移动方法是指定移动方向与物体的面朝朝向，然后物体面朝指定朝向，向移动方向移动一格，故需要 `stepFace` 接口。在绝大多数情况下，移动方向与朝向是一致的，故提供 `step` 接口。除了这种情况，还会包含前进一格的需求，故提供 `forward` 接口；与之对应，还提供 `backward` 后退接口，而且在多数情况下，后退往往代表面朝前向后走，这里也使用这一语义。在后退时，移动动画的播放进度应该相反，故提供 `animDir` 接口。在移动时，移动速度是一个重要参数，故提供 `speed` 接口。在某些情况下，物体可能会需要瞬移，故提供 `tp` 接口。除了这些，还需要提供转向接口 `face`，调整面朝朝向；以及一个相对比较常见的 `jump` 接口。

对于移动对象，仅需要 `x` `y` `setPos` `getCurrentFaceDirection` 接口即可完成所有上述行为，故将这几个接口包装为 `IObjectMovable`，同时 `interface IObjectMover<T extends IObjectMovable>` 允许自定义拓展。

### 接口分析

> 此处仅列出部分。

- `IObjectMover.forward(count?: number)`：预期频率**高频**。向前移动一格是地图行走、动画演出等场景的核心需求，在逻辑与演出中都会频繁出现，故为高频。
- `IObjectMover.speed(speed: number)`：预期频率**中频**。移动中修改移速有一定使用场景，但远不及 `forward`、`step` 等移动接口的频率，通常只在特殊演出或逻辑中出现，故为中频。
- `IObjectMover.stepFace(move: FaceDirection, face: FaceDirection, count?: number)`：预期频率**低频**。移动方向与朝向不同的常见场景（后退）已由 `backward` 覆盖，只有极特殊情况才需要此接口（如角色朝向固定但沿垂直方向平移），相当罕见，故为低频。

### 预期体量

预期代码体量为 200-300 行。分析如下：

- 计划功能预期 100 行：`IObjectMover` 首先需要完成计划存储与计划的定义，这些接口基本大致就是向数组中添加元素，每个方法内容都不多。
- 移动流程预期 200 行：`IObjectMover` 还需要完成移动流程的编写工作，需要根据每个移动步按照流程执行不同的行为，这一过程较为复杂。

## IMoveController

...

# 实现思路

> 仅列出实现思路较为复杂的内容，例如像计划存储等属于非常直观简单的内容，不需要列出实现思路。

## 移动流程控制

核心难点在于如何进行移动控制，以下为核心思路。

1. 为实现移动流程，首先需要写一个大循环来处理每一个移动步。
2. 对于每一个移动步，首先调用 `onStepStart` 接口，获取移动 `code`，然后触发钩子，然后进行 `onStepEnd` 的执行，其返回值作为移动后的目标位置，最后触发钩子。

# 涉及文件

## `@user/data-common/src/common/mover.ts`

- [ ] 编写 `IObjectMover` 接口：按照本文描述完成设计
- [ ] 编写 `IObjectMovable` 接口：按照本文描述完成设计
- [ ] 编写 `IMoveController` 接口：按照本文描述完成设计
- [ ] 完成每个移动步的接口设计：每个移动步都需要一个接口对象，本文未明确提及，需包含每种移动计划
- [ ] 完成移动枚举的编写：每种移动计划都需要一个枚举类型来标注
- [ ] 编写 `ObjectMover` 抽象类：实现 `IObjectMover` 接口，作为移动基类