frontend-miniapp/docs/superpowers/plans/2026-07-10-explain-multi-page-flow.md

# 讲解流独立页面拆分 Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 将讲解流从单页 `stage` 状态机拆分为展厅列表页、业务单元列表页、讲解点列表页三个真实路由页面，使嵌入小程序时标题与返回都跟随页面层级工作。

**Architecture:** 保留现有 `explainUseCase` / repository 数据边界，页面层拆开但组件层短期继续复用 `ExplainHallSelect.vue`。`pages/explain/list.vue` 收敛为展厅列表页，新增 `business-unit-list.vue` 与 `guide-stop-list.vue` 分别承载业务单元和讲解点，详情页继续沿用 `pages/exhibit/detail.vue`。

**Tech Stack:** uni-app、Vue 3 `<script setup>`、TypeScript、SCSS、现有 explain use case/repository/view-model 层

## Global Constraints

- 嵌入小程序时，宿主标题和返回行为与页面层级一致。
- 普通 H5 中现有讲解流视觉风格和交互尽量保持不变。
- 继续复用当前 explain use case / repository 数据边界，不引入新的页面直接数据耦合。
- 讲解点进入 `pages/exhibit/detail` 的既有详情能力保持可用。
- 不重做讲解详情页的数据模型或播放器架构。
- 不改造 explain 数据来源边界。
- 不新增小程序宿主桥接协议。
- 不重构 `ExplainHallSelect.vue` 为多个纯展示组件，除非实现时为降低复杂度必须做最小拆分。
- 标题规则固定为：展厅列表页 `讲解`，业务单元列表页 `当前展厅名`，讲解点列表页 `当前业务单元名`。
- 返回链路固定为：讲解点列表 → 业务单元列表 → 展厅列表 → 讲解首页/入口页。
- 当前项目没有独立 `test` 脚本，验证以 `pnpm type-check`、`pnpm lint`、`pnpm build:h5` 和 H5 手工回归为准。

---

### Task 1: 收敛讲解首页入口，改为展厅列表独立页跳转

**Files:**
- Modify: `src/pages/index/index.vue`
- Modify: `src/pages/explain/list.vue`
- Test: `src/pages/index/index.vue`（手工回归入口）

**Interfaces:**
- Consumes:
  - `explainUseCase.loadExplainHalls(): Promise<MuseumHall[]>`
  - `explainUseCase.loadExplainHallSummaries(hallIds: string[]): Promise<Record<string, ExplainHallSummary>>`
  - `navigateToGuideTopTab(tab: GuideTopTab): void`
- Produces:
  - 首页讲解 Tab 点击展厅时调用 `uni.navigateTo({ url: '/pages/explain/list' })` 或直接在独立页内部继续流转
  - `src/pages/explain/list.vue` 仅暴露展厅列表行为，不再承担 `unit` / `stop` 状态切换

- [ ] **Step 1: 阅读并锁定当前讲解入口代码**

阅读以下代码块并记录要删除或迁移的行为：

```ts
// src/pages/index/index.vue
const explainHallItems = ref<ExplainHallSelectItem[]>([])
const explainBusinessUnits = ref<ExplainBusinessUnit[]>([])
const explainStage = ref<ExplainSelectStage>('hall')
const selectedExplainHallId = ref('')
const selectedExplainBusinessUnitId = ref('')
```

重点确认：
- `ExplainHallSelect` 在首页 explain Tab 中被直接渲染
- `handleExplainHallClick / handleExplainBusinessUnitClick / handleExplainGuideStopClick / handleExplainBack` 仍由首页维护

- [ ] **Step 2: 先写实现后验证“首页 explain Tab 点击展厅跳独立页”的手工检查点**

将以下检查点写进任务注释或临时核对清单，不写入生产代码：

```text
入口回归预期：
1. 首页切到讲解 Tab，仍能看到展厅列表
2. 点击任一展厅，不再在首页内部切到业务单元 stage
3. 而是跳转到 /pages/explain/business-unit-list
```

- [ ] **Step 3: 将首页 explain Tab 的点击行为改为页面跳转**

