Files
crawler-plugin/docs/specs/16-client-task-console.md
T
huangzd1997 cd9bf509ec feat(taskcenter): 设备花名册与在线状态接口
新增 GET /api/admin/task-center/devices:任务设备(近 30 天)∪ 客户端日志设备
(近 7 天、uid 非空)合并去重,设备名取日志侧、最近任务时间取任务侧;在线 =
最近活动(任务 updated_at ∪ 日志上报)≤ 5 分钟,在线优先排序。`web-` 前缀标
webDevice 供前端标注「网页」。

SQL 侧把原来的 ROSTER_ROWS 拆成 TASK_DEVICE_ROWS + LOG_DEVICE_ROWS 再组合,
统计口径与列表共用同一段并集,避免两处漂移;新增按设备统计进行中任务数
(空设备号不归属任何设备)。overview 的 deviceTotal/deviceOnline 继续走
COUNT 查询(同一并集常量派生),不再从列表二次计算。

测试:Service 合并/在线阈值/空设备号/排序/网页标记 8 项,Mapper 动态 SQL 9 项。
2026-09-28 22:54:36 +08:00

11 KiB
Raw Blame History

16 客户端任务管理(后台看板)

模块职责

后台新增「客户端任务管理」页面,让管理员按账号 × 设备 × 业务统一查看客户端任务执行情况, 不必逐台设备排查;超管可看全部。管理员只能看本组(本人 + 本组用户 + 自己管理的成员)。

覆盖页面:

  • 客户端任务管理:task-center/board(两个页签:「客户端任务」「变体采集」)

需求约束(用户明确):

  • 默认只有超管可见;管理员需超管在「用户管理 → 菜单权限」授权后可见 —— 复用现有菜单授权机制 (columns + user_column_permission),不新建权限机制:无授权记录 = 管理员看不到。
  • 列表字段:账号名、店铺、业务名称、任务状态、执行开始时间、任务结束时间、执行进度 + 设备、 来源等补充列,并提供筛选。

依赖关系

上游(全部复用现有机制):

  • 菜单授权:columns / user_column_permission(整树替换授权;超管直通)
  • 组范围裁剪:ShopManageGroupMapper.selectAccessibleGroupIds / selectUserIdsByGroupIds / selectManagedMemberUserIds(先例 DedupeTotalDataService.resolveAccessScope:1179)
  • 设备标识:AdminAuthSupport.currentDeviceId(JWT 签名 deviceId claim,空串=来源不明; 先例 PublishController → biz_publish_file.device_id,V130)
  • 设备花名册/存活:device_log_file(V127;客户端日志上报 60s 一轮)
  • 进度口径:biz_task_progress_snapshot 优先,文件计数兜底
  • 麦象 console:MaixiangConsoleClient(复用,token 查询参数鉴权)

数据口径

任务数据源(13 个客户端模块,两张表合并)

数据源 模块(module_type,中文名取 TaskModuleRegistry.labels())
biz_file_task(12) PUBLISH 上架、DELETE_BRAND 删除ASIN、PRODUCT_RISK_RESOLVE 商品风险解决、PRICE_TRACK 跟价、SHOP_MATCH 定时匹配、PATROL_DELETE 巡店删除、QUERY_ASIN 查询ASIN、WITHDRAW 取款、APPEARANCE_PATENT 外观专利检测、SIMILAR_ASIN 货源查询、COLLECT_DATA 采集数据、SHOP_DATA_CRAWL 店铺数据抓取
brand_crawl_tasks(1) BRAND 品牌检测(该表自建、不写 biz_file_task,见 BrandTaskRetentionService 注释)
不显示 DEDUPE / SPLIT / CONVERT(纯服务端执行,无客户端设备归属)

两表字段映射(UNION ALL,子查询内下推过滤,外层排序分页):

  • task_no = biz_file_task.task_no;品牌任务合成 brand-<id>
  • status 统一大写输出(品牌表存小写):UPPER(status)
  • created_at / updated_at 同名;品牌任务无 finished_at,用终态时的 updated_at 代替
  • 进度:品牌任务用 progress_current / progress_total
  • 过滤条件(账号/状态/设备/时间范围)分别下推到两个子查询,各自走自己的索引

