From 0a7e1b9c0150e9a9302fd0da525c7bb07b5f0904 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=BB=84=E8=87=AA=E8=BE=BE?= <980324341@qq.com> Date: Mon, 28 Sep 2026 22:33:49 +0800 Subject: [PATCH] =?UTF-8?q?feat(taskcenter):=20V138=20=E5=AE=A2=E6=88=B7?= =?UTF-8?q?=E7=AB=AF=E4=BB=BB=E5=8A=A1=E7=AE=A1=E7=90=86=E8=BF=81=E7=A7=BB?= =?UTF-8?q?=E4=B8=8E=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit biz_file_task / brand_crawl_tasks 补 device_id 列(JWT 签名 claim,历史任务留空), 并挂载 admin_task_center 菜单:只写 columns 不写 user_column_permission, 管理员默认不可见,超管授权后可见。 --- backend-java/docs/migration-inventory.md | 8 +- .../db/V138__client_task_console.sql | 61 ++++++ docs/specs/16-client-task-console.md | 188 ++++++++++++++++++ 3 files changed, 253 insertions(+), 4 deletions(-) create mode 100644 backend-java/src/main/resources/db/V138__client_task_console.sql create mode 100644 docs/specs/16-client-task-console.md diff --git a/backend-java/docs/migration-inventory.md b/backend-java/docs/migration-inventory.md index 2df87f3a8..0e0900054 100644 --- a/backend-java/docs/migration-inventory.md +++ b/backend-java/docs/migration-inventory.md @@ -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`,无空格 diff --git a/backend-java/src/main/resources/db/V138__client_task_console.sql b/backend-java/src/main/resources/db/V138__client_task_console.sql new file mode 100644 index 000000000..a97ce8e82 --- /dev/null +++ b/backend-java/src/main/resources/db/V138__client_task_console.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' + ); diff --git a/docs/specs/16-client-task-console.md b/docs/specs/16-client-task-console.md new file mode 100644 index 000000000..0744d5f2a --- /dev/null +++ b/docs/specs/16-client-task-console.md @@ -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-` +- `status` 统一大写输出(品牌表存小写):`UPPER(status)` +- `created_at` / `updated_at` 同名;品牌任务无 `finished_at`,用终态时的 `updated_at` 代替 +- 进度:品牌任务用 `progress_current / progress_total` +- 过滤条件(账号/状态/设备/时间范围)分别下推到两个子查询,各自走自己的索引 + +### 设备口径 + +- 任务创建时记录 `device_id` = JWT 签名 claim(`AdminAuthSupport.currentDeviceId`)。 + **网页登录**(`web--`)照记,列表按 `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-`):基础信息 + 进度快照 + 店铺/文件明细 | +| `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)** 判定可见性,不按设备归属; + 设备若跨组使用(同机多账号),任务仍按账号归组,不会串组; +- 品牌任务状态小写、其余大写,**接口层统一转大写**,前端只认一套; +- 变体采集无设备/店铺归属(麦象侧无此数据),页签二不显示这两列。