docs/自营业务/数据采集页面设计.md

数据采集页面设计

把采集首页和任务详情改成能直接看懂的进度界面：正在做什么、总量多少、完成多少、还剩多少、预计还要多久、结果是否已经可用。 历史尝试、配置和诊断按需展开，不再让用户从多段文字和两张宽表中寻找答案。

2026-10-13 用户已确认本文方案及配套交互示意，并明确交由开发总控 01a12feb-0474-77f1-afe0-a3b491733dca 安排开发。方案维护对话只维护文档，不修改业务代码；图形示意不是实时任务监控，方案确认也不等于正式页面视觉验收。采集范围、统计口径、发布条件和账号保护继续以一期方案为准，查询性能按优化方案验收。

从这条任务暴露的问题

用户关注任务为 LXCOL-20261013-FC1699DFFB6E4EC7，截图显示 US01、2026-10-12 的出库销量采集。本仓状态为“等待数据准备”，详情却显示来源任务 LXCOL-20261013-0D70D251A9C5488F 正在获取详情，已处理 339 / 2,787 单。两种状态可以同时成立：来源数据还在准备，本仓尚未开始归并。

上述数量只代表截图时刻的来源阶段，不能当成此刻实时进度、US01 单量、SKU 销量或整个同步的完成比例。按截图口径剩余 2,448 单，阶段百分比为 12.1%；展示沿用服务端统一舍入口径。

当前问题	用户需要看到的解释	设计处理
首页只写等待，关键列被截断	后台到底有没有在干活	首屏聚焦当前关注任务，同时展示已确认关联的来源进度
本仓执行 0 次，来源却正在执行	两段状态是什么关系	用“来源准备 → 本仓归并 → 统计计算 → 结果发布”阶段流串起来，范围分别标注
详情重复任务号并铺满文字	总量、已完成、剩余在哪里	标题保留一次完整任务号；主体用数字摘要、阶段进度图和一句状态解释
“完成时间暂无法预计”长期不变	大概要等多久	增加基于可靠检查点的速度与当前阶段剩余时间；不具备条件时解释具体原因
空执行历史占大块区域，仍展示恢复表单	是否有需要我处理的事	历史默认收起；无尝试显示一行摘要；不可恢复时不铺表单
页面更新时间看起来很新，但数量未动	是页面在刷新，还是任务在推进	区分状态读取时间、进度推进时间和执行心跳

源码核对结论与边界

当前前端已有阶段计数、尝试信息、共享来源和结果状态，不需要另起一个监控系统。但后端 currentTasks 按最新创建任务选取，不保证它正在执行；详情上游依据直接关联，概览另有时间窗口关联。调度占位任务还可能没有自己的执行尝试。因此，改版必须补齐“当前实际执行”和“本任务等待对象”的语义，不能只改变文字或给现有最新记录套进度条。

源码入口为 CollectionView、CollectionQueryService、CollectionReadMapper 和 SelfopProgressProjection。这些是只读源码结论，不证明截图任务最新运行情况或部署状态。

首页：先看正在发生什么

2026-10-13 单账号首屏收敛（优先于下方原方案）

用户在最新截图中明确：只有一个领星账号，首页只关心账号正在做什么、完成／剩余多少、预计本阶段多久结束及后续处理。首屏改为账号运行看板，直接使用账号活动与各仓实际活动摘要，不受历史任务号或仓库筛选影响；不能把停止的历史记录作为主进度。布局按配套原型重构为运行看板，配色使用现有 Admin 白色卡片与蓝紫色强调，保留环形进度、三项数量、预计时间和阶段流程；待机时显示最近发布结果与各仓可用状态，不把待机画成100%完成。

按用户最新要求，采集页移除仓库筛选、任务定位、配置、历史详情、诊断与恢复表单，只读一个账号概览接口；旧链接中的仓库和任务号不改变账号首屏。后续阶段用流程说明展示，不宣称已确定执行顺序；待处理只列服务端已返回的活动摘要（每仓每类型有上限），不能将其数量冒充全账号剩余任务总数。没有完整队列与总任务ETA契约时如实说明，继续展示可靠的当前阶段剩余量和阶段ETA。