设备口径

  • 任务创建时记录 device_id = JWT 签名 claim(AdminAuthSupport.currentDeviceId)。 网页登录(web-<ts>-<rand>)照记,列表按 web- 前缀识别并标注「网页」。
  • 记录点:13 个模块创建入口 controller 取 deviceId → service 落库(内部令牌调用取到空串, 照记空 = 未记录);续跑任务(TaskResumeService)继承原任务 device_id。
  • 新列:biz_file_task.device_id、brand_crawl_tasks.device_id(V138)。
  • 历史任务 device_id 为空 → 显示「未记录」(不回填,无法追溯)。
  • 设备展示名:device_id → device_log_file 该设备 device_name(主机名,同设备多行聚合取 MAX, 与 DeviceLogService.recentDevices 同款);查不到时显示 device_id 截断值。

设备花名册(设备筛选器 + 设备状态卡)

两台来源合并去重:

  1. 任务设备:biz_file_task / brand_crawl_tasks 中该范围可见用户近 30 天创建过任务 的 device_id(空值不参与);
  2. 日志设备:device_log_file 中 source='client'、uid ∈ 可见用户且近 7 天有上报 (last_upload_at);uid 为空的日志设备不能归组,不显示(若其 device_id 已在任务设备 集合内则保留)。

状态判定:

  • 在线 = 最近上报(last_upload_at 或任务 updated_at 取最新)≤ 5 分钟;
  • 正在跑任务 = 该设备存在 RUNNING/进行中任务(含 BRAND 的 running/pending);
  • 两者独立展示:在线但空闲、离线但仍有终态任务都可区分。

店铺口径

任务本身不存店铺,按模块从既有数据聚合;多店铺统一显示「当前店铺 + 共 N 个」:

模块 店铺来源
PUBLISH biz_publish_file.shop_name(按 task_id 聚合 distinct)
QUERY_ASIN / WITHDRAW / PATROL_DELETE / SHOP_DATA_CRAWL / PRODUCT_RISK_RESOLVE biz_task_result_item.scope_key(task_id + module_type)
PRICE_TRACK / SHOP_MATCH biz_file_result.source_filename(文件名含店铺)
其余/兜底 biz_task_progress_snapshot.current_scope_key;再兜底 request_json.items[].shopName

店铺筛选:对上述来源做 EXISTS 子查询(三张表都有 task_id 索引:idx_result_item_task / idx_task_id / uk_task_progress_snapshot),与其余筛选一起下推到主查询。

进度口径(列表/详情展示)

  1. biz_task_progress_snapshot(task_id + module_type)优先:total/success/failed/pending + current_scope_key + message;
  2. 无快照 → biz_file_task 文件计数(source/success/failed_file_count);
  3. BRAND → brand_crawl_tasks.progress_current/progress_total。

前端展示「成功 X / 总 Y(失败 Z)」+ 百分比进度条。

「是否正常在跑」判定

  • 进行中且 updated_at 距今 ≤ 10 分钟 → 正常(任务心跳 60s 一轮);
  • 进行中且 > 10 分钟无更新 → 「疑似卡住」(仅展示提示,不做处置动作);
  • 终态 → 成功/失败/已取消,按 status 展示。

数据库迁移 V138

对齐 V119/V127/V130 幂等写法,可重复执行:

  1. biz_file_task ADD COLUMN device_id VARCHAR(128) NULL(+ KEY idx_file_task_device_created (device_id, created_at))
  2. brand_crawl_tasks ADD COLUMN device_id VARCHAR(128) NULL
  3. 菜单行:column_key='admin_task_center',name='客户端任务管理',menu_type='admin', route_path='task-center/board',parent=admin_group_record,sort_order=84 —— 只插入 columns,不写 user_column_permission(管理员默认不可见,超管直通)

回滚:DROP 两列与索引;DELETE FROM columns WHERE column_key='admin_task_center'。

后端接口(5 个,全部只读)

新模块包 modules/taskcenter/(controller / service / mapper / vo)。

鉴权:AdminAuthSupport.requireAdminOrInternal(request) + 菜单授权检查 (PermissionMenuService 新增 requireClientTaskCenterAccess,口径同 requireShopDataCrawlTaskAccess: 超管直通,非超管要求 admin_task_center 菜单授权,否则 403); 数据范围 = resolveAccessScope 同款(非超管 visibleUserIds,空集用 IN (-1) 防越权)。

