refactor(02-04): restore authorized path contract

- Match path/types.ts to the user-authored baseline plus nullable returns
- Keep graph contracts implementation-owned and preserve the mover bridge

packages-user/data-system/src/path/finder.ts

@@ -7,12 +7,8 @@ import {
 } from '@user/data-base';
 import { isNil } from 'lodash-es';
 import { PathfindingGraphBuilder } from './graph';
-import {
-    IPathfinder,
-    IPathfindingStep,
-    IPathGraph,
-    PathCostFunction
-} from './types';
+import { IPathfinder, IPathfindingStep, PathCostFunction } from './types';
+import { IPathGraph } from './graph';
 
 interface IDistanceHeapEntry {
     /** 条目的键值，堆中键值最小的条目最先取出 */

packages-user/data-system/src/path/graph.ts

@@ -15,13 +15,79 @@ import {
     IPassPredicate
 } from '@user/data-base';
 import { isNil } from 'lodash-es';
-import {
-    IPathGraph,
-    IPathGraphEdge,
-    IPathGraphNode,
-    IPathfindingGraphBuilder,
-    PathCostFunction
-} from './types';
+import { PathCostFunction } from './types';
+
+export interface IPathGraphEdge {
+    /** 本条边对应的移动方向 */
+    readonly dir: FaceDirection;
+    /** 边指向的节点索引，值为 y * width + x */
+    readonly to: number;
+}
+
+export interface IPathGraphNode {
+    /** 节点索引，值为 y * width + x */
+    readonly index: number;
+    /** 节点横坐标 */
+    readonly x: number;
+    /** 节点纵坐标 */
+    readonly y: number;
+    /** 节点对应的位置信息 */
+    readonly block: ILayerLocation;
+    /** 进入该节点的损失，构建图时由损失函数计算 */
+    readonly cost: number;
+    /** 该节点是否仅可作为路径终点，不可作为中间节点 */
+    readonly terminal: boolean;
+    /** 该节点的全部出边 */
+    readonly edges: readonly IPathGraphEdge[];
+}
+
+export interface IPathGraph {
+    /** 图宽度 */
+    readonly width: number;
+    /** 图高度 */
+    readonly height: number;
+    /** 图内全部节点，键为节点索引 */
+    readonly nodes: ReadonlyMap<number, IPathGraphNode>;
+}
+
+export interface IPathfindingGraphBuilder {
+    /**
+     * 绑定地图状态对象，用于解析图层所属楼层 id
+     * @param maps 地图状态对象
+     */
+    useMapState(maps: IMapState | null): void;
+
+    /**
+     * 绑定构建有向图所用的地图图层
+     * @param layer 地图图层对象
+     */
+    useMapLayer(layer: IMapLayer | null): void;
+
+    /**
+     * 设置构建图时使用的损失函数，未注入时每格损失 1
+     * @param cost 损失函数
+     */
+    useCostFunction(cost: PathCostFunction | null): void;
+
+    /**
+     * 注入判定边可行性的通行性谓词
+     * @param predicate 通行性谓词
+     */
+    usePassPredicate(predicate: IPassPredicate | null): void;
+
+    /**
+     * 设置邻域使用的方向组
+     * @param group 朝向组
+     */
+    useDirGroup(group: number): void;
+
+    /**
+     * 以起始位置为中心构建有向图：沿可通行有向边 BFS 扩展，
+     * 仅包含从起始位置可达的节点。图层未绑定或起始位置越界时告警并返回空图
+     * @param start BFS 起始位置
+     */
+    build(start: ITileLocator): IPathGraph;
+}
 
 /**
  * 将方向描述器的坐标增量解析为对应的朝向

packages-user/data-system/src/path/system.ts

@@ -17,6 +17,8 @@ export class PathfindingSystem implements IPathfindingSystem {
 
     /** 绑定的移动器对象 */
     private mover: IObjectMover<IObjectMovable> | null = null;
+    /** 绑定的移动对象，用于保留用户契约的对象绑定入口 */
+    private movable: IObjectMovable | null = null;
     /** 注入的瞬移回退策略，未注入时必定回退为逐步寻路 */
     private policy: PathFallbackPolicy | null = null;
     /** 最近一次寻路移动的控制器包装 */
@@ -26,8 +28,13 @@ export class PathfindingSystem implements IPathfindingSystem {
         this.finder = new PathfindingFinder(state);
     }
 
+    useMovable(movable: IObjectMovable | null): void {
+        this.movable = movable;
+    }
+
     useMover(mover: IObjectMover<IObjectMovable> | null): void {
         this.mover = mover;
+        this.movable = mover ? mover.tile : null;
     }
 
     useFallbackPolicy(policy: PathFallbackPolicy | null): void {
@@ -36,11 +43,13 @@ export class PathfindingSystem implements IPathfindingSystem {
 
     getPath(target: ITileLocator): IPathfindingStep[] {
         const mover = this.mover;
-        if (isNil(mover)) {
+        const movable = this.movable;
+        if (isNil(mover) && isNil(movable)) {
             logger.warn(173);
             return [];
         }
-        const tile = mover.tile;
+        const tile = mover ? mover.tile : movable;
+        if (!tile) return [];
         return this.finder.find({ x: tile.x, y: tile.y }, target);
     }
 

packages-user/data-system/src/path/types.ts

@@ -9,12 +9,9 @@ import {
 import {
     FaceDirection,
     IMoverController,
-    IObjectMovable,
-    IObjectMover
+    IObjectMovable
 } from '@user/data-common';
 
-//#region 寻路系统
-
 export interface IPathfindingStep {
     /** 移动方向 */
     readonly dir: FaceDirection;
@@ -88,9 +85,9 @@ export interface IPathfindingSystem extends IDataBaseExtended {
 
     /**
      * 绑定寻路移动对象，可绑定勇士位置或任意 `IObjectMovable`，如动态图块
-     * @param mover 移动对象
+     * @param movable 移动对象
      */
-    useMover(mover: IObjectMover<IObjectMovable> | null): void;
+    useMovable(movable: IObjectMovable | null): void;
 
     /**
      * 设置瞬移回退策略，默认必定回退为逐步寻路
@@ -107,12 +104,14 @@ export interface IPathfindingSystem extends IDataBaseExtended {
     /**
      * 逐步寻路至目标位置，触发途经事件
      * @param target 目标坐标
+     * @returns 移动控制器。无法寻路、无路径或已有移动进行中时返回 `null`
      */
     moveTo(target: ITileLocator): IPathfindingController | null;
 
     /**
      * 瞬移至目标位置。瞬移前经回退策略判定，判定需要回退则自动退为逐步寻路
      * @param target 目标坐标
+     * @returns 移动控制器；无法寻路、无路径或已有移动进行中时返回 `null`
      */
     teleportTo(target: ITileLocator): IPathfindingController | null;
 
@@ -121,81 +120,3 @@ export interface IPathfindingSystem extends IDataBaseExtended {
      */
     interrupt(): Promise<void>;
 }
-
-//#endregion
-
-//#region 路径图
-
-export interface IPathGraphEdge {
-    /** 本条边对应的移动方向 */
-    readonly dir: FaceDirection;
-    /** 边指向的节点索引，值为 y * width + x */
-    readonly to: number;
-}
-
-export interface IPathGraphNode {
-    /** 节点索引，值为 y * width + x */
-    readonly index: number;
-    /** 节点横坐标 */
-    readonly x: number;
-    /** 节点纵坐标 */
-    readonly y: number;
-    /** 节点对应的位置信息 */
-    readonly block: ILayerLocation;
-    /** 进入该节点的损失，构建图时由损失函数计算 */
-    readonly cost: number;
-    /** 该节点是否仅可作为路径终点，不可作为中间节点 */
-    readonly terminal: boolean;
-    /** 该节点的全部出边 */
-    readonly edges: readonly IPathGraphEdge[];
-}
-
-export interface IPathGraph {
-    /** 图宽度 */
-    readonly width: number;
-    /** 图高度 */
-    readonly height: number;
-    /** 图内全部节点，键为节点索引 */
-    readonly nodes: ReadonlyMap<number, IPathGraphNode>;
-}
-
-export interface IPathfindingGraphBuilder {
-    /**
-     * 绑定地图状态对象，用于解析图层所属楼层 id
-     * @param maps 地图状态对象
-     */
-    useMapState(maps: IMapState | null): void;
-
-    /**
-     * 绑定构建有向图所用的地图图层
-     * @param layer 地图图层对象
-     */
-    useMapLayer(layer: IMapLayer | null): void;
-
-    /**
-     * 设置构建图时使用的损失函数，未注入时每格损失 1
-     * @param cost 损失函数
-     */
-    useCostFunction(cost: PathCostFunction | null): void;
-
-    /**
-     * 注入判定边可行性的通行性谓词
-     * @param predicate 通行性谓词
-     */
-    usePassPredicate(predicate: IPassPredicate | null): void;
-
-    /**
-     * 设置邻域使用的方向组
-     * @param group 朝向组
-     */
-    useDirGroup(group: number): void;
-
-    /**
-     * 以起始位置为中心构建有向图：沿可通行有向边 BFS 扩展，
-     * 仅包含从起始位置可达的节点。图层未绑定或起始位置越界时告警并返回空图
-     * @param start BFS 起始位置
-     */
-    build(start: ITileLocator): IPathGraph;
-}
-
-//#endregion