保留“自营业务 → 数据采集”和现有页面路由，按以下顺序组织。沿用 Admin 高密度规范，使用连续白底区域、轻分隔和紧凑间距，不为每个字段单独放一张大卡片。

1. 查询栏： 仓库、采集内容、任务号定位、查询／刷新；北京时间作为统一辅助说明。任务号支持完整粘贴。选择仓库后定位该仓任务，错误仓库返回明确提示，不自动跨权限搜索。
2. 当前关注任务： 一行完整任务号、仓库、采集内容和数据日期；下面是阶段流、当前阶段数量、等待原因、预计剩余时间和最近推进时间。普通用户无需先打开详情就能理解进展。
3. 各仓数据可用情况： 紧凑表展示仓库＋采集内容、当前活动、最近可用数据、覆盖／新鲜度。出库与产品库存各自独立，库存已发布不代表销量已完成。
4. 任务记录： 保留分页、筛选和历史详情。初始展示较少行，把视觉重点留给当前任务；历史列表不能代替实时运行概览。

首屏焦点默认采用服务端明确的实际活动／阻塞任务，不将“最新创建”冒充“正在执行”。同仓有多个关联任务时给出数量和可切换入口，切换后持续关注所选任务，不被刷新自动换掉。手动选择历史记录时标明“查看历史任务”，保留返回当前活动入口。

任务号定位同步到现有路由查询参数 warehouseCode,taskNo，读取已有受权限约束的任务详情；不要求用户先翻到该任务所在页。轮询不重置历史分页，不丢弃手动选择。任务不存在、无权访问、首次读取失败、暂无任务分别呈现。

历史记录压缩为六列

顺序	列	呈现方式
1	操作	“查看详情”；需要固定时固定左侧，不统一写“详情／恢复”
2	任务／范围	完整任务号允许两行；辅助行放仓库、出库／库存、正式／验证用途
3	数据时间段	显示明确日期区间，精确起止时间进入详情；统一北京时间，结束边界不歧义
4	当前阶段与进度	阶段标签＋简短计数；等待来源时标注来源范围，不塞完整解释段落
5	最近进展	推进时间及多久前；没有执行尝试时显示未开始本仓执行，不能用读取时间填充
6	执行／发布结果	如“等待来源 · 未发布”“已完成 · 已发布”“本次失败 · 旧数据可用”

完整技术字段、重试资格、尝试历史和诊断从详情查看，不继续横向增加列。按 1920×1080、100% 缩放及展开侧栏验收：关键状态与进度不依赖横向滚动，任务号不只剩无法区分的前缀，长内容自然换行，不缩小字号硬塞。

详情：图形进度在上，诊断记录在下

继续使用已确认的 1200px 居中 AppDialog，保留全屏与关闭；不新增抽屉或独立详情页。弹框标题只出现一次完整业务任务号，内容分为三层。

第一层：数量、进度与时间

顶部显示“US01 · 出库销量 · 2026-10-12”和简短状态。当前正在等待来源时，主状态为“等待来源数据”，其下突出“关联来源正在获取出库详情”，避免一个大大的“未开始”盖过真实活动。

主体左侧为当前阶段的环形进度图，右侧为一组数字和时间摘要，共用一个区域：

位置	本次截图对应的呈现	规则
图形标题	来源详情采集 · 账号共享	图形旁持续显示范围，不能只放在提示浮层中
中心数字	12.1% · 当前阶段	只有可靠分母才能画确定比例；不叫“同步总进度”
数量摘要	总数 2,787 单／已完成 339 单／剩余 2,448 单	同一计数范围、阶段和基准；“单”不是 SKU 件数
时间摘要	任务累计耗时（含排队与重试）；最近处理速度；预计本阶段还需多久	累计耗时使用 Task.elapsedSeconds，从 createdAt 起算，活动任务截止读取时间，终态截止任务最后更新时间；不受 attempt 或阶段切换影响，缺失显示 —；当前阶段 ETA 与任务累计耗时分别标注
提示	本仓尚未归并；来源完成后继续计算与发布	一句话解释下一步，不复述整段技术规则