把首页 explain 逻辑从“内部 stage 切换”改为“跳到独立页”。保留 explain Tab 首屏展厅列表展示，但去掉首页中业务单元和讲解点的状态推进逻辑。实现目标示意：

```ts
const handleExplainHallClick = async (hallId: string) => {
  const hall = explainHallItems.value.find((item) => item.id === hallId)
  const params = new URLSearchParams({
    hallId,
    hallName: hall?.name || '讲解'
  })

  uni.navigateTo({
    url: `/pages/explain/business-unit-list?${params.toString()}`
  })
}
```

同时移除首页中对以下逻辑的业务依赖：

```ts
explainStage.value = 'unit'
selectedExplainBusinessUnitId.value = ''
selectedExplainBusinessUnitName.value = ''
```

并把 `handleExplainBusinessUnitClick` / `handleExplainBack` 调整为不再驱动首页内部多级状态。

- [ ] **Step 4: 收敛 `pages/explain/list.vue` 为展厅列表页**

删除 `src/pages/explain/list.vue` 中仅为单页多阶段服务的逻辑，目标代码形态示意：

```ts
const explainHallItems = ref<ExplainHallSelectItem[]>([])
const explainLoading = ref(false)
const explainError = ref('')

const handleExplainHallClick = (hallId: string) => {
  const hall = explainHallItems.value.find((item) => item.id === hallId)
  const params = new URLSearchParams({
    hallId,
    hallName: hall?.name || '讲解'
  })

  uni.navigateTo({
    url: `/pages/explain/business-unit-list?${params.toString()}`
  })
}
```

模板里只保留：

```vue
<ExplainHallSelect
  :halls="explainHallItems"
  stage="hall"
  :loading="explainLoading"
  :error="explainError"
  @hall-click="handleExplainHallClick"
  @back="handleBack"
/>
```

移除 `business-units`、`guide-stops`、`selected-*`、`history.pushState/popstate` 相关逻辑。

- [ ] **Step 5: 运行类型检查验证页面收敛没有破坏现有引用**

Run: `pnpm type-check`
Expected: exit 0，`pages/index/index.vue` 与 `pages/explain/list.vue` 不再报 `ExplainSelectStage` / `selectedExplainBusinessUnit` 等已删除字段错误

- [ ] **Step 6: 提交**

```bash
git add src/pages/index/index.vue src/pages/explain/list.vue
git commit -m "refactor: split explain hall entry from home tab"
```

### Task 2: 新增业务单元列表页并接管展厅级标题与返回

**Files:**
- Create: `src/pages/explain/business-unit-list.vue`
- Modify: `src/pages.json`
- Test: `src/pages/explain/business-unit-list.vue`

**Interfaces:**
- Consumes:
  - `explainUseCase.loadTemporaryBusinessUnitsByHall(hallId: string): Promise<ExplainBusinessUnit[]>`
  - `ExplainHallSelect.vue` 的 `stage="unit"` 展示模式
- Produces:
  - 新页面路由：`/pages/explain/business-unit-list?hallId=<id>&hallName=<name>`
  - 页面级标题设置函数：`syncPageTitle(title: string): void`
  - 页面级返回：`goBackToExplainHallList(): void`

- [ ] **Step 1: 在 `pages.json` 注册新页面**

新增页面配置：

```json
{
  "path": "pages/explain/business-unit-list",
  "style": {
    "navigationBarTitleText": "业务单元",
    "navigationBarBackgroundColor": "#FFFFFF",
    "navigationStyle": "custom"
  }
}
```

插入位置紧跟 `pages/explain/list`，保持 explain 路由集中。

- [ ] **Step 2: 创建业务单元页骨架并先放失败态/空态兜底**

创建 `src/pages/explain/business-unit-list.vue`，先写最小骨架：

