Files
crawler-plugin/docs/specs/16-client-task-console.md
T
huangzd1997 4a6e139ae9 feat(后台): 日期筛选统一默认当天(7 页 + 告警铃铛),并带上看板列改造的在途改动
- utils/datetime 新增 todayDateInput()/todayDateTimeRange(),8 处日期筛选的初值与「重置」都锁当天;
  撞款监控按口径排除(该页日期是 ASIN 上架时间,默认当天会让首屏几乎为空)。
- NotificationBell 的 hasFilter 不再把日期计入:日期恒有值是默认视图,计入会让
  「无筛选才记录已提醒 id」那条分支永久失效。
- 新增护栏 tests/date-filter-default-today.test.ts(6 例,变异自证 3/3 转红):
  凡带日期控件的页面没接入当天默认就红,不等人工发现首屏是空的。
- 同批带上另一路会话的看板在途改动(task-center-model 的 tabCount/完成数口径、
  TaskCenterBoardPage 列改造与对应用例):它与本页的日期默认改动落在同一文件,
  拆开会让单次提交编译不过,故按现状一起上。
2026-10-04 01:19:28 +08:00

235 lines
17 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`),**不新建权限机制**:无授权记录 = 管理员看不到。
- 顶部汇总卡:总店铺 / 在跑店铺 / 进行中任务 / 今日完成 / 疑似卡住。
- 全局在跑店铺面板:一行一个店铺,列在跑任务数、疑似卡住数、业务分布、最近上报;点行下钻到该店铺的任务。
- 列表字段:账号名、店铺、业务名称、任务状态、任务ID、开始时间、最近上报、结束时间、执行进度
(进度按「已完成数 / 总数」,已完成 = 成功 + 失败,与客户端任务面板同口径),
并提供筛选(账号/业务/状态/店铺/时间范围)。
- 「只要客户端任务在跑就上报」是面板的前提:进行中任务的 `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 class="admin-filter" filterable clearable`(`admin-filter` 把控件补到 42px,
与同行原生控件同高,`align-items: flex-end` 的筛选行里 label 才不会被顶偏),
候选 = 店铺库 ∪ 面板出现的店铺名
(店铺已删、但任务还在的情形也筛得动);
- 页签一「客户端任务」:表格(账号、店铺、业务、状态、任务ID、开始、最近上报、结束、进度)
+ 详情 `el-drawer`(设备名、当前处理与分组明细只在详情出现;「操作」列已删,任务ID 单元格是详情入口);
- 页签二「变体采集」:状态筛选 + 表格(账号、任务号、状态、开始/更新时间、进度文字 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`(出包即跑全量测试)→ 发版前三取证 →
`_deploy_jar_and_restart_both.py <jar 路径>`(A/B 分批发若在飞任务集中)
- 后台前端:`npm run build` → `_deploy_admin_vue.py`(上传本地 `dist/`,原子切软链并删旧版本目录)
- 回滚:jar 上一版备份 / 前端上一版 / 麦象备份;菜单行删除即恢复「仅超管可见」
## 风险与边界
- 历史任务无设备号(V138 之前创建)→ 详情显示「未记录」;看板不看设备,不受影响;
- 「不挂店铺」桶里的任务不能按店铺下钻(它们本来没有店铺维度),只能按业务筛;
- `biz_file_result.source_filename` 作为店铺只在这 6 个逐店落行的模块成立,其余模块该列是上传文件名,
由 SQL 模块白名单挡在外面;店铺名对不上时表现为「不挂店铺」,不会串到别的店;
- 面板取进行中任务上限 500 行:触顶时卡片仍按 SQL 精确计数、面板会少列,服务层 `log.warn`
(实测在跑任务为数十量级);
- 组裁剪按 **任务发起账号(user_id)** 判定任务可见性,店铺库按 `created_by_id`;
店铺若跨组共用,任务仍按账号归组,不会因为店铺同名而串组;
- 品牌任务状态小写、其余大写,**接口层统一转大写**,前端只认一套;
- 变体采集无店铺归属(麦象侧无此数据),页签二不显示店铺列。