未知总量显示“已完成 N 单／总量待确认”（库存按实际单位），使用不表达百分比的阶段状态图，不画 0% 或假转动的确定进度。零量仅表示数量，状态继续取服务端证据：如“0 单，正在核验”或“0 单，结果已发布”；库存显示对应页／行单位，不由 total=0 推断正在校验或已经完成。异常计数或总量变化时撤去比例，说明正在复核。

进度图只表达当前阶段。按 2026-10-13 用户确认，与自营业务其他图表统一使用 ECharts＋vue-echarts 的 Canvas 配置，通过 AnalyticsChart.vue 复用；当前阶段环图使用无指针、无刻度的环形进度配置。未知、零分母及异常计数只显示空环，不填入虚假百分比。状态同时使用文字和图形，不只靠红绿颜色区分。

第二层：阶段流与结果可用性

出库流程画为五个节点：来源目录 → 来源详情 → 更新本仓出库数据 → 统计计算 → 结果发布。前两个节点标“账号共享”，后三个标“本仓”。完成节点用勾、当前节点用突出色、阻塞节点用原因、未开始节点用灰色；只有服务器确认适用时显示“复用完成／无需此步骤”。不能把完成两个节点直接换算为整体 40%。

节点完成必须有对应任务、尝试／轮次及切片的服务端完成证据，不能因当前进入后一个阶段就自动勾选之前全部节点。重复扫描、恢复或多切片时标明当前适用范围；缺少阶段历史证据显示“状态未确认”，不补造完成时间或完成结论。

产品库存采用自己的流程：本仓库存分页 → 完整性校验 → 统计计算 → 结果发布。展示页数、读取行数和去重业务键时分别标单位；库存行数不能冒充 SKU 数。

阶段流下方只保留两条业务说明：

• 本次结果： 未发布／已发布／沿用已有结果／失败。来源完成或详情 100% 不等于本仓报表更新。
• 当前报表： 正在使用哪次已发布数据、销量连续覆盖到哪天、库存观测时间。首次没有结果时显示尚无可用数据；已有旧版则继续展示其真实时效。

多日首采另显示目标日期范围和已发布覆盖／缺口摘要，目标从服务端读取。当前 TEST 最近 30 个完整日和生产首次最近 2 个月不得写成同一个固定标签；单个 12 日任务完成也不代表近 10／30 天可售天数观察窗口已经齐全。

第三层：按需查看与处理

“执行记录（N 次）”“校验与诊断”按需展开。配置只保留必要摘要，完整配置继续从原页面入口使用只读 AppDialog 查看，不在详情里另造配置区或叠开弹框。没有本仓尝试时只占一行：“本仓尚未开始执行；来源准备进度见上方”，不显示空表、空分页器。来源任务号与其尝试信息独立展示，不混进本仓尝试次数。

失败、长时间无推进或账号保护生效时，将简短原因提到上方；完整错误码、历史检查点和请求用量留在诊断区。质量尚未计算时摘要写“待校验”，不在多个区块重复长解释。可恢复任务且具备独立写权限时，才展示原有原因填写、核对与恢复操作；等待来源、正常运行或会话终止时不展示不可使用的表单。

恢复仍沿已有 POST /sync-tasks 的 RETRY、原任务号和幂等键，受服务端 allowedActions/actionBlockReason 控制。受理后只提示已排队，不能提示同步成功；页面不增加绕过账号暂停、会话截止或预算的“强制继续”。

预计时间：先给可靠的阶段估算

用户需要大概同步时间，因此把速度与预计剩余时间纳入本次设计，不无限期留一句“无法预计”。先交付当前可计量阶段的剩余时间；整个任务还需归并、计算、发布时明确说明。完整同步 ETA 只有所有剩余阶段均有可信工作量或校准过的历史耗时模型后才开放，不能把当前阶段 ETA 改个标题当总 ETA。

