Files
crawler-plugin/docs/specs/16-client-task-console.md
T
huangzd1997 e1f1aa8b16 feat(看板): 客户端任务管理从设备维度改为店铺维度全局在跑看板
原「在线设备」卡按日志上报窗口统计,把 89 台算成在线,与实际在跑的客户端数差一个
量级,且设备维度并不能回答"哪台机器上有任务卡住"。改为:

- 汇总卡:总店铺 / 在跑店铺 / 进行中任务 / 今日完成 / 疑似卡住
- 新增「在跑店铺看板」:当前所有进行中任务按店铺归组(在跑数、卡住数、业务分布、
  最近上报),点店铺行下筛该店铺任务;不落店铺的任务归「不挂店铺」桶
- 卡片与面板同源(同一个 aggregateShops),杜绝口径分裂
- 店铺只认两个真来源:上架结果文件 + 逐店落行的结果文件名;
  biz_task_progress_snapshot.current_scope_key 是实例锁不是店铺,已从口径中剔除
- 设备号退为详情附注,花名册 /devices 与在线判定整条链删除
- 上报口径只留一个 10 分钟窗口(进行中且超 10 分钟无上报 = 疑似卡住)

后端 3487 例全绿;新增反射护栏断言设备维度查询与快照当店铺的来源已彻底移除。
2026-10-03 22:41:29 +08:00