```vue
<template>
  <GuidePageFrame
    active-tab="explain"
    variant="static"
    :show-top-tabs="false"
    show-back
    @tab-change="handleTopTabChange"
    @back="handleBack"
  >
    <view class="explain-business-unit-page">
      <ExplainHallSelect
        :business-units="explainBusinessUnitItems"
        stage="unit"
        :selected-hall-name="selectedExplainHallName"
        :loading="explainLoading"
        :error="explainError"
        @business-unit-click="handleExplainBusinessUnitClick"
        @back="handleBack"
      />
    </view>
  </GuidePageFrame>
</template>
```

- [ ] **Step 3: 实现参数解析、标题同步与数据加载**

在脚本中实现以下最小接口：

```ts
const selectedExplainHallId = ref('')
const selectedExplainHallName = ref('')
const explainBusinessUnits = ref<ExplainBusinessUnit[]>([])
const explainLoading = ref(false)
const explainError = ref('')

const explainBusinessUnitItems = computed<ExplainBusinessUnitSelectItem[]>(() => (
  explainBusinessUnits.value.map((unit) => ({
    id: unit.id,
    name: unit.name,
    hallId: unit.hallId,
    previewImageUrl: unit.previewImageUrl,
    guideStopCount: unit.guideStopCount
  }))
))

const syncPageTitle = (title: string) => {
  uni.setNavigationBarTitle({ title })
  if (typeof document !== 'undefined') document.title = title
}
```

`onLoad` 内实现：

```ts
onLoad(async (options: any = {}) => {
  const hallId = Array.isArray(options.hallId) ? options.hallId[0] : options.hallId
  const hallName = Array.isArray(options.hallName) ? options.hallName[0] : options.hallName

  selectedExplainHallId.value = hallId || ''
  selectedExplainHallName.value = hallName || '业务单元'
  syncPageTitle(selectedExplainHallName.value)

  if (!selectedExplainHallId.value) {
    explainError.value = '缺少展厅参数，请返回讲解列表后重试'
    return
  }

  explainLoading.value = true
  try {
    explainBusinessUnits.value = await explainUseCase.loadTemporaryBusinessUnitsByHall(selectedExplainHallId.value)
  } catch (error) {
    explainError.value = '展厅讲解点加载失败，请稍后重试'
  } finally {
    explainLoading.value = false
  }
})
```

- [ ] **Step 4: 实现业务单元点击和页面级返回**

```ts
const handleExplainBusinessUnitClick = (unitId: string) => {
  const unit = explainBusinessUnits.value.find((item) => item.id === unitId)
  const params = new URLSearchParams({
    hallId: selectedExplainHallId.value,
    hallName: selectedExplainHallName.value,
    unitId,
    unitName: unit?.name || '讲解点'
  })

  uni.navigateTo({
    url: `/pages/explain/guide-stop-list?${params.toString()}`
  })
}

const goBackToExplainHallList = () => {
  uni.redirectTo({
    url: '/pages/explain/list',
    fail: () => {
      uni.reLaunch({ url: '/pages/explain/list' })
    }
  })
}

const handleBack = () => {
  uni.navigateBack({
    delta: 1,
    fail: goBackToExplainHallList
  })
}
```

- [ ] **Step 5: 运行 lint 验证新页面与 pages.json 兼容**

Run: `pnpm lint`
Expected: exit 0，`business-unit-list.vue` 没有未使用导入、`pages.json` 对应引用未触发脚本错误

- [ ] **Step 6: 提交**

```bash
git add src/pages.json src/pages/explain/business-unit-list.vue
git commit -m "feat: add explain business unit page"
```

### Task 3: 新增讲解点列表页并接管业务单元级标题与返回

**Files:**
- Create: `src/pages/explain/guide-stop-list.vue`
- Modify: `src/pages.json`
- Test: `src/pages/explain/guide-stop-list.vue`

**Interfaces:**
- Consumes:
  - `explainUseCase.selectBusinessUnit(hallId: string, unitId: string): Promise<ExplainBusinessUnit | null>`
  - `normalizeExplainDetailTargetFromGuideStop({ id: string }): ExplainDetailTarget`
  - `ExplainHallSelect.vue` 的 `stage="stop"` 展示模式