计算由服务端产生，页面只显示，不按页面轮询次数、请求次数或截图里的“339 单／78 秒”推算。78 秒可能是尝试耗时，且已完成数量可能包含检查点复用，两者并非同一个测速口径。

计算条件与公式

• 采样来自已提交的进度检查点。使用同一来源任务、尝试、阶段、扫描轮次、范围、单位和计数基准；分母已确认且在采样窗口内稳定，执行健康正常。
• 建议初始参数：最近不超过 3 分钟的有界样本，至少跨度 60 秒、至少 3 次真实推进。阈值集中配置，并用实际采集验证；这是实现建议，不是当前已测得的领星吞吐能力。
• 处理速度 = 窗口内新增实际处理完成量 / 窗口实际经过秒数；正常运行期间没有推进的间隔也计入耗时，不能只统计快的请求。完成总数允许包含复用对象，但测速增量独立排除复用；窗口内新识别的历史复用也不能抬高速度。实现可保留可靠的实际处理增量，无法区分时遇到复用跳变重新建立基线，暂不估算。
• 同身份且完成数不变的保存不重置样本，也不计为有效推进；复用导致完成数增加仍重新采样。本次执行至少积累60秒、3次实际推进后估算，累计完成比例不能作为本次测速的样本量。有效期为最多30秒，为10秒轮询留出请求时间，仍受最近推进、执行健康及180秒采样窗口约束；选取在有效期内不会移出窗口的采样起点，避免窗口滚动造成短暂失效。
• 估算使用同一份进度身份、完成数、分母和时点。采样窗口截止到本次估算时刻，最后一次检查点后正常等待的时间也计入分母，补充的只读端点不伪造新推进。不能将旧估算与新 completed／total 混合返回；页面按身份和有效期整体接收或丢弃。
• 本阶段预计剩余秒数 = (可靠总量 - 已完成量) / 处理速度。速度必须大于零、剩余量非负；以“约 N 分钟”向上取整展示，小于一分钟显示“约 1 分钟内”，不显示精确到秒的完成承诺。
• 阶段切换、尝试重开、轮次变化、分母变化或冷却后恢复均重建测速窗口。建议样本按 10 秒桶合并、最多保留 20 个端点，ETA 持久采样数据不超过 1 KiB，并与已有阶段记录合计遵守进度 JSON 8 KiB 上限。优先保留业务检查点及审计摘要；接近上限时压缩／丢弃 ETA 样本并返回暂不可估算，不能让估算附加数据导致采集提交失败。不为 ETA 扫描全部订单或引入独立时序平台。

情况	预计时间区域
正常推进且样本充分	“当前阶段预计还需约 N 分钟”，同时显示最近处理速度与估算更新时间
刚启动／恢复后样本不足	“正在测速”，照常显示已有完成量
总量未确定／正在变化	“总量待确认，暂不估算”
明确限流冷却	“限流暂停；最早恢复时刻……；恢复后重新估算”，不把冷却结束当完成时刻
预算耗尽／人工暂停／失败／健康待确认	“已暂停估算”＋具体原因，不保留看似继续倒计时的旧 ETA
超过配置的无推进期限	保留最后真实计数，显示“近期无新增进度，暂不估算”；心跳正常不等于有处理速度
页面读取失败／估算已过期	标记最后观测时间，撤去活动倒计时，显示更新失败或估算已过期
本阶段结束但后续阶段未知	“本阶段已完成；正在归并／计算／发布”，不显示整个同步还剩 0 分钟

服务端返回 ETA 适用阶段、有效期及不可估算原因。全任务 ETA 留作后续校准能力，不阻塞本轮数量、阶段图、测速和阶段预计时间交付；不以提高领星请求并发来让预计时间变短。

任务关联、等待与活动状态合同

继续扩展现有运行查询 DTO，不新增平行的监控 API，不改采集任务身份。以下为需补齐的语义；已有等价字段优先复用，开发总控确认最终 DTO 命名并同步 OpenAPI、直接调用方和契约测试。

