aegon-lv97 1.0.0

package/gen-ai/build-report/report-domain.ts

@@ -0,0 +1,1133 @@
+/**
+ * build-report 輔助模塊（業務域 + 路由/滾動基礎設施）
+ *
+ * 1. 章節標題（接口原文）
+ * 2. 報告連貫性檢查 / 定稿記錄（session；無本地假定稿）
+ * 3. 報告歷史預覽與章節佈局
+ * 4. 報告歷史時間展示
+ * 5. 申請創建模板詳情
+ * 6. 報告編輯路由同步
+ * 7. 膠囊滾動條與視口高度
+ */
+
+import { computed, nextTick, onUnmounted, ref, watch } from 'vue'
+import type { RouteLocationNormalizedLoaded, Router } from 'vue-router'
+import { resolveReportTemplateById, type ReportTemplateCard } from './report-template-data'
+import type {
+  PromptChapterForm,
+  PromptRightPanel,
+  ReportModelStep,
+} from './useReportWorkflow'
+
+// =============================================================================
+// 1. 章節標題（以接口原文為準，不做本地 i18n 詞典映射）
+// =============================================================================
+
+export type ChapterContentLanguage = 'zh-Hant' | 'zh-Hans'
+
+export const CHAPTER_CONTENT_LANGUAGE_OPTIONS = [
+  { value: 'zh-Hans', label: '簡體中文' },
+  { value: 'zh-Hant', label: '繁體中文' },
+] as const
+
+export function stripChapterNumberPrefix(title: string) {
+  return title.trim().replace(/^\d+\.\s*/, '')
+}
+
+export function shouldShowChapterLanguageSelect(reportLanguage: string) {
+  return reportLanguage === 'zh-Hant' || reportLanguage === 'zh-Hans'
+}
+
+export function resolveEffectiveChapterLocale(
+  _reportLanguage: string,
+  contentLanguage: ChapterContentLanguage
+): 'zh-Hant' | 'zh-Hans' {
+  return contentLanguage
+}
+
+/** 直接返回接口/來源標題（去序號前綴），不再查本地 mock 詞典 */
+export function translateChapterLabel(
+  label: string,
+  _reportLanguage?: string,
+  _contentLanguage?: ChapterContentLanguage
+) {
+  return stripChapterNumberPrefix(label)
+}
+
+export function translateChapterTitle(
+  title: string,
+  _reportLanguage?: string,
+  _contentLanguage?: ChapterContentLanguage
+) {
+  return title.trim()
+}
+
+export function translateChapterTitles(
+  chapters: string[],
+  _reportLanguage?: string,
+  _contentLanguage?: ChapterContentLanguage
+) {
+  return chapters.map((title, index) => {
+    const trimmed = title.trim()
+    if (/^\d+\./.test(trimmed)) return trimmed
+    return `${index + 1}. ${stripChapterNumberPrefix(trimmed)}`
+  })
+}
+
+export function translateUnavailableVersionLabel(
+  _reportLanguage?: string,
+  _contentLanguage?: ChapterContentLanguage
+) {
+  return '無可用版本'
+}
+
+// =============================================================================
+// 2. 報告連貫性檢查 / 定稿記錄（report-coherence-check）
+// =============================================================================
+
+export interface ReportChapterSelectionItem {
+  label: string
+  version: string
+  generator?: string
+}
+
+export interface ReportGenerationSignature {
+  templateId: string
+  chapters: ReportChapterSelectionItem[]
+  reportLanguage: string
+  chapterContentLanguage: ChapterContentLanguage
+}
+
+export interface FinalizedReportRecord {
+  id: string
+  displayTitle: string
+  templateId: string
+  chapters: ReportChapterSelectionItem[]
+  reportLanguage: string
+  chapterContentLanguage: ChapterContentLanguage
+  sourceFileIds: string[]
+  finalizedAt: string
+}
+
+export interface CoherenceCheckSessionPayload {
+  templateId: string
+  reportName: string
+  year: string
+  chapters: ReportChapterSelectionItem[]
+  chapterContentLanguage: ChapterContentLanguage
+  reportLanguage: string
+  /** 接口：實例 / 版本（可選，深鏈時可能沒有） */
+  instanceId?: string
+  versionIdList?: string[]
+  /** 接口返回的連貫性檢查正文 */
+  coherenceCheckContentText?: string
+  beenFinalizedFlag?: string
+}
+
+export const COHERENCE_CHECK_SESSION_KEY = 'gen-ai-report-coherence-check-payload'
+const COHERENCE_CHECKED_SIGNATURES_KEY = 'gen-ai-coherence-checked-signatures'
+const GENERATED_REPORTS_SESSION_KEY = 'gen-ai-generated-report-records'
+
+const REPORT_LANGUAGE_LABELS: Record<string, string> = {
+  'zh-Hant': '繁體中文',
+  'zh-Hans': '簡體中文',
+  en: 'English',
+}
+
+function loadGeneratedReportsFromSession(): FinalizedReportRecord[] {
+  const raw = sessionStorage.getItem(GENERATED_REPORTS_SESSION_KEY)
+  if (!raw) return []
+  try {
+    return JSON.parse(raw) as FinalizedReportRecord[]
+  } catch {
+    return []
+  }
+}
+
+function saveGeneratedReportsToSession(records: FinalizedReportRecord[]) {
+  sessionStorage.setItem(GENERATED_REPORTS_SESSION_KEY, JSON.stringify(records))
+}
+
+function loadAllFinalizedReports(): FinalizedReportRecord[] {
+  // 僅 session 中用戶生成的記錄；不再混入本地假定稿
+  return loadGeneratedReportsFromSession()
+}
+
+export function serializeGenerationSignature(signature: ReportGenerationSignature) {
+  return JSON.stringify({
+    templateId: signature.templateId,
+    chapters: signature.chapters,
+    reportLanguage: signature.reportLanguage,
+    chapterContentLanguage: signature.chapterContentLanguage,
+  })
+}
+
+export function buildGenerationSignature(
+  templateId: string,
+  chapters: ReportChapterSelectionItem[],
+  reportLanguage: string,
+  chapterContentLanguage: ChapterContentLanguage
+): ReportGenerationSignature {
+  return {
+    templateId,
+    chapters,
+    reportLanguage,
+    chapterContentLanguage,
+  }
+}
+
+export function findFinalizedReportById(recordId: string): FinalizedReportRecord | null {
+  return loadAllFinalizedReports().find((record) => record.id === recordId) ?? null
+}
+
+export function findFinalizedReportBySignature(
+  signature: ReportGenerationSignature
+): FinalizedReportRecord | null {
+  const target = serializeGenerationSignature(signature)
+  return (
+    loadAllFinalizedReports().find((record) => serializeGenerationSignature(record) === target) ??
+    null
+  )
+}
+
+/** @deprecated use findFinalizedReportBySignature */
+export function findFinalizedReportBySelection(
+  templateId: string,
+  selection: ReportChapterSelectionItem[]
+) {
+  return findFinalizedReportBySignature(
+    buildGenerationSignature(templateId, selection, 'zh-Hant', 'zh-Hant')
+  )
+}
+
+function loadCoherenceCheckedSignatures(): string[] {
+  const raw = sessionStorage.getItem(COHERENCE_CHECKED_SIGNATURES_KEY)
+  if (!raw) return []
+  try {
+    return JSON.parse(raw) as string[]
+  } catch {
+    return []
+  }
+}
+
+function saveCoherenceCheckedSignatures(signatures: string[]) {
+  sessionStorage.setItem(COHERENCE_CHECKED_SIGNATURES_KEY, JSON.stringify(signatures))
+}
+
+export function isCoherenceCheckCompleted(signature: ReportGenerationSignature) {
+  const key = serializeGenerationSignature(signature)
+  return loadCoherenceCheckedSignatures().includes(key)
+}
+
+export function markCoherenceCheckCompleted(signature: ReportGenerationSignature) {
+  const key = serializeGenerationSignature(signature)
+  const stored = loadCoherenceCheckedSignatures()
+  if (stored.includes(key)) return
+  saveCoherenceCheckedSignatures([...stored, key])
+}
+
+export function getReportLanguageLabel(reportLanguage: string) {
+  return REPORT_LANGUAGE_LABELS[reportLanguage] ?? '繁體中文'
+}
+
+function getNextReportVersionLabel(templateId: string) {
+  const count = loadAllFinalizedReports().filter(
+    (record) => record.templateId === templateId
+  ).length
+  return `v${count + 1}`
+}
+
+export function buildGeneratedReportDisplayTitle(
+  reportName: string,
+  year: string,
+  reportLanguage: string,
+  templateId: string
+) {
+  const name = reportName.trim() || '未命名報告'
+  const versionLabel = getNextReportVersionLabel(templateId)
+  const languageLabel = getReportLanguageLabel(reportLanguage)
+  return `${name} ${year} ${versionLabel} ${languageLabel}`
+}
+
+export function registerGeneratedReport(
+  signature: ReportGenerationSignature,
+  reportName: string,
+  year: string,
+  sourceFileIds: string[]
+): FinalizedReportRecord {
+  const displayTitle = buildGeneratedReportDisplayTitle(
+    reportName,
+    year,
+    signature.reportLanguage,
+    signature.templateId
+  )
+  const record: FinalizedReportRecord = {
+    id: `generated-${Date.now()}`,
+    displayTitle,
+    sourceFileIds,
+    finalizedAt: new Date().toISOString(),
+    ...signature,
+  }
+  const nextRecords = [record, ...loadGeneratedReportsFromSession()]
+  saveGeneratedReportsToSession(nextRecords)
+  return record
+}
+
+export function saveCoherenceCheckSession(payload: CoherenceCheckSessionPayload) {
+  sessionStorage.setItem(COHERENCE_CHECK_SESSION_KEY, JSON.stringify(payload))
+}
+
+export function loadCoherenceCheckSession(): CoherenceCheckSessionPayload | null {
+  const raw = sessionStorage.getItem(COHERENCE_CHECK_SESSION_KEY)
+  if (!raw) return null
+  try {
+    const parsed = JSON.parse(raw) as CoherenceCheckSessionPayload & { reportLanguage?: string }
+    return { ...parsed, reportLanguage: parsed.reportLanguage ?? 'zh-Hant' }
+  } catch {
+    return null
+  }
+}
+
+/** 深鏈 / 無 session 時：僅按 templateId 從已解析模板組裝章節列表（無本地假定稿正文） */
+export function buildCoherenceCheckPayloadFromTemplateId(
+  templateId: string
+): CoherenceCheckSessionPayload | null {
+  const id = templateId.trim()
+  if (!id) return null
+
+  const template = resolveReportTemplateById(id)
+  const chapters: ReportChapterSelectionItem[] = (template?.chapters ?? []).map((label) => ({
+    label: stripChapterNumberPrefix(label),
+    version: '',
+  }))
+
+  if (!chapters.length) return null
+
+  return {
+    templateId: id,
+    reportName: template?.name ?? '未命名報告',
+    year: String(new Date().getFullYear()),
+    chapters,
+    chapterContentLanguage: 'zh-Hant',
+    reportLanguage: 'zh-Hant',
+  }
+}
+
+export function openReportCoherenceCheck(router: Router, payload: CoherenceCheckSessionPayload) {
+  saveCoherenceCheckSession(payload)
+  markCoherenceCheckCompleted(
+    buildGenerationSignature(
+      payload.templateId,
+      payload.chapters,
+      payload.reportLanguage,
+      payload.chapterContentLanguage
+    )
+  )
+  openCoherenceCheckResultPage(router, payload.templateId)
+}
+
+export function openReportCoherenceCheckResult(
+  router: Router,
+  payload: CoherenceCheckSessionPayload
+) {
+  saveCoherenceCheckSession(payload)
+  openCoherenceCheckResultPage(router, payload.templateId)
+}
+
+function openCoherenceCheckResultPage(router: Router, templateId: string) {
+  void router.push({
+    name: 'report-coherence-check' as const,
+    query: { templateId },
+  })
+}
+
+// =============================================================================
+// 3. 報告歷史預覽與章節佈局（report-history-preview）
+// =============================================================================
+
+export function buildReportHistoryChapterBodies(record: FinalizedReportRecord): string[] {
+  // 歷史正文以接口 / AdjustInstance 為準；本地定稿記錄無正文時返回空串
+  return record.chapters.map(() => '')
+}
+
+export function serializeSelectedChapterLabels(chapters: ReportChapterSelectionItem[]) {
+  return JSON.stringify(chapters.map((chapter) => chapter.label))
+}
+
+export function buildSelectedChapterLabels(
+  order: string[],
+  selected: Record<string, boolean>,
+  presets: Array<{ key: string; label: string }>,
+  isUnavailable: (label: string) => boolean
+) {
+  return order
+    .filter((key) => {
+      const preset = presets.find((item) => item.key === key)
+      return preset && selected[key] && !isUnavailable(preset.label)
+    })
+    .map((key) => presets.find((item) => item.key === key)!.label)
+}
+
+export function serializeChapterLayoutFromState(
+  order: string[],
+  selected: Record<string, boolean>,
+  presets: Array<{ key: string; label: string }>,
+  isUnavailable: (label: string) => boolean
+) {
+  return JSON.stringify(buildSelectedChapterLabels(order, selected, presets, isUnavailable))
+}
+
+export function buildChapterOrderForHistoryRecord(
+  templateChapterLabels: string[],
+  recordChapters: ReportChapterSelectionItem[],
+  isUnavailable: (label: string) => boolean
+) {
+  const presets = templateChapterLabels.map((title, index) => ({
+    key: `chapter-${index}`,
+    label: stripChapterNumberPrefix(title),
+  }))
+
+  const findPresetKey = (chapterLabel: string) =>
+    presets.find((preset) => preset.label === stripChapterNumberPrefix(chapterLabel))?.key
+  const findChapter = (presetLabel: string) =>
+    recordChapters.find(
+      (chapter) => stripChapterNumberPrefix(chapter.label) === stripChapterNumberPrefix(presetLabel)
+    )
+
+  const selectedKeys = recordChapters
+    .map((chapter) => findPresetKey(chapter.label))
+    .filter((key): key is string => !!key)
+
+  const remainingKeys = presets
+    .filter((preset) => !selectedKeys.includes(preset.key))
+    .map((preset) => preset.key)
+
+  return {
+    presets,
+    chapterOrder: [...selectedKeys, ...remainingKeys],
+    selectedChapters: Object.fromEntries(
+      presets.map((preset) => [
+        preset.key,
+        !!findChapter(preset.label) && !isUnavailable(preset.label),
+      ])
+    ),
+    chapterVersions: Object.fromEntries(
+      presets.map((preset) => {
+        const matched = findChapter(preset.label)
+        return [preset.key, matched?.version ?? 'V3']
+      })
+    ),
+  }
+}
+
+// =============================================================================
+// 4. Prompt 表單工具
+// =============================================================================
+
+export function clonePromptChapterForm(form: PromptChapterForm): PromptChapterForm {
+  return { ...form }
+}
+
+// =============================================================================
+// 5. 報告歷史時間展示（report-history-time）
+// =============================================================================
+
+const MINUTE_MS = 60 * 1000
+const HOUR_MS = 60 * MINUTE_MS
+const DAY_MS = 24 * HOUR_MS
+
+function pad2(value: number) {
+  return String(value).padStart(2, '0')
+}
+
+export function formatAbsoluteDateTime(date: Date) {
+  const year = date.getFullYear()
+  const month = pad2(date.getMonth() + 1)
+  const day = pad2(date.getDate())
+  const hours = pad2(date.getHours())
+  const minutes = pad2(date.getMinutes())
+  const seconds = pad2(date.getSeconds())
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`
+}
+
+/**
+ * 報告定稿時間展示：
+ * - 距當前 < 60 分鐘：X min 前
+ * - 距當前 < 24 小時：X h 前
+ * - 距當前 >= 24 小時：yyyy-mm-dd HH:MM:SS
+ */
+export function formatReportHistoryTime(
+  finalizedAt: string | number | Date,
+  now: Date | number = Date.now()
+) {
+  const finalized = finalizedAt instanceof Date ? finalizedAt : new Date(finalizedAt)
+  const nowMs = typeof now === 'number' ? now : now.getTime()
+  const finalizedMs = finalized.getTime()
+
+  if (Number.isNaN(finalizedMs)) return ''
+
+  const diffMs = Math.max(0, nowMs - finalizedMs)
+
+  if (diffMs < MINUTE_MS) {
+    return '1 min 前'
+  }
+
+  if (diffMs < HOUR_MS) {
+    const minutes = Math.floor(diffMs / MINUTE_MS)
+    return `${minutes} min 前`
+  }
+
+  if (diffMs < DAY_MS) {
+    const hours = Math.floor(diffMs / HOUR_MS)
+    return `${hours} h 前`
+  }
+
+  return formatAbsoluteDateTime(finalized)
+}
+
+export interface CoherenceCheckResultSection {
+  title: string
+  paragraphs: string[]
+}
+
+/** 將接口連貫性檢查正文拆成可展示段落（無 mock 文案） */
+export function parseCoherenceCheckContentText(contentText: string): CoherenceCheckResultSection[] {
+  const text = String(contentText ?? '').trim()
+  if (!text) return []
+
+  // 若接口已按段落分隔，保留為單節多段；否則整段展示
+  const paragraphs = text
+    .split(/\n{2,}/)
+    .map((p) => p.trim())
+    .filter(Boolean)
+  if (!paragraphs.length) return []
+
+  return [
+    {
+      title: '連貫性檢查結果',
+      paragraphs,
+    },
+  ]
+}
+
+// =============================================================================
+// 6. 申請創建模板詳情（apply-template-detail）
+// =============================================================================
+
+export interface ApplyTemplateApprovalRecord {
+  id: string
+  operator: string
+  status: string
+  completedAt: string
+  detail: string
+}
+
+export interface ApplyTemplateChapter {
+  id: string
+  title: string
+  description: string
+  prompt: string
+}
+
+export interface ApplyTemplateDetail {
+  sourceReport: string
+  language: string
+  title: string
+  description: string
+  chapters: ApplyTemplateChapter[]
+  approvalRecords: ApplyTemplateApprovalRecord[]
+}
+
+export type ApplyTemplateProcessAction = 'reject' | 'approve'
+
+export interface ApplyTemplateProcessPayload {
+  action: ApplyTemplateProcessAction
+  title: string
+  description: string
+  opinion: string
+}
+
+export function getApplyTemplateLanguageDisplay(language: string) {
+  return language === 'en' ? 'English[原模板所選語言]' : '中文[原模板所選語言]'
+}
+
+export function getApplyTemplateDisplayChapters(detail: ApplyTemplateDetail | null) {
+  if (!detail) return []
+  return detail.chapters.filter(
+    (chapter, index) => index < 2 || Boolean(chapter.prompt.trim() || chapter.description.trim())
+  )
+}
+
+export function buildApplyTemplateDetailFromReport(params: {
+  sourceReport: string
+  language: string
+  title: string
+  description: string
+  chapterTitles: string[]
+  chapterPrompt?: string
+  approvalRecords?: ApplyTemplateApprovalRecord[]
+}): ApplyTemplateDetail {
+  const chapters: ApplyTemplateChapter[] = params.chapterTitles.map((rawTitle, index) => {
+    const title = stripChapterNumberPrefix(rawTitle)
+    return {
+      id: `report-ch-${index}`,
+      title,
+      // 僅帶入當前報告已有數據；無則空（不填本地假描述 / Prompt）
+      description: '',
+      prompt:
+        index === 0 && params.chapterPrompt?.trim() ? params.chapterPrompt.trim() : '',
+    }
+  })
+
+  return {
+    sourceReport: params.sourceReport,
+    language: params.language,
+    title: params.title,
+    description: params.description,
+    chapters,
+    approvalRecords: params.approvalRecords ?? [],
+  }
+}
+
+// =============================================================================
+// 8. 報告編輯路由同步（report-edit-route）
+// =============================================================================
+
+export const BUILD_REPORT_PATH = '/gen-ai/build-report'
+export const REPORT_EDIT_PAGE_NAME = 'reportEdit'
+
+const VALID_STEPS = new Set<ReportModelStep>(['select', 'detail', 'generating', 'prompt'])
+
+export function isReportEditRoute(route: RouteLocationNormalizedLoaded) {
+  const pageName = route.query.pageName
+  if (pageName === REPORT_EDIT_PAGE_NAME) return true
+  if (Array.isArray(pageName) && pageName.includes(REPORT_EDIT_PAGE_NAME)) return true
+  // 遷移後可能拼接參數：路徑裡只要包含 reportEdit 即視為編輯流
+  return decodeURIComponent(route.fullPath).includes(REPORT_EDIT_PAGE_NAME)
+}
+
+/** 從路由字串解析步驟（支援 step 被拼接其他參數的情況） */
+export function matchReportModelStep(haystack: string): ReportModelStep {
+  const text = decodeURIComponent(String(haystack || '')).toLowerCase()
+  // 優先級：generating > prompt > detail > select（避免短詞誤傷；禁止 includes('select') 誤匹配）
+  if (text.includes('generating')) return 'generating'
+  if (text.includes('generate-settings')) return 'prompt'
+  if (/(?:^|[/?&#_=.-])prompt(?:$|[/?&#_=.-])/.test(text) || text.includes('step=prompt')) {
+    return 'prompt'
+  }
+  if (text.includes('prompt')) return 'prompt'
+  if (/(?:^|[/?&#_=.-])detail(?:$|[/?&#_=.-])/.test(text) || text.includes('step=detail')) {
+    return 'detail'
+  }
+  if (text.includes('detail')) return 'detail'
+  if (/(?:^|[/?&#_=.-])select(?:$|[/?&#_=.-])/.test(text) || text.includes('step=select')) {
+    return 'select'
+  }
+  return 'select'
+}
+
+/** 清洗遷移後可能污染的 step 值（如 `generating&foo=1` / 雙編碼） */
+export function sanitizeReportEditStepValue(raw: unknown): ReportModelStep | null {
+  if (raw == null) return null
+  const text = decodeURIComponent(String(Array.isArray(raw) ? raw[0] : raw)).trim()
+  if (!text) return null
+  if (text === 'generate-settings') return 'prompt'
+  if (VALID_STEPS.has(text as ReportModelStep)) return text as ReportModelStep
+  // 拼接污染：取首個可識別步驟關鍵字
+  return matchReportModelStep(text)
+}
+
+export function parseReportEditStep(route: RouteLocationNormalizedLoaded): ReportModelStep | null {
+  if (!isReportEditRoute(route)) return null
+
+  const fromQuery = sanitizeReportEditStepValue(route.query.step)
+  if (fromQuery) return fromQuery
+
+  // 遷移兼容：path 段 /generating|/prompt|/detail
+  const path = decodeURIComponent(route.path).toLowerCase()
+  if (path.includes('/generating')) return 'generating'
+  if (path.includes('/prompt')) return 'prompt'
+  if (path.includes('/detail')) return 'detail'
+
+  return matchReportModelStep(route.fullPath)
+}
+
+export function parsePromptRightPanel(route: RouteLocationNormalizedLoaded): PromptRightPanel {
+  const stepRaw = String(route.query.step ?? '')
+  if (
+    stepRaw === 'generate-settings' ||
+    route.query.rightPanel === 'settings' ||
+    String(route.query.rightPanel ?? '').includes('settings')
+  ) {
+    return 'settings'
+  }
+  return 'prompt'
+}
+
+export function buildReportEditQuery(
+  step: ReportModelStep,
+  templateId?: string,
+  rightPanel?: PromptRightPanel,
+  instanceId?: string,
+  preserveQuery?: Record<string, unknown>
+) {
+  const query: Record<string, string> = {}
+
+  // 遷移兼容：保留其它業務 query，但強制覆蓋 pageName / step
+  if (preserveQuery) {
+    for (const [key, value] of Object.entries(preserveQuery)) {
+      if (key === 'pageName' || key === 'step' || key === 'rightPanel') continue
+      if (value == null) continue
+      const text = Array.isArray(value) ? value.find((v) => v != null) : value
+      if (text == null || text === '') continue
+      query[key] = String(text)
+    }
+  }
+
+  query.pageName = REPORT_EDIT_PAGE_NAME
+  query.step = step
+  if (templateId) query.templateId = templateId
+  // settings：寫入 rightPanel；prompt：故意不帶該參數，用於清掉遷移/設置頁殘留
+  if (step === 'prompt' && rightPanel === 'settings') {
+    query.rightPanel = 'settings'
+  }
+  if (step === 'generating' && instanceId) query.instanceId = instanceId
+  return query
+}
+
+export function navigateToReportEdit(
+  router: Router,
+  step: ReportModelStep = 'select',
+  templateId?: string,
+  replace = false,
+  rightPanel?: PromptRightPanel,
+  instanceId?: string
+) {
+  const currentQuery = router.currentRoute.value.query as Record<string, unknown>
+  const location = {
+    path: BUILD_REPORT_PATH,
+    query: buildReportEditQuery(step, templateId, rightPanel, instanceId, currentQuery),
+  }
+  return replace ? router.replace(location) : router.push(location)
+}
+
+export function exitReportEdit(router: Router) {
+  return router.replace({ path: BUILD_REPORT_PATH })
+}
+
+interface ReportEditRouteSyncActions {
+  restoreReportEditSession: () => void
+  openReportEdit: (step: ReportModelStep) => void
+  closeReportEdit: () => void
+  setSelectedTemplate: (template: ReportTemplateCard | null) => void
+  loadTemplateFromSession: () => void
+  showPromptSettingsPanel: () => void
+  showPromptEditorPanel: () => void
+  /** 導航鎖定期間跳過用路由覆寫 modelStep */
+  isReportEditNavLocked?: () => boolean
+}
+
+export function createReportEditRouteSyncActions(
+  workflow: ReturnType<typeof import('./useReportWorkflow').useReportWorkflow>
+): ReportEditRouteSyncActions {
+  return {
+    restoreReportEditSession: workflow.restoreReportEditSession,
+    openReportEdit: workflow.openReportEdit,
+    closeReportEdit: workflow.closeReportEdit,
+    setSelectedTemplate: workflow.setSelectedTemplate,
+    loadTemplateFromSession: workflow.loadTemplateFromSession,
+    showPromptSettingsPanel: workflow.showPromptSettingsPanel,
+    showPromptEditorPanel: workflow.showPromptEditorPanel,
+    isReportEditNavLocked: () => workflow.isReportEditNavLocked(),
+  }
+}
+
+export function syncWorkflowFromReportEditRoute(
+  route: RouteLocationNormalizedLoaded,
+  actions: ReportEditRouteSyncActions
+) {
+  // 刷新後先從 session 恢復 draft / 模板 / 正文 / 資訊源等
+  actions.restoreReportEditSession()
+
+  // 主動跳轉鎖定期：只恢復 session，不讓舊/中間態路由覆寫 modelStep
+  if (actions.isReportEditNavLocked?.()) return
+
+  const step = parseReportEditStep(route)
+  if (!step) {
+    actions.closeReportEdit()
+    return
+  }
+
+  actions.openReportEdit(step)
+
+  const rightPanel = parsePromptRightPanel(route)
+  if (step === 'prompt' && rightPanel === 'settings') {
+    actions.showPromptSettingsPanel()
+  } else if (step === 'prompt') {
+    actions.showPromptEditorPanel()
+  }
+
+  const templateId = route.query.templateId
+  if (typeof templateId === 'string' && templateId) {
+    const found = resolveReportTemplateById(templateId)
+    if (found) {
+      actions.setSelectedTemplate(found)
+      return
+    }
+  }
+
+  if (step === 'detail' || step === 'generating' || step === 'prompt') {
+    actions.loadTemplateFromSession()
+  }
+}
+
+// =============================================================================
+// 9. 膠囊滾動條與視口高度（scroll）
+// =============================================================================
+
+export const CAPSULE_SCROLL_CONTAINER_CLASS = 'capsule-scroll-container'
+
+export interface CapsuleScrollbarTheme {
+  thumbColor?: string
+  thumbHoverColor?: string
+  thumbActiveColor?: string
+  trackColor?: string
+  thumbWidthPx?: number
+  classPrefix?: string
+}
+
+export interface CapsuleScrollbarOptions extends CapsuleScrollbarTheme {
+  scrollEl: { value: HTMLElement | null }
+  anchorEl?: { value: HTMLElement | null }
+  active: { value: boolean }
+  gutterPx?: number
+  thumbWidthPx?: number
+  minThumbPx?: number
+  visibleRatio?: number
+  alwaysVisible?: boolean
+  autoHideAfterMs?: number
+  rightOffsetPx?: number
+}
+
+export interface CapsuleScrollbarBindings {
+  canScroll: { value: boolean }
+  shown: { value: boolean }
+  visible: { value: boolean }
+  rootStyle: { value: { [key: string]: string } }
+  thumbStyle: { value: { [key: string]: string } }
+  rootClass: string
+  thumbClass: string
+  onThumbMouseDown: (event: MouseEvent) => void
+  refresh: () => void
+  bind: () => void
+  unbind: () => void
+}
+
+const DEFAULT_CLASS_PREFIX = 'capsule-scrollbar'
+
+interface NativeHideSnapshot {
+  paddingRight: string
+  marginRight: string
+  width: string
+  boxSizing: string
+  scrollbarWidth: string
+  msOverflowStyle: string
+}
+
+export function markCapsuleScrollContainer(el: HTMLElement): () => void {
+  const computed = getComputedStyle(el)
+  const snapshot: NativeHideSnapshot = {
+    paddingRight: el.style.paddingRight,
+    marginRight: el.style.marginRight,
+    width: el.style.width,
+    boxSizing: el.style.boxSizing,
+    scrollbarWidth: el.style.scrollbarWidth,
+    msOverflowStyle:
+      (el.style as CSSStyleDeclaration & { msOverflowStyle?: string }).msOverflowStyle ?? '',
+  }
+
+  el.style.setProperty('--capsule-scroll-padding-right', computed.paddingRight)
+  el.classList.add(CAPSULE_SCROLL_CONTAINER_CLASS)
+  el.style.scrollbarWidth = 'none'
+  ;(el.style as CSSStyleDeclaration & { msOverflowStyle?: string }).msOverflowStyle = 'none'
+
+  return () => {
+    el.classList.remove(CAPSULE_SCROLL_CONTAINER_CLASS)
+    el.style.removeProperty('--capsule-scroll-padding-right')
+    el.style.paddingRight = snapshot.paddingRight
+    el.style.marginRight = snapshot.marginRight
+    el.style.width = snapshot.width
+    el.style.boxSizing = snapshot.boxSizing
+    el.style.scrollbarWidth = snapshot.scrollbarWidth
+    ;(el.style as CSSStyleDeclaration & { msOverflowStyle?: string }).msOverflowStyle =
+      snapshot.msOverflowStyle
+  }
+}
+
+export function useCapsuleScrollbar(options: CapsuleScrollbarOptions): CapsuleScrollbarBindings {
+  const thumbWidthPx = options.thumbWidthPx ?? 10
+  const gutterPx = options.gutterPx ?? thumbWidthPx
+  const minThumbPx = options.minThumbPx ?? 48
+  const visibleRatio = options.visibleRatio ?? 1
+  const rightOffsetPx = options.rightOffsetPx ?? 1
+  const autoHideAfterMs = options.autoHideAfterMs ?? 3000
+  const alwaysVisible = options.alwaysVisible ?? autoHideAfterMs <= 0
+  const classPrefix = options.classPrefix ?? DEFAULT_CLASS_PREFIX
+
+  const canScroll = ref(false)
+  const shown = ref(false)
+  const zoneTop = ref(0)
+  const zoneRight = ref(rightOffsetPx)
+  const zoneHeight = ref(0)
+  const thumbHeight = ref(minThumbPx)
+  const thumbOffset = ref(0)
+
+  const visible = computed(() => canScroll.value && (alwaysVisible || shown.value))
+
+  let resizeObserver: ResizeObserver | undefined
+  let thumbDragCleanup: (() => void) | undefined
+  let removeContainerMark: (() => void) | undefined
+  let hideTimer: number | undefined
+  let rafId = 0
+
+  const rootStyle = computed(() => ({
+    top: `${zoneTop.value + thumbOffset.value}px`,
+    right: `${zoneRight.value}px`,
+    width: `${gutterPx}px`,
+    height: `${Math.round(thumbHeight.value)}px`,
+  }))
+
+  const thumbStyle = computed(() => ({
+    width: `${thumbWidthPx}px`,
+    height: '100%',
+  }))
+
+  function clearHideTimer() {
+    if (hideTimer !== undefined) {
+      clearTimeout(hideTimer)
+      hideTimer = undefined
+    }
+  }
+
+  function scheduleHide() {
+    clearHideTimer()
+    if (alwaysVisible || autoHideAfterMs <= 0) return
+    hideTimer = window.setTimeout(() => {
+      shown.value = false
+      hideTimer = undefined
+    }, autoHideAfterMs)
+  }
+
+  function revealBar() {
+    if (!canScroll.value) return
+    shown.value = true
+    scheduleHide()
+  }
+
+  function refreshLayout() {
+    const scrollEl = options.scrollEl.value
+    const anchorEl = options.anchorEl?.value ?? scrollEl
+    if (!options.active.value || !scrollEl || !anchorEl) {
+      canScroll.value = false
+      shown.value = false
+      return
+    }
+
+    const { scrollTop, scrollHeight, clientHeight } = scrollEl
+    const scrollable = scrollHeight > clientHeight + 1
+    canScroll.value = scrollable
+    if (!scrollable) {
+      shown.value = false
+      return
+    }
+
+    const anchorRect = anchorEl.getBoundingClientRect()
+    const shrinkInset = (anchorRect.height * (1 - visibleRatio)) / 2
+
+    zoneTop.value = Math.round(anchorRect.top + shrinkInset)
+    zoneRight.value = rightOffsetPx
+    zoneHeight.value = Math.round(anchorRect.height * visibleRatio)
+
+    const trackH = zoneHeight.value
+    thumbHeight.value = Math.max(minThumbPx, (clientHeight / scrollHeight) * trackH)
+    const maxThumbTravel = Math.max(0, trackH - thumbHeight.value)
+    const scrollMax = scrollHeight - clientHeight
+    thumbOffset.value = scrollMax > 0 ? Math.round((scrollTop / scrollMax) * maxThumbTravel) : 0
+  }
+
+  function scheduleRefresh() {
+    cancelAnimationFrame(rafId)
+    rafId = requestAnimationFrame(refreshLayout)
+  }
+
+  function onScroll() {
+    revealBar()
+    scheduleRefresh()
+  }
+
+  function bind() {
+    unbind()
+    const scrollEl = options.scrollEl.value
+    if (!scrollEl) return
+
+    removeContainerMark = markCapsuleScrollContainer(scrollEl)
+    refreshLayout()
+    scrollEl.addEventListener('scroll', onScroll, { passive: true })
+    resizeObserver = new ResizeObserver(() => scheduleRefresh())
+    resizeObserver.observe(scrollEl)
+    if (options.anchorEl?.value) resizeObserver.observe(options.anchorEl.value)
+    window.addEventListener('resize', scheduleRefresh, { passive: true })
+  }
+
+  function unbind() {
+    cancelAnimationFrame(rafId)
+    clearHideTimer()
+    window.removeEventListener('resize', scheduleRefresh)
+    resizeObserver?.disconnect()
+    resizeObserver = undefined
+    thumbDragCleanup?.()
+    thumbDragCleanup = undefined
+    options.scrollEl.value?.removeEventListener('scroll', onScroll)
+    removeContainerMark?.()
+    removeContainerMark = undefined
+    canScroll.value = false
+    shown.value = false
+  }
+
+  function onThumbMouseDown(event: MouseEvent) {
+    const scrollEl = options.scrollEl.value
+    if (!scrollEl) return
+
+    event.preventDefault()
+    revealBar()
+    clearHideTimer()
+
+    const startY = event.clientY
+    const startScrollTop = scrollEl.scrollTop
+    const trackH = zoneHeight.value
+    const scrollMax = scrollEl.scrollHeight - scrollEl.clientHeight
+    const maxThumbTravel = Math.max(0, trackH - thumbHeight.value)
+
+    const onMove = (ev: MouseEvent) => {
+      if (maxThumbTravel <= 0 || scrollMax <= 0) return
+      scrollEl.scrollTop = startScrollTop + ((ev.clientY - startY) / maxThumbTravel) * scrollMax
+    }
+
+    const onUp = () => {
+      document.removeEventListener('mousemove', onMove)
+      document.removeEventListener('mouseup', onUp)
+      thumbDragCleanup = undefined
+      scheduleHide()
+    }
+
+    document.addEventListener('mousemove', onMove)
+    document.addEventListener('mouseup', onUp)
+    thumbDragCleanup = onUp
+  }
+
+  watch(
+    () => options.active.value,
+    (active) => {
+      if (active) {
+        void nextTick(() => {
+          bind()
+          void nextTick(refreshLayout)
+        })
+        return
+      }
+      unbind()
+    },
+    { immediate: true }
+  )
+
+  onUnmounted(unbind)
+
+  return {
+    canScroll,
+    shown,
+    visible,
+    rootStyle,
+    thumbStyle,
+    rootClass: classPrefix,
+    thumbClass: `${classPrefix}__thumb`,
+    onThumbMouseDown,
+    refresh: refreshLayout,
+    bind,
+    unbind,
+  }
+}
+
+export function lockDocumentScroll(): () => void {
+  const html = document.documentElement
+  const body = document.body
+  const prevHtml = html.style.overflow
+  const prevBody = body.style.overflow
+
+  html.style.overflow = 'hidden'
+  body.style.overflow = 'hidden'
+
+  return () => {
+    html.style.overflow = prevHtml
+    body.style.overflow = prevBody
+  }
+}
+
+export interface ViewportBodyHeightOptions {
+  subtract?: number
+  subtractSelector?: string
+  subtractRoot?: HTMLElement
+  listenResize?: boolean
+}
+
+export function getViewportHeight(): number {
+  return window.innerHeight
+}
+
+function resolveSubtract(el: HTMLElement, options?: ViewportBodyHeightOptions): number {
+  if (options?.subtract !== undefined) return options.subtract
+
+  if (options?.subtractSelector) {
+    const root = options.subtractRoot ?? el.parentElement ?? document.body
+    const node = root.querySelector(options.subtractSelector) as HTMLElement | null
+    if (node) return node.getBoundingClientRect().height
+  }
+
+  return 0
+}
+
+export function getViewportBodyHeight(
+  el: HTMLElement,
+  options?: ViewportBodyHeightOptions
+): number {
+  const subtract = resolveSubtract(el, options)
+  return Math.max(0, getViewportHeight() - subtract)
+}
+
+export function bindViewportBodyHeight(
+  el: HTMLElement,
+  options?: ViewportBodyHeightOptions
+): () => void {
+  const listenResize = options?.listenResize ?? true
+
+  const update = () => {
+    const height = getViewportBodyHeight(el, options)
+    el.style.height = `${height}px`
+    el.style.maxHeight = `${height}px`
+  }
+
+  update()
+
+  if (!listenResize) {
+    return () => {
+      el.style.height = ''
+      el.style.maxHeight = ''
+    }
+  }
+
+  window.addEventListener('resize', update)
+  return () => {
+    window.removeEventListener('resize', update)
+    el.style.height = ''
+    el.style.maxHeight = ''
+  }
+}