- Produces:
  - 新页面路由：`/pages/explain/guide-stop-list?hallId=<id>&hallName=<name>&unitId=<id>&unitName=<name>`
  - 点击讲解点后进入 `pages/exhibit/detail`
  - 页面级返回：`goBackToBusinessUnitList(): void`

- [ ] **Step 1: 在 `pages.json` 注册讲解点列表页**

新增页面配置：

```json
{
  "path": "pages/explain/guide-stop-list",
  "style": {
    "navigationBarTitleText": "讲解点",
    "navigationBarBackgroundColor": "#FFFFFF",
    "navigationStyle": "custom"
  }
}
```

- [ ] **Step 2: 创建讲解点页骨架**

```vue
<template>
  <GuidePageFrame
    active-tab="explain"
    variant="static"
    :show-top-tabs="false"
    show-back
    @tab-change="handleTopTabChange"
    @back="handleBack"
  >
    <view class="explain-guide-stop-page">
      <ExplainHallSelect
        :guide-stops="explainGuideStopItems"
        stage="stop"
        :selected-business-unit-name="selectedExplainBusinessUnitName"
        :loading="explainLoading"
        :error="explainError"
        @guide-stop-click="handleExplainGuideStopClick"
        @back="handleBack"
      />
    </view>
  </GuidePageFrame>
</template>
```

- [ ] **Step 3: 实现参数解析、标题同步与业务单元恢复**

```ts
const selectedExplainHallId = ref('')
const selectedExplainHallName = ref('')
const selectedExplainBusinessUnitId = ref('')
const selectedExplainBusinessUnitName = ref('')
const explainGuideStopItems = ref<ExplainGuideStopSelectItem[]>([])
const explainLoading = ref(false)
const explainError = ref('')

const toGuideStopItems = (unit: ExplainBusinessUnit): ExplainGuideStopSelectItem[] => (
  unit.stops.map((stop) => ({
    id: stop.id,
    name: stop.name,
    hallId: stop.hallId,
    hallName: stop.hallName,
    floorId: stop.floorId,
    poiId: stop.poiId,
    mapX: stop.mapX,
    mapY: stop.mapY,
    coverImageUrl: stop.coverImageUrl,
    description: stop.description,
    hasAudio: stop.hasAudio,
    audioStatus: stop.audioStatus,
    guideLevel: stop.guideLevel,
    playTargetType: stop.playTargetType,
    playTargetId: stop.playTargetId
  }))
)
```

`onLoad` 中：

```ts
onLoad(async (options: any = {}) => {
  selectedExplainHallId.value = Array.isArray(options.hallId) ? options.hallId[0] : options.hallId || ''
  selectedExplainHallName.value = Array.isArray(options.hallName) ? options.hallName[0] : options.hallName || ''
  selectedExplainBusinessUnitId.value = Array.isArray(options.unitId) ? options.unitId[0] : options.unitId || ''
  selectedExplainBusinessUnitName.value = Array.isArray(options.unitName) ? options.unitName[0] : options.unitName || '讲解点'

  syncPageTitle(selectedExplainBusinessUnitName.value)

  if (!selectedExplainHallId.value || !selectedExplainBusinessUnitId.value) {
    explainError.value = '缺少业务单元参数，请返回上一级后重试'
    return
  }

  explainLoading.value = true
  try {
    const unit = await explainUseCase.selectBusinessUnit(
      selectedExplainHallId.value,
      selectedExplainBusinessUnitId.value
    )
    if (!unit) {
      explainError.value = '未找到对应业务单元，请返回上一级后重试'
      return
    }
    selectedExplainBusinessUnitName.value = unit.name || selectedExplainBusinessUnitName.value
    syncPageTitle(selectedExplainBusinessUnitName.value)
    explainGuideStopItems.value = toGuideStopItems(unit)
  } catch (error) {
    explainError.value = '讲解点加载失败，请稍后重试'
  } finally {
    explainLoading.value = false
  }
})
```

- [ ] **Step 4: 实现讲解点跳详情和业务单元页回退**