232 lines
16 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 客户端任务管理(后台看板)
## 模块职责
后台「客户端任务管理」页面,让管理员**按店铺 × 账号 × 业务**统一查看客户端任务执行情况。
本页的目的地是「哪家店现在有任务在跑、跑得到不到底」,一屏看完,不必逐台客户端登录检查;
超管可看全部,管理员只能看本组(本人 + 本组用户 + 自己管理的成员)。
看板维度是**店铺**,不是设备:设备号只是任务的一个附注(详情里展示「跑在哪台机」),
不参与任何统计口径。改造前用「在线设备」计数,把「近 5 分钟有日志上报的设备」当成了存活,
网页登录设备与只上报日志的设备一起进数,与「有客户端任务在跑」根本不是同一件事。
覆盖页面:
- 客户端任务管理:`task-center/board`(两个页签:「客户端任务」「变体采集」)
需求约束(用户明确):
- **默认只有超管可见**;管理员需超管在「用户管理 → 菜单权限」授权后可见 —— 复用现有菜单授权机制
(`columns` + `user_column_permission`),**不新建权限机制**:无授权记录 = 管理员看不到。
- 顶部汇总卡:总店铺 / 在跑店铺 / 进行中任务 / 今日完成 / 疑似卡住。
- 全局在跑店铺面板:一行一个店铺,列在跑任务数、疑似卡住数、业务分布、最近上报;点行下钻到该店铺的任务。
- 列表字段:账号名、店铺、业务名称、任务状态、当前处理、开始时间、最近上报、结束时间、执行进度,
并提供筛选(账号/业务/状态/店铺/时间范围)。
- 「只要客户端任务在跑就上报」是面板的前提:进行中任务的 `updated_at` 由心跳(60s)与结果回传共同顶新,
因此不再需要任何设备身份基线(曾用过的 code.txt 台账已放弃)。
## 依赖关系
上游(全部复用现有机制):
- 菜单授权:`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)
- 店铺库:`biz_shop_manage`(`shop_name` 唯一、`created_by_id` 归组,无软删列)
- 逐店落行的结果文件:`biz_file_result.source_filename`(仅 6 个模块按店铺建行)
- 进度口径:`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`
- 过滤条件(账号/状态/店铺/时间范围)分别下推到两个子查询,各自走自己的索引
(`biz_file_task` 有 `idx_module_status(module_type, status)`,进行中面板直接复用它)
### 设备号(只作附注,不参与统计)
- 任务创建时记录 `device_id` = JWT 签名 claim。
**网页登录**(`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` 同款);**只在详情查一次**,列表不查设备名。
- 原「设备花名册 + 5 分钟在线」口径已整体删除(任务设备近 30 天 ∪ 日志设备近 7 天那套 UNION、
`countOnlineDevices`、`/devices` 接口与前端设备条),不再有任何以设备为分母的数字。
### 店铺归属:两个真来源 + 一个「不挂店铺」桶
面板与列表的店铺只认两个来源:
| 来源 | 覆盖模块 | 说明 |
|---|---|---|
| `biz_publish_file.shop_name` | PUBLISH | 上架结果文件,按 task_id 聚合 distinct |
| `biz_file_result.source_filename` | PATROL_DELETE、PRICE_TRACK、PRODUCT_RISK_RESOLVE、QUERY_ASIN、SHOP_DATA_CRAWL、SHOP_MATCH | 这 6 个模块逐店落行,`source_filename` 存的就是规范化后的店铺名;SQL 里必须带这份模块白名单,否则会把别的模块的**上传文件名**当店铺 |
已否决的候选(都会把不是店铺的东西当店铺):
- `biz_task_progress_snapshot.current_scope_key` —— 形如 `task:<id>:owner:<instance>`,是**实例锁**;
品牌行该列是品牌关键字。列表仍原样透出这一列(排查「哪个实例占着任务」),但它不是店铺。
- `biz_task_result_item.scope_key` —— 任务结果分组名。
- `request_json.items[].shopName` —— 大 JSON 列;列表主查询刻意不拉它,为兜底把它读出来过一次代价太大。
COLLECT_DATA / SIMILAR_ASIN / APPEARANCE_PATENT / BRAND 这些不落店铺,面板给它们一行合成桶
**「不挂店铺」**(`noShop=true`):按线上一次实测 42 个在跑任务里有 19 个属于这一类,
没有桶它们就会在看板里静默消失。桶行不可下钻(没有可筛的店铺名),要看这些任务用业务筛选。
一个任务挂多家店铺时在每家店下各计一次;归组键 `LOWER(TRIM(...))`,同一店两种写法不拆成两行,
展示名沿用首次出现的写法。
### 店铺口径(面板与卡片)
- **总店铺** = `biz_shop_manage` 中可见账号(`created_by_id`)名下的店铺数(超管不裁剪)。
- **在跑店铺** = 面板行数减去「不挂店铺」桶。汇总卡与 `/shops` **共用同一次聚合**
(`TaskCenterQueryService.aggregateShops`),卡片说几家在跑、面板就列几行,两处不允许各算各的。
- 面板原料 = 当前全部进行中任务(客户端 12 模块 ∪ 品牌),行数上限 500;触顶时服务层 `log.warn`,
卡片的进行中/卡住/今日完成三项仍走 SQL 精确计数。
- 面板排序:有卡住的排前面 → 最久没上报的排前面 → 「不挂店铺」桶永远垫底。
- 店铺筛选:上面两个来源任一命中(EXISTS + `LOWER(TRIM(...)) = LOWER(TRIM(?))` **精确**匹配,
LIKE 会让「林芳」命中「林芳芳」);品牌分支带店铺筛选时恒空(品牌不存店铺,且品牌 id 会与 biz 撞号)。
### 任务列表的店铺列
`shopName` 取该任务店铺列表的第一个,`shopCount` 是数量;无来源命中时留空(显示「—」),
不做文件名/请求体兜底 —— 宁可空,不把文件名当店铺。
### 进度口径(列表/详情展示)
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 分钟无更新 → 「疑似卡住」(**仅展示提示,不做处置动作**);
`updated_at` 缺失时回落 `created_at` 判老;
- 终态 → 成功/失败/已取消,按 `status` 展示;
- 列表/详情/面板统一输出 `lastReportAt`(= `updated_at`,缺失回落 `created_at`),文案用「最近上报」,
不再说「在线/离线」——设备是否在线与任务是否在跑是两件事。
- 唯一的窗口就是这 10 分钟;30 天 / 7 天 / 5 分钟那三个设备窗口随设备维度一起删除。
## 数据库迁移 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'`。
## 后端接口(6 个,全部只读)
新模块包 `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` | 汇总卡:shopTotal 总店铺、shopRunning 在跑店铺、runningTasks 进行中、todayFinishedTasks 今日完成、stuckTasks 疑似卡住 |
| `GET /api/admin/task-center/shops` | 在跑店铺面板:shop、noShop(是否「不挂店铺」桶)、runningTasks、stuckTasks、moduleSummary(如「跟价×2 / 定时匹配×1」)、lastReportAt |
| `GET /api/admin/task-center/shop-options` | 店铺筛选候选:`biz_shop_manage` 去重店铺名(`LIMIT 2000`,只取 `shop_name` 一列,不带 account/password/zn_username) |
| `GET /api/admin/task-center/tasks` | 任务列表(分页 + 筛选:page、pageSize、username、moduleType、status、shop、startTime/endTime);字段:id、taskNo、moduleType、moduleLabel、status、userId、username、deviceId、webDevice、shopName、shopCount、createdAt、finishedAt、lastReportAt、progressTotal/progressSuccess/progressFailed、currentScope、message、stuck(`deviceName` 只在详情装配) |
| `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-select filterable clearable`,候选 = 店铺库 ∪ 面板出现的店铺名
(店铺已删、但任务还在的情形也筛得动);
- 页签一「客户端任务」:表格(账号、店铺、业务、状态、当前处理、开始、最近上报、结束、进度条、操作)
+ 详情 `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:`TaskCenterQueryServiceTest` 守「卡片在跑店铺 = 面板行数减桶」「每个进行中任务恰好落进一个桶
(无店铺归属的不许消失)」「多店任务每店各计一次」「两种写法归一行」「快照 scope 不是店铺」
「品牌行撞号时不继承 biz 行店铺」「卡住边界 9/10/11 分钟」「列表不查设备名」;
`TaskCenterQueryMapperSqlTest` 守 SQL:店铺筛选带模块白名单 + 精确匹配、面板查询不带筛选占位符、
`current_scope_key` 不出现在店铺位置,并用反射断言 `selectRequestJson`/`selectResultItemShops`/
设备花名册那批方法已不存在;组裁剪(超管直通 / 空集 `IN(-1)` / 组内多用户)、V138 幂等同前;
- 前端:`tests/task-center-board.test.ts` 守接口清单(6 个)、设备维度不得回流(`deviceTotal`/
`deviceOnline`/`/devices`/`filter.deviceId` 全部断言不存在)、面板下钻与桶行不可点接线、
筛选参数与三种空态;
- 麦象:多 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 之前创建)→ 详情显示「未记录」;看板不看设备,不受影响;
- 「不挂店铺」桶里的任务不能按店铺下钻(它们本来没有店铺维度),只能按业务筛;
- `biz_file_result.source_filename` 作为店铺只在这 6 个逐店落行的模块成立,其余模块该列是上传文件名,
由 SQL 模块白名单挡在外面;店铺名对不上时表现为「不挂店铺」,不会串到别的店;
- 面板取进行中任务上限 500 行:触顶时卡片仍按 SQL 精确计数、面板会少列,服务层 `log.warn`
(实测在跑任务为数十量级);
- 组裁剪按 **任务发起账号(user_id)** 判定任务可见性,店铺库按 `created_by_id`;
店铺若跨组共用,任务仍按账号归组,不会因为店铺同名而串组;
- 品牌任务状态小写、其余大写,**接口层统一转大写**,前端只认一套;
- 变体采集无店铺归属(麦象侧无此数据),页签二不显示店铺列。