Files
crawler-plugin/docs/specs/16-client-task-console.md
T
huangzd1997 186c288dbf feat(taskcenter): 两表 UNION 任务列表 + 筛选 + 店铺/进度装配
- biz_file_task(12 个客户端模块)∪ brand_crawl_tasks,品牌任务号合成 brand-<id>、
  终态用 updated_at 充当 finished_at;子查询内下推过滤、外层排序分页
- 筛选:账号名(users LIKE → ∩ 可见账号)、业务、状态、设备、店铺(4 个来源 EXISTS)、
  创建时间范围;选具体业务时品牌分支恒空,带店铺筛选时品牌分支直接排除(防撞号误判)
- 状态口径单一来源:SQL 字面量与 Java 集合由测试守同步,服务层判「卡住」复用同一集合
- 店铺来源优先级链:上架结果文件 → 任务结果分组 → 结果文件名 → 快照 scope → 请求体
  items[].shopName(最后一级批量一次拉取,列表主查询不拉大 JSON 列);品牌行店铺恒空
- 进度:快照(按 moduleType+taskId 匹配,防品牌 id 撞号)优先,无快照用行内文件计数

Tests run: 42, Failures: 0, Errors: 0
2026-09-28 23:09:21 +08:00

192 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 个」:
1. `biz_publish_file.shop_name`(上架结果文件,按 task_id 聚合 distinct);
2. `biz_task_result_item.scope_key`(任务结果分组);
3. `biz_file_result.source_filename`(结果文件名里带店铺,如跟价/定时匹配);
4. `biz_task_progress_snapshot.current_scope_key`;
5. `request_json.items[].shopName`(兜底,只对当页前四个来源都为空的任务批量拉一次)。
各模块的主来源天然落在链上的对应位置,未列出的模块自动降级到下一来源;品牌行店铺恒空。
店铺筛选:对来源 1~4 做 EXISTS 子查询(四张表都有 task_id 索引:`biz_publish_file` /
`idx_result_item_task` / `idx_task_id` / `uk_task_progress_snapshot`),与其余筛选一起下推到
主查询;`request_json` 不参与筛选。
### 进度口径(列表/详情展示)
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` | 设备列表:deviceId、deviceName、lastActiveAt(最近上报/任务活动)、online、runningTasks、recentTaskAt、webDevice(`web-` 前缀=网页登录) |
| `GET /api/admin/task-center/tasks` | 任务列表(分页 + 筛选:page、pageSize、username、moduleType、status、deviceId、shop、startTime/endTime);字段:id、taskNo、moduleType、moduleLabel、status、userId、username、deviceId、deviceName、webDevice、shopName、shopCount、createdAt、finishedAt、progressTotal/progressSuccess/progressFailed、currentScope、message、stuck |
| `GET /api/admin/task-center/tasks/detail` | 任务详情(参数 `taskNo`,品牌任务为 `brand-<id>`):基础信息 + 进度快照 + 店铺/文件明细 |
| `GET /api/admin/task-center/variant-tasks` | 变体采集列表(代理麦象 console):uid 集合 = 可见用户;page/pageSize + status/taskType 筛选 |
## 前端页面
`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)** 判定可见性,不按设备归属;
设备若跨组使用(同机多账号),任务仍按账号归组,不会串组;
- 品牌任务状态小写、其余大写,**接口层统一转大写**,前端只认一套;
- 变体采集无设备/店铺归属(麦象侧无此数据),页签二不显示这两列。