```ts
const handleExplainGuideStopClick = (stop: ExplainGuideStopSelectItem) => {
  const target = stop.playTargetType && stop.playTargetId
    ? { targetType: stop.playTargetType, targetId: stop.playTargetId }
    : normalizeExplainDetailTargetFromGuideStop({ id: stop.id })

  const params = new URLSearchParams({
    id: stop.id,
    tab: 'explain',
    targetType: target.targetType,
    targetId: target.targetId
  })

  uni.navigateTo({
    url: `/pages/exhibit/detail?${params.toString()}`
  })
}

const goBackToBusinessUnitList = () => {
  const params = new URLSearchParams({
    hallId: selectedExplainHallId.value,
    hallName: selectedExplainHallName.value
  })

  uni.redirectTo({
    url: `/pages/explain/business-unit-list?${params.toString()}`,
    fail: () => {
      uni.reLaunch({ url: `/pages/explain/business-unit-list?${params.toString()}` })
    }
  })
}

const handleBack = () => {
  uni.navigateBack({
    delta: 1,
    fail: goBackToBusinessUnitList
  })
}
```

- [ ] **Step 5: 运行类型检查确认 explain 详情入参链路未被破坏**

Run: `pnpm type-check`
Expected: exit 0，`guide-stop-list.vue` 到 `pages/exhibit/detail` 的 `targetType/targetId` 参数类型与详情页现有解析逻辑兼容

- [ ] **Step 6: 提交**

```bash
git add src/pages.json src/pages/explain/guide-stop-list.vue
git commit -m "feat: add explain guide stop page"
```

### Task 4: 收敛 ExplainHallSelect 组件为“页面驱动、单模式复用”

**Files:**
- Modify: `src/components/explain/ExplainHallSelect.vue`
- Test: `src/components/explain/ExplainHallSelect.vue`

**Interfaces:**
- Consumes:
  - 父页面传入的 `stage: 'hall' | 'unit' | 'stop'`
  - 父页面传入的 `selectedHallName?: string`
  - 父页面传入的 `selectedBusinessUnitName?: string`
- Produces:
  - 保持 `hallClick(hallId: string)`
  - 保持 `businessUnitClick(unitId: string)`
  - 保持 `guideStopClick(stop: ExplainGuideStopSelectItem)`
  - 保持 `back()`

- [ ] **Step 1: 阅读组件中仅服务单页状态机的逻辑**

检查以下内容是否仍有必要：

```ts
const shouldUseHostNavigation = computed(() => isEmbeddedInWechatMiniProgram())
const headerTitle = computed(() => {
  if (props.stage === 'unit') return props.selectedHallName || '选择业务单元'
  if (props.stage === 'stop') return props.selectedBusinessUnitName || '选择讲解点'
  return '讲解'
})
```

判断原则：页面已拆开后，组件内部标题不再是宿主标题来源，只是普通 H5 自绘页头文案。

- [ ] **Step 2: 删除不再需要的宿主导航分支和单页补丁依赖**

如果页面层已经承接宿主标题与返回，则组件只保留纯展示逻辑。最小目标是让组件不再承担“宿主导航是否可用”的页面级责任。目标代码形态：

```ts
const headerTitle = computed(() => {
  if (props.stage === 'unit') return props.selectedHallName || '业务单元'
  if (props.stage === 'stop') return props.selectedBusinessUnitName || '讲解点'
  return '讲解'
})
```

如确认嵌入小程序场景仍需隐藏自绘页头，可保留 `shouldUseHostNavigation`，但不要再让组件承担页面级 history/title 逻辑。

- [ ] **Step 3: 确认三种模式在拆页后都能独立渲染**

核对模板三块：

```vue
v-if="stage === 'hall'"
v-else-if="stage === 'unit'"
v-else-if="stage === 'stop'"
```

确保：
- hall 模式不依赖 `businessUnits`
- unit 模式不依赖 `guideStops`
- stop 模式不依赖首页 explain 旧状态

- [ ] **Step 4: 运行 lint 保证组件收敛后无未使用代码**

Run: `pnpm lint`
Expected: exit 0，`ExplainHallSelect.vue` 无未使用 import / computed / props 分支

- [ ] **Step 5: 提交**

