新增 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 项。
11 KiB
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 截断值。
设备花名册(设备筛选器 + 设备状态卡)
两台来源合并去重:
- 任务设备:
biz_file_task/brand_crawl_tasks中该范围可见用户近 30 天创建过任务 的 device_id(空值不参与); - 日志设备:
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),与其余筛选一起下推到主查询。
进度口径(列表/详情展示)
biz_task_progress_snapshot(task_id + module_type)优先:total/success/failed/pending +current_scope_key+message;- 无快照 →
biz_file_task文件计数(source/success/failed_file_count); - BRAND →
brand_crawl_tasks.progress_current/progress_total。
前端展示「成功 X / 总 Y(失败 Z)」+ 百分比进度条。
「是否正常在跑」判定
- 进行中且
updated_at距今 ≤ 10 分钟 → 正常(任务心跳 60s 一轮); - 进行中且 > 10 分钟无更新 → 「疑似卡住」(仅展示提示,不做处置动作);
- 终态 → 成功/失败/已取消,按
status展示。
数据库迁移 V138
对齐 V119/V127/V130 幂等写法,可重复执行:
biz_file_taskADD COLUMNdevice_id VARCHAR(128) NULL(+KEY idx_file_task_device_created (device_id, created_at))brand_crawl_tasksADD COLUMNdevice_id VARCHAR(128) NULL- 菜单行:
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.tsadminPages 追加{ 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):
uid支持逗号分隔多值(uid=A,B→IN;单值语义不变);- 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) 判定可见性,不按设备归属; 设备若跨组使用(同机多账号),任务仍按账号归组,不会串组;
- 品牌任务状态小写、其余大写,接口层统一转大写,前端只认一套;
- 变体采集无设备/店铺归属(麦象侧无此数据),页签二不显示这两列。