import type { Entity } from '../core';
import type { Interaction } from '../interaction';

/**
 * 路由
 *
 * 【架构定位】：
 *
 * 1. 它是连接 URL 与 Page（页面实例）的唯一桥梁。
 * 2. 它是构建复杂应用（如中后台系统、多页官网）的核心导航骨架。
 *
 * 【引擎实现指引】
 *
 * 1. 隔离策略：
 *    - 设计模式 (design) 下，渲染引擎必须使用 `Memory Router`（或重写 `history.pushState`），
 *      以防止用户在配置路由跳转时，导致整个设计器外壳发生灾难性的真刷新或沙盒逃逸。
 *    - 运行/预览模式 (runtime/preview) 下，引擎切换为原生的 `Browser Router`。
 * 2. 嵌套挂载：
 *    当遇到带有 `children` 的路由时，引擎会将其对应的 `pageId` 视为一个“父级布局骨架（Layout Skeleton）”。
 *    引擎在该骨架中必须寻找一个特殊的内置组件（如 `type: 'Outlet'` 或 `RouterView`），
 *    以作为子路由对应 `Page` 的挂载插槽。
 */
export interface Route extends Entity {
  /**
   * 路由路径
   *
   * 定义了匹配当前路由的 URL 片段。
   *
   * 支持静态路径（如 '/home'、'/dashboard'）和参数路径（如 '/user/:id'）。
   *
   * 在根数组中，通常包含一个 '/' 作为默认首页。
   */
  path: string;
  /**
   * 路由重定向
   *
   * 如果配置了此字段，当 URL 匹配到当前 path 时，引擎不渲染组件，
   * 而是立即执行 301/302 级别的重定向，跳转到目标 path。
   *
   * 常见于将根路径 '/' 重定向到具体的首页 '/home'。
   */
  redirect?: string;
  /**
   * 绑定的页面 ID
   *
   * 核心映射：当前路由命中时，引擎将去全局的 `Application.pages` 数组中
   * 查找对应的 Page 实例，并渲染该 Page 携带的庞大组件树。
   *
   * 注：如果这是一个纯粹的重定向路由 (redirect存在) 或父级空壳路由，此项可为空。
   */
  pageId?: string;
  /**
   * 子路由
   *
   * 构建复杂应用（如带侧边栏、顶部导航的后台框架）的核心。
   *
   * 架构规约：
   *
   * 如果此数组不为空，则当前路由的 `pageId` 对应的 Page，不再是一个终端页面，
   * 而是一个带有“插槽”的布局容器。它的内部组件树中必须包含一个 `type: 'Outlet'` 的组件，
   * 用于动态渲染其子孙 Route 所绑定的 Page。
   */
  children?: Route[];
  /**
   * 交互
   *
   * 路由级生命周期与拦截器
   *
   * 在进入或离开该路由时触发的高阶控制流。
   *
   * 引擎实现指引：
   * 1. 常用于“路由守卫 (Navigation Guards)”：例如在进入 '/admin' 前，
   *    执行一个校验 Token 的 Action，若校验失败，则执行一个 Redirect Action 踢回登录页。
   * 2. 常见事件如：`onEnter` (进入前), `onLeave` (离开前)。
   *
   * 如果当前路由无拦截逻辑，则必须为空数组 `[]`（而非 undefined）。
   */
  interactions: Interaction[];
}