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

189 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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)** 判定可见性,不按设备归属;
设备若跨组使用(同机多账号),任务仍按账号归组,不会串组;
- 品牌任务状态小写、其余大写,**接口层统一转大写**,前端只认一套;
- 变体采集无设备/店铺归属(麦象侧无此数据),页签二不显示这两列。