数据组	已有基础	必须补齐或明确的语义
关注任务与实际执行	currentTask,latestAttempt,taskNo	显式区分最新逻辑任务与活动执行；无本仓 run 是合法状态。不能依赖创建时间推断活动任务
依赖与阻塞	sharedUpstream、直接上游关联、概览窗口关联	建议返回 dependencyState,blockingReason,progressSourceTaskNo；服务端确认关联后才标“为本任务准备”。窗口相交只表示相关候选，不能证明直接依赖；多个实际依赖以有界摘要呈现
阶段计数	progressScope,countBasis,attemptNo,phase,scanRound,completed,total,totalKnown,unit,sliceFrom,sliceUntil	数量保留范围、来源和分母依据；本仓无投影不能借账号总数填充。本仓页可展示共享进度，但标题必须标账号共享
状态时钟	observedAt,progressUpdatedAt,heartbeatAt,executionHealth	读取时间、最后提交推进时间、执行心跳分别返回；终态尝试冻结可靠摘要时间。当前终态读取 summaryAsOf 而标准冻结路径未写此值，需补实际快照证据，不用查询时刻伪装
等待与保护	nextRetryAt,accountCooldownUntil,accountPauseReason 和预算摘要	等待原因与不能重试原因分开；区分来源未齐、排队、冷却、会话截止、预算耗尽。前端不靠本地时钟自行判失败或宣布已恢复
速度与预计时间	现有可靠计数和阶段时间	建议有界 stageEstimate：状态、progressIdentity（来源任务、尝试、阶段、轮次、范围、单位、基准）、所依据的 completed／total，以及 sampleFrom,sampleUntil,completedDelta,ratePerSecond,remainingSeconds,estimatedAt,validUntil,unavailableReason；completedDelta 仅指实际处理增量。估算和进度依据一致才返回数值，有效期同时受状态观测及无推进期限约束
结果与覆盖	resultPublicationState,lastPublishedAt,initialCoverageStatus 等	本次结果和目前报表可用结果独立；来源 ROUTED、预算 YIELDED、目录完整不能当成本仓发布

依赖不明确时，展示“本任务等待来源；关联进度尚未确认”。如服务端确有其他账号活动，可以另外显示“账号正在执行其他采集”，不能挂在这条任务下面冒充它的完成量。actionBlockReason 是操作资格，不能直接当成执行等待原因。

共享采集可能服务两个仓库，在全部仓库视图按来源任务号去重展示一次；本仓任务不重复累加共享数量或尝试次数。数据范围与权限由服务端核验，不暴露来源密钥、内部数据库 ID 或原始订单载荷。

状态刷新与查询成本

页面可见且有本仓活动、来源活动、等待来源或待执行任务时，沿用每 10 秒刷新运行元数据；没有活动时每 60 秒刷新。来源仍在推进时，不因本仓执行次数为零降为闲置。切页或浏览器隐藏停止，恢复可见立即读取。

只保留一个轮询调度器：概览和所关注任务读取有界摘要；任务详情展开时复用同一任务数据，历史尝试分页按需获取，不为每一行各开请求，也不每 10 秒反复拉不变的历史页。仓库切换、任务切换、旧尝试迟到响应均进行取消／身份校验，不覆盖新选择。

轮询失败保留最后成功读到的数量和时间，提示“状态更新失败”，不把运行状态改成失败。无新推进且心跳正常显示“执行中，最近一次推进在……”，是否超时或失联由服务端判定。页面刷新成功不更新任务推进时间；只有下一次服务端健康与保护状态确认后，才撤销冷却／暂停提示。

运行查询只读 scope、task、run 与有界投影，不扫描订单、商品明细、统计全表或完整 manifest，不调用领星。阶段 ETA 也不增加外部请求。已有运行元数据 P95 ≤500 ms 的目标继续适用；后续与候选构建混合负载验证按性能方案安排，本轮不新增真实采集或压测。

逐操作设计与验收

视觉依据是本轮首页与任务详情两张用户截图及用户已确认的配套交互示意；现有承载以 模块操作矩阵为准。下表为已确认的改版设计，由开发者实施时更新该矩阵；本轮不把设计图写成已实现／已验收。

