# 星图市场导出范围设计 ## 背景 当前插件的 `导出CSV` 只导出当前页数据，并在星图默认列后追加两列： - `单视频看后搜率` - `个人视频看后搜率` 现阶段用户希望把导出范围扩展为可配置页数，而不是固定当前页。同时需要保留当前默认列导出逻辑，避免重新引入之前“全量扫描导致页面闪动、卡顿、排序异常”的问题。 ## 目标 - 支持导出范围配置，默认导出前 `5` 页。 - 支持以下范围选项： - `当前页` - `前5页` - `前10页` - `全部` - `自定义` - 保留当前 CSV 规则： - 先导出星图页面默认列 - 末尾追加两列插件字段 - 批量导出时真实翻页采集当前筛选结果页，不改变当前页面筛选条件来源。 - 保持当前“筛选/排序只作用当前页”的行为，不重新绑定多页扫描逻辑。 ## 非目标 - 不改为直接调用星图列表接口拉多页数据。 - 不让插件筛选或排序自动跨页生效。 - 不处理“导出后自动回到最初分页位置”的复杂恢复，首版只要求滚动位置恢复到单页采集前。 ## 交互设计 在插件工具栏中保留一个 `导出CSV` 按钮，同时新增导出范围控件。 ### 范围控件 - 默认值：`前5页` - 可选项： - `当前页` - `前5页` - `前10页` - `全部` - `自定义` - 选择 `自定义` 时，展示页数输入框 - 仅接受正整数 - 无效值时禁止导出并提示错误 ### 任务状态 - 导出开始后： - `导出CSV` 按钮禁用 - 筛选按钮、排序按钮、范围控件、自定义输入框一并禁用 - 按钮文案根据任务模式更新： - 当前页：`导出中...` - 前 N 页：`导出中 3/5 页...` - 全部：`导出中 第3页...` - 全部导出时额外显示轻提示： - `全部导出可能耗时较长，页面会自动翻页。` ### 失败反馈 - 任一页采集失败时直接终止 - 通过按钮附近状态文本或 `alert` 提示： - `第 N 页导出失败，请稍后重试` - 失败时不下载残缺 CSV ## 执行流程 ### 当前页导出 当前页模式沿用现有逻辑： 1. 等待当前页表格可读取 2. 自动滚动当前页一次，补齐懒加载字段 3. 读取当前页星图默认列 4. 合并插件两列 5. 生成 CSV 并下载 ### 多页导出 多页模式仅在导出任务中启用，不影响平时筛选和排序。 1. 读取导出范围配置 2. 初始化批量任务状态与结果聚合器 3. 对当前页执行： - 等待表格稳定 - 自动滚动当前页以采全默认列 - 读取当前页记录 - 以 `authorId` 合并入结果集 4. 判断是否达到目标页数 5. 若未完成，则点击下一页 6. 等待“页切换完成”信号 7. 重复步骤 3 到 6 8. 汇总所有记录，生成单个 CSV 下载 ### 全部导出停止条件 `全部` 模式从当前页开始向后翻页，直到任一条件成立： - 下一页按钮不可点击 - 当前页签名不再变化 - 页面无法继续翻页并达到超时阈值 ## 页切换判定 批量导出不能只依赖固定 `setTimeout`。翻页完成需要同时满足至少一个强信号： - 当前页作者 ID 集合发生变化 - 当前页首行作者 ID 变化 - 当前页活动分页按钮变化 - 下一页按钮状态变化 为避免误判，翻页流程需要： 1. 记录翻页前页签名 2. 点击下一页 3. 轮询直到签名变化或超时 4. 签名变化后再执行一次当前页表格稳定等待 ## 当前页采集策略 当前页导出已知存在懒加载问题：页面初加载时后半段行的默认列为空，滚动后才补齐。 因此无论当前页导出还是多页导出，每一页都必须执行： 1. 初次读取当前页快照并写入 store 2. 查找当前市场列表滚动容器 3. 逐步向下滚动直到该页底部 4. 每次滚动后等待 DOM 稳定，再采集一轮 5. 恢复滚动位置并再采集一轮 这一步只针对“当前已打开的页”，不跨页扫描。 ## 数据合并规则 ### 去重键 - 使用 `authorId` 去重 ### 字段合并 - 新页记录有值时，补充到已有记录 - 新页记录为空时，不覆盖已有非空值 - 插件两列沿用当前已有的合并规则 ### CSV 表头 - 先保留星图默认列顺序 - 再追加： - `单视频看后搜率` - `个人视频看后搜率` ## 错误处理 ### 单页失败 以下情况视为单页失败： - 找不到表格根节点 - 找不到下一页按钮但目标尚未完成 - 翻页后页签名未变化且超时 - 当前页采集过程中出现异常 处理方式： - 立即终止任务 - 恢复工具栏控件状态 - 显示页级错误信息 - 不触发下载 ### 用户干预 首版不额外提供取消按钮，但应防御以下情况： - 用户手动切换筛选 - 用户手动翻页 - 用户再次点击导出 处理方式： - 导出期间禁用插件控件 - 对关键节点重新校验表格和页签名 - 如环境已被破坏，终止任务并报错 ## 实现建议 建议按以下边界组织实现： ### `plugin-toolbar` - 新增导出范围选择器 - 新增自定义页数输入框 - 新增导出过程中的状态展示 ### `market/index` - 保留当前页导出逻辑作为单页模式 - 新增批量导出入口 - 管理任务状态、按钮禁用、进度回写 ### 新建批量导出控制器 建议新增类似 `export-range-controller.ts` 的模块，职责包括： - 读取当前页记录 - 控制翻页 - 等待页切换 - 聚合多页数据 - 统一返回最终 `MarketRecord[]` 这样可以避免把 `market/index.ts` 继续堆大。 ### `dom-sync` 或新辅助模块 - 提供读取当前页签名 - 提供定位下一页按钮 - 提供判断下一页是否可点击 ## 测试策略 ### 单元测试 - 默认导出范围为前 5 页 - 选择 `当前页` 时只导出一页 - 选择 `前10页` 时最多导出 10 页 - `自定义` 输入非法值时不启动导出 - `全部` 模式在没有下一页时停止 - 多页合并时按 `authorId` 去重 - 空字段不会覆盖已有非空字段 ### 集成测试 - 批量导出时会依次点击下一页 - 翻页后等待新页签名再采集 - 每一页在导出前都会执行滚动采集 - 中途某页失败时不生成 CSV - 导出期间工具栏控件被禁用 ## 风险 - 星图分页 DOM 结构可能不稳定，下一页按钮定位需要做降级兼容。 - 全部导出在高页数场景下耗时会较长。 - 页面中途刷新或筛选重算可能打断批量任务。 ## 推荐实施顺序 1. 工具栏新增范围选择与自定义输入 2. 抽出批量导出控制器 3. 实现前 N 页导出 4. 在前 N 页能力稳定后开放 `全部` 5. 补齐全部相关失败与超时测试 ## 决策结论 采用“一个导出按钮 + 范围选择器”的方案，默认导出前 `5` 页，支持 `全部` 和 `自定义`。批量模式通过真实翻页逐页采集当前筛选结果，不把多页扫描重新引入到筛选和排序链路中。