接口风格对齐最新先例 AdminDeviceLogController:驼峰参数(page/pageSize/...)、返回 VO; SQL 用 @Select 注解 mapper + 手写 LIMIT/OFFSET 分页(先例 ImageVideoAdminTaskMapper)。

接口 说明
GET /api/admin/task-center/overview 汇总卡:设备总数/在线数、进行中任务数、今日完成任务数、疑似卡住数
GET /api/admin/task-center/devices 设备列表:device_id、device_name、lastActiveAt(最近上报/任务活动)、online、runningTasks、recentTaskAt、webDevice(web- 前缀=网页登录)
GET /api/admin/task-center/tasks 任务列表(分页 + 筛选:username、module_type、status、device_id、shop、start_time/end_time);字段:id、task_no、module_type、module_label、status、user_id、username、device_id、device_name、shop_name、shop_count、created_at、finished_at、progress{total,success,failed,current_scope,message}、stuck
GET /api/admin/task-center/tasks/detail 任务详情(参数 task_no,品牌任务为 brand-<id>):基础信息 + 进度快照 + 店铺/文件明细
GET /api/admin/task-center/variant-tasks 变体采集列表(代理麦象 console):uid 集合 = 可见用户;page/page_size + status/task_type 筛选;字段:task_id、uid、username、status、res_mes、create_time、update_time

前端页面

admin-frontend-vue/src/pages/task-center/:

  • TaskCenterBoardPage.vue:外层页签 + 筛选栏(账号/业务/状态/设备/店铺/时间范围)+ 汇总卡 + 设备状态卡条(在线点、运行中任务数,点击筛选该设备);
  • 页签一「客户端任务」:el-table(账号、设备、店铺、业务、状态、开始、结束、进度条、操作)
    • 详情 el-drawer;
  • 页签二「变体采集」:状态筛选 + 表格(账号、任务号、状态、开始/更新时间、进度文字 res_mes);
  • 30s 轮询:document.hidden 暂停、卸载清理、手动刷新按钮。

注册点:

  • src/router/routes.ts adminPages 追加 { path: 'task-center/board', menuKey: 'admin_task_center', title: '客户端任务管理', load: ... }
  • src/layout/operation-guides.ts 补 admin_task_center 文案(align-operation-guide.test.ts 强制)
  • AdminMenuRouteMatrix 冻结勿动(既有测试断言条数)

麦象侧改动(变体采集数据源)

maixiang_run_task/maixiang_task_api/main.py(/api/console/batch/tasks):

  1. uid 支持逗号分隔多值(uid=A,B → IN;单值语义不变);
  2. items 增加 res_mes(进度/结果文字)与 task_data(任务参数,可空)。

Java 侧同步扩展 MaixiangConsoleClient.BatchTaskItem(加 resMes 字段)与调用参数。 部署脚本:scripts/_deploy_maixiang_api.py(先于 Java 部署,保证接口先就绪)。

测试策略

  • Java:组裁剪(超管直通 / 空集 IN(-1) / 组内多用户)、两表 UNION 分页与筛选、 设备花名册合并、进度兜底、卡住判定边界(9/10/11 分钟)、V138 幂等;
  • 前端:页面渲染/筛选/页签切换/轮询清理(vitest);
  • 麦象:多 uid 过滤与 res_mes 返回(pytest);
  • 既有门禁:align-operation-guide / AdminMenuRouteMatrix / 路由注册表校验必须保持绿。

发布与回滚

  • 麦象:_deploy_maixiang_api.py(先行)
  • Java:Gitea push → mvn -o clean package -DskipTests → 发版前三取证 → _deploy_jar_and_restart_both.py(A/B 分批发若在飞任务集中)
  • 后台前端:_deploy_admin_vue.py
  • 回滚:jar 上一版备份 / 前端上一版 / 麦象备份;菜单行删除即恢复「仅超管可见」

风险与边界

  • 历史任务无设备号(V138 之前创建)→ 统一「未记录」;
  • 组裁剪按 任务发起账号(user_id) 判定可见性,不按设备归属; 设备若跨组使用(同机多账号),任务仍按账号归组,不会串组;
  • 品牌任务状态小写、其余大写,接口层统一转大写,前端只认一套;
  • 变体采集无设备/店铺归属(麦象侧无此数据),页签二不显示这两列。