操作	承载与关键验收
打开采集页	现有独立页面；首屏读到活动／等待对象、当前计数、最近推进和结果可用性
输入任务号	现有查询栏；可直接定位，不依赖历史首屏；当前关注区保留完整任务号和仓库
切换仓库／关注任务	原页更新；旧响应不串仓、不替换手动选择；共享数量不重复合计
查看任务详情	原 1200px AppDialog；首屏为数量摘要、阶段图、阶段预计时间和结果提示；全屏／关闭保留
查看历史／诊断	当前详情内折叠；空历史无表格和分页；失败原因在首层有短摘要
查看配置	复用原只读 AppDialog，不把查看变成修改配置
恢复任务	原详情内受权限与资格控制的确认流程；无资格不铺表单，不能绕过账号保护
跳转销量／库存	复用已有页面与仓库上下文；目标展示已发布版本，不把运行计数当销量

必测状态

1. 本次截图场景： 本仓未启动，已确认关联来源正处理 339 / 2,787 单。首页和详情均明确来源在工作，本仓等待；两个任务号、尝试次数和计数范围不混用。
2. 关联缺失： 账号有活动但无法证明属于该任务。明确待确认，不把无关进度贴过来；详情与概览采用同一关联语义。
3. 计数边界： 总量未知、零单、分母变化、分页轮次变化、对象复用、尝试重开。没有虚假百分比、剩余负数、重复完成数或从阶段序号算整体比例。
4. 预计时间： 样本未齐不估算，稳定采样可估算；窗口内外复用都不抬高速度；最后推进后的正常停顿计入窗口；阶段／尝试变化重置，旧估算不得配新数量，冷却和陈旧数据暂停估算，阶段 100% 不等于任务剩余 0。高频推进且历史阶段摘要接近 8 KiB 时，样本仍有界、可降级，采集提交不受 ETA 影响。
5. 更新故障： HTTP 失败、旧响应迟到、心跳过期、心跳正常但无推进。最后观测值保留，任务不被浏览器误判失败；来源活动下保持活动轮询。
6. 发布与覆盖： 来源完成但本仓计算中、本次失败但旧版可用、首次无版本、单日已发布但 10／30 日窗口不足、库存独立发布。所有结论均与实际覆盖一致。
7. 权限与布局： 只读账号可看详情但不可恢复；无资格任务无恢复表单；1920×1080／100% 截图核对首页、普通详情、全屏详情、长任务号和错误状态，关键内容不靠横向滚动或极小字号查看。

前端状态用受控样本和组件验证，后端关联、计数、ETA 和权限用合同测试；不为验收设计扩大真实领星采集。源码检查、接口验证和人工截图分别交付，缺少人工截图时保留“待人工视觉确认”。

交给开发总控的建议顺序

顺序	工作包	交付判断
1	统一活动任务、等待依赖与计数范围	服务端能解释这条任务在等谁；概览和详情一致；未确认关联如实显示
2	首页与现有详情改版	先用已有可靠计数呈现阶段图、大数字和结果状态，收起历史及无效操作；不等待复杂总 ETA 才改善可读性
3	阶段速度与预计时间	补有界采样和服务端估算合同；所有不可估算状态有具体解释，页面显示约数
4	联合验收	跑上述状态矩阵、元数据查询检查和人工截图，核对两仓／出库／库存；已通过项目不无故重复

用户已授权开发总控将本设计纳入开发安排，由总控协调现有模块写入者、共享接口与执行顺序；方案维护对话不改业务代码，不另建监控服务、任务表、调度系统或用户可见对话。代码、部署和正式验收进度继续只维护在工程主契约；本次设计交接不扩大环境操作授权。

页面阶段名称 MERGE 显示“更新本仓出库数据”：将已校验的来源出库单按所属仓库写入或更新本地出库数据，再计算销量；不表示库存合并。库存流程独立为获取产品库存、完整性校验、统计计算、结果发布。