```bash
git add src/components/explain/ExplainHallSelect.vue
git commit -m "refactor: narrow explain hall select responsibilities"
```

### Task 5: 清理旧的单页讲解状态逻辑并完成全链路回归

**Files:**
- Modify: `src/pages/explain/list.vue`
- Modify: `src/pages/index/index.vue`
- Modify: `src/pages/exhibit/detail.vue`（仅当详情返回链路需要最小调整）
- Test: `src/pages/explain/list.vue`
- Test: `src/pages/explain/business-unit-list.vue`
- Test: `src/pages/explain/guide-stop-list.vue`
- Test: `src/pages/exhibit/detail.vue`

**Interfaces:**
- Consumes:
  - 新页面路由 `/pages/explain/business-unit-list`
  - 新页面路由 `/pages/explain/guide-stop-list`
  - 现有详情页 `handleBack()` / `buildDetailRoute()` 逻辑
- Produces:
  - 不再存在依赖 `explainStage` 的宿主标题 / history patch
  - 完整回归链路：展厅列表 → 业务单元 → 讲解点 → 详情 → 返回

- [ ] **Step 1: 删除 `pages/explain/list.vue` 中旧的单页 history 补丁**

删除以下类型逻辑：

```ts
type ExplainHistoryState = { ... }
window.history.pushState(...)
window.history.replaceState(...)
window.addEventListener('popstate', ...)
```

因为页面拆分后它们不再是正确抽象。

- [ ] **Step 2: 删除首页中旧的 explain 多阶段状态字段**

从 `src/pages/index/index.vue` 删除或收敛以下字段：

```ts
const explainBusinessUnits = ref<ExplainBusinessUnit[]>([])
const explainStage = ref<ExplainSelectStage>('hall')
const selectedExplainHallId = ref('')
const selectedExplainBusinessUnitId = ref('')
const selectedExplainBusinessUnitName = ref('')
```

并同步删除只为这些字段服务的 computed / handlers。

- [ ] **Step 3: 最小检查详情返回是否还需要补充来源兜底**

检查 `src/pages/exhibit/detail.vue` 当前逻辑：

```ts
const handleBack = () => {
  if (typeof window !== 'undefined' && window.history.length > 1) {
    window.history.back()
    ...
    return
  }

  uni.navigateBack({
    delta: 1,
    fail: fallbackToExplainHome
  })
}
```

如果从新讲解点页进入详情后，`navigateBack()` 已能自然回到讲解点列表，则不改代码；如果仍会误回首页，再补最小来源参数（例如 `from=guide-stop-list` 与返回兜底路由），但禁止顺手改动播放器或详情正文逻辑。

- [ ] **Step 4: 运行完整静态验证**

Run: `pnpm type-check`
Expected: exit 0

Run: `pnpm lint`
Expected: exit 0

Run: `pnpm build:h5`
Expected: build complete，允许保留项目既有 Sass / 字体告警，但不得有新的 explain 路由构建错误

- [ ] **Step 5: 执行 H5 手工回归**

按以下顺序人工验证：

```text
1. 首页进入讲解 Tab，展厅列表正常显示
2. 点击展厅，进入业务单元列表页，标题为当前展厅名
3. 点击业务单元，进入讲解点列表页，标题为当前业务单元名
4. 点击讲解点，进入讲解详情页
5. 页面返回：详情 -> 讲解点列表 -> 业务单元列表 -> 展厅列表 -> 讲解首页/入口页
6. 直接打开业务单元列表页缺少 hallId 时显示错误态并可返回
7. 直接打开讲解点列表页缺少 hallId/unitId 时显示错误态并可返回
```

记录结果到提交说明或任务备注中，不写入生产代码。

- [ ] **Step 6: 提交**

```bash
git add src/pages/index/index.vue src/pages/explain/list.vue src/pages/exhibit/detail.vue src/components/explain/ExplainHallSelect.vue src/pages/explain/business-unit-list.vue src/pages/explain/guide-stop-list.vue src/pages.json
git commit -m "feat: split explain flow into dedicated pages"
```