feat(taskcenter): V138 客户端任务管理迁移与设计文档
biz_file_task / brand_crawl_tasks 补 device_id 列(JWT 签名 claim,历史任务留空), 并挂载 admin_task_center 菜单:只写 columns 不写 user_column_permission, 管理员默认不可见,超管授权后可见。
This commit is contained in:
@@ -1,14 +1,14 @@
|
||||
# Flyway 迁移盘点(task-193)
|
||||
|
||||
> 生成方式:`src/test/java/com/nanri/aiimage/config/MigrationInventoryTest.java`(只读审计,可重复)。
|
||||
> 快照日期:2026-09-27。
|
||||
> 快照日期:2026-09-28。
|
||||
|
||||
## 概览
|
||||
|
||||
- 版本化迁移文件数:**136**(`src/main/resources/db/V*.sql`)
|
||||
- 整数版本范围:**V1..V137**,其中 V132/V133 为已退役空号(见下),其余连续
|
||||
- 版本化迁移文件数:**137**(`src/main/resources/db/V*.sql`)
|
||||
- 整数版本范围:**V1..V138**,其中 V132/V133 为已退役空号(见下),其余连续
|
||||
- 历史遗留小版本:**V25_1__shop_manage_group_bind_user.sql**(Flyway 语义 25.1,紧跟在 V25 之后、V26 之前执行,属历史命名,保留)
|
||||
- 最新版本:**V137__hide_redundant_indexes_invisible.sql**
|
||||
- 最新版本:**V138__client_task_console.sql**
|
||||
- 重复版本:无
|
||||
- 迁移命名:全部符合 `V<整数>(_<子版本>)?__<描述>.sql`,无空格
|
||||
|
||||
|
||||
@@ -0,0 +1,61 @@
|
||||
-- V138: 客户端任务管理(后台看板)—— 任务设备号 + 菜单
|
||||
--
|
||||
-- 设备号取自 JWT 签名的 deviceId claim(AdminAuthSupport.currentDeviceId),由各模块
|
||||
-- 创建入口显式落库(方法参数从 controller 传入);历史任务为 NULL(界面显示「未记录」,不回填)。
|
||||
-- 品牌检测任务自建 brand_crawl_tasks 表、不写 biz_file_task,故同样补列。
|
||||
--
|
||||
-- 菜单:只插 columns、不写 user_column_permission —— 管理员默认不可见(无授权记录即看不到),
|
||||
-- 超管直通;超管在「用户管理 → 菜单权限」授权后管理员可见。
|
||||
--
|
||||
-- 幂等:列/索引/菜单行均仅当不存在时创建,重复执行安全。
|
||||
-- 回滚(手工):
|
||||
-- ALTER TABLE biz_file_task DROP KEY idx_file_task_device_created, DROP COLUMN device_id;
|
||||
-- ALTER TABLE brand_crawl_tasks DROP COLUMN device_id;
|
||||
-- DELETE FROM columns WHERE column_key = 'admin_task_center';
|
||||
|
||||
SET @db_name = DATABASE();
|
||||
|
||||
SET @col_exists := (
|
||||
SELECT COUNT(*) FROM information_schema.COLUMNS
|
||||
WHERE TABLE_SCHEMA = @db_name AND TABLE_NAME = 'biz_file_task' AND COLUMN_NAME = 'device_id'
|
||||
);
|
||||
SET @sql := IF(@col_exists = 0,
|
||||
'ALTER TABLE biz_file_task ADD COLUMN device_id VARCHAR(128) NULL COMMENT ''device from signed JWT deviceId claim'' AFTER user_id',
|
||||
'SELECT 1'
|
||||
);
|
||||
PREPARE stmt FROM @sql;
|
||||
EXECUTE stmt;
|
||||
DEALLOCATE PREPARE stmt;
|
||||
|
||||
SET @idx_exists := (
|
||||
SELECT COUNT(*) FROM information_schema.STATISTICS
|
||||
WHERE TABLE_SCHEMA = @db_name AND TABLE_NAME = 'biz_file_task' AND INDEX_NAME = 'idx_file_task_device_created'
|
||||
);
|
||||
SET @sql := IF(@idx_exists = 0,
|
||||
'ALTER TABLE biz_file_task ADD KEY idx_file_task_device_created (device_id, created_at)',
|
||||
'SELECT 1'
|
||||
);
|
||||
PREPARE stmt FROM @sql;
|
||||
EXECUTE stmt;
|
||||
DEALLOCATE PREPARE stmt;
|
||||
|
||||
SET @col_exists := (
|
||||
SELECT COUNT(*) FROM information_schema.COLUMNS
|
||||
WHERE TABLE_SCHEMA = @db_name AND TABLE_NAME = 'brand_crawl_tasks' AND COLUMN_NAME = 'device_id'
|
||||
);
|
||||
SET @sql := IF(@col_exists = 0,
|
||||
'ALTER TABLE brand_crawl_tasks ADD COLUMN device_id VARCHAR(128) NULL COMMENT ''device from signed JWT deviceId claim'' AFTER user_id',
|
||||
'SELECT 1'
|
||||
);
|
||||
PREPARE stmt FROM @sql;
|
||||
EXECUTE stmt;
|
||||
DEALLOCATE PREPARE stmt;
|
||||
|
||||
-- 后台菜单:客户端任务管理(挂在「记录与版本」分组下;幂等,仅当 column_key 不存在时插入)
|
||||
INSERT INTO columns (name, column_key, menu_type, route_path, sort_order, parent_id)
|
||||
SELECT '客户端任务管理', 'admin_task_center', 'admin', 'task-center/board', 84, parent.id
|
||||
FROM columns parent
|
||||
WHERE parent.column_key = 'admin_group_record'
|
||||
AND NOT EXISTS (
|
||||
SELECT 1 FROM columns WHERE column_key = 'admin_task_center'
|
||||
);
|
||||
@@ -0,0 +1,188 @@
|
||||
# 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`(主机名);
|
||||
查不到时显示 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 (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、最近上报、在线、运行中任务数、最近任务时间 |
|
||||
| `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)** 判定可见性,不按设备归属;
|
||||
设备若跨组使用(同机多账号),任务仍按账号归组,不会串组;
|
||||
- 品牌任务状态小写、其余大写,**接口层统一转大写**,前端只认一套;
|
||||
- 变体采集无设备/店铺归属(麦象侧无此数据),页签二不显示这两列。
|
||||
Reference in New Issue
Block a user