Files
crawler-plugin/docs/specs/16-client-task-console.md
T

337 lines
26 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、开始时间、最近上报、结束时间、执行进度
(进度按「已完成数 / 总数」,已完成 = 成功 + 失败,与客户端任务面板同口径;采集数据这一列照抄客户端
文案「关键词进度:第 N/总 个」),
并提供筛选(账号/业务/状态/店铺/时间范围);状态默认「在跑」,其余状态保留入口。
- 「只要客户端任务在跑就上报」是「在跑店铺」与「疑似卡住」两张卡的前提:进行中任务的 `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` 优先;无快照按模块分档(采集=关键词数、上架/删除ASIN/品牌=文件数、
其余=无进度),见「进度口径」节
- 麦象 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 这些任务不落店铺:按线上一次实测,42 个在跑
任务里有 19 个属于这一类。它们没有店铺归属,只能按业务筛出来看。
一个任务挂多家店铺时每家都算;归组键 `LOWER(TRIM(...))`,同一店两种写法算一家。
### 店铺口径(只有汇总卡)
- **总店铺** = `biz_shop_manage` 中可见账号(`created_by_id`)名下的店铺数(超管不裁剪)。
- **在跑店铺** = 进行中任务挂到的**去重店铺数**(`TaskCenterQueryService.runningShops`,
归组键同上)。不落店铺的任务天然不计入,所以「在跑店铺 5」不等于「5 个任务在跑」,
后者看「进行中任务」那张卡。
- 原料 = 当前全部进行中任务(客户端 12 模块 ∪ 品牌),扫描行数上限 500;触顶时服务层 `log.warn`
并说明该数会偏小,卡片的进行中/卡住/今日完成三项仍走 SQL 精确计数。
- 店铺筛选:上面两个来源任一命中(EXISTS + `LOWER(TRIM(...)) = LOWER(TRIM(?))` **精确**匹配,
LIKE 会让「林芳」命中「林芳芳」);品牌分支带店铺筛选时恒空(品牌不存店铺,且品牌 id 会与 biz 撞号)。
### 任务列表的店铺列
`shopName` 取该任务店铺列表的第一个,`shopCount` 是数量;无来源命中时留空(显示「—」),
不做文件名/请求体兜底 —— 宁可空,不把文件名当店铺。
### 状态筛选:默认「在跑」= 三个进行中状态合并
用户 2026-10-04 要求「其他状态也保留,但默认显示执行中的任务」,落地方式是把合并口径放在**一处**:
- 前端 `TASK_STATUS_OPTIONS` 首项仍是「全部状态」,第二项新增 `ACTIVE`「在跑」并作为页面默认值
(`createTaskFilter()` 保持全空 = 不裁剪,默认值由页面 `defaultTaskFilter()` 覆盖,重置也回到「在跑」);
- `ACTIVE` 不是表里的状态,后端 `TaskCenterQueryService.statusFilter` 把它展开成
`ACTIVE_STATUSES_ORDERED`(= 判在跑/判卡住用的 `ACTIVE_STATUS_SET`,两者由用例钉成同一组成员),
SQL 侧状态筛选相应从单值 `= ?` 改成 `IN (...)`,两张表分支各自展开,品牌表小写状态仍由 `STATUS_B` 归一;
- 近 7 天 PENDING/SCHEDULED 实际 0 行,所以默认「在跑」今天等价于旧的「执行中」,
但排期与待领取的任务不会再被默认视图漏掉。
### 默认视图不锁创建时间(与「进行中任务」卡片同数)
用户 2026-10-04 13:2x 报「列表 12 条执行中、卡片 32 对不上」。**差额与状态合并无关**,生产只读复算:
| 口径 | SQL 特征 | 实测 |
|---|---|---|
| 卡片 `countRunningTasks` | 12 模块白名单 + 三状态 ∪ 品牌 pending/running,**不带创建时间窗** | **39**(count 3.2ms,走 `idx_module_status` 覆盖索引) |
| 列表默认(旧) | 同上 **+ 今天 00:00–23:59** | **21** |
| 差额 | 10-01 17:49 ~ 10-03 21:25 创建、`updated_at` 13:20~13:22 仍在推进 | **18 个跨天在跑任务** |
此刻库里 PENDING/SCHEDULED = 0、品牌在跑 = 0,全部是 RUNNING ⇒ 这 18 个不是僵尸、也不是品牌口径,
就是被"默认今天"挡在列表外。所以:
- `defaultTaskFilter()` **只给 `status: ACTIVE`,不再给 `startTime/endTime`**(`todayTaskRange()` 与该
helper 的 import 一起撤掉),时间控件保留、初值为空,用户要查历史自己选;
- 页头说明改口为「默认列出全部在跑任务…条数与上方「进行中任务」同源」;
- 这条与仓库级护栏 `date-filter-default-today`("带日期筛选的页必须默认当天")冲突,按用户定案
**走豁免**:豁免清单加 `TaskCenterBoardPage.vue` 并写明理由,同时把该用例的分母注释与阈值一起改准
(带日期控件 9 个文件 / 豁免 3 个 ⇒ managed 6,阈值 6→5 保留一档余量)—— 豁免不是把护栏调松,
而是让"这一页故意不同窗"这件事留在代码里可被读到;
- 护栏用例 `task_center_default_view_has_no_time_window_so_it_matches_the_card` 断言默认查询里
`startTime/endTime` 均为 `undefined`,且页面源码不再出现 `todayTaskRange`/`todayDateTimeRange`。
### 进度口径(列表/详情展示)
1. `biz_task_progress_snapshot`(task_id + module_type)优先:total/success/failed/pending +
`current_scope_key` + `message`;
2. BRAND 行 → `brand_crawl_tasks.progress_current/progress_total`;
3. 无快照的采集数据(COLLECT_DATA)→ `biz_file_task.result_json` 的 `$.totalRows / $.processedRows`,
与客户端「关键词进度:第 X/N 个」同一份数、同一比值口径(SQL 侧只抽这两列,大 JSON 不出库);
4. 无快照的上架 / 删除ASIN → 行内文件计数(客户端进度条单位本就是文件);
5. 其余无快照模块(跟价、定时匹配…)→ 进度置 0,**不回退文件数**:客户端在这些模块没有进度条,
而单文件任务回退成「已完成 0 / 总 1」会被读成"一步没跑",是误导。
前端文案两档(2026-10-04 用户要求「和客户端同步一致」):采集数据行逐字抄客户端
`BrandCollectDataTab.vue#taskKeywordProgress` —— **关键词进度:第 min(总, 已处理+1)/总 个**;
其余模块仍是「已完成 X / 总 Y(失败 Z 徽标)」+ 百分比进度条。
`progressTotal ≤ 0` 时只显示「—」,不画 0% 空进度轨(空轨="进度 0%",与"这里没有进度可看"是两件事)。
### 国家列(只展示,不做筛选)
`biz_file_task` / `brand_crawl_tasks` 都没有国家列,目标站点只存在于 `request_json` 里,且各模块写法不同
(2026-10-04 生产实测,七条路径按下面的优先级 COALESCE):
| 顺序 | JSON 路径 | 近 7 天实际命中(模块 → 条数) |
|---|---|---|
| 1 | `$.filters.countryCode` | 采集数据 138 |
| 2 | `$.countryCode` | — 0 条 |
| 3 | `$.country` | — 0 条 |
| 4 | `$.publish_country` | 上架 13 |
| 5 | `$.countryCodes` | 跟价 141、店铺数据抓取 8 |
| 6 | `$.country_codes` | 定时匹配 15 |
| 7 | `$.filters.countryCodes` | 采集数据 138(与路径 1 同值,靠优先级取 1) |
- **覆盖率**:近 7 天 315/451 = **69.8%**,12 个在跑的模块里 **5 个**能取到(跟价、采集数据、定时匹配、上架、
店铺数据抓取);取不到的是外观专利检测 46、货源查询 36、去重 29、商品风险解决 21、删除ASIN 2,
以及不在业务下拉里的 SPLIT 1 / CONVERT 1
—— 这些模块的请求参数里本就没有国家,显示「—」,不用店铺名或账号默认站点猜;
全历史比例更低(老任务写法不同);
- **形状**两种并存:裸串 `UK` 与数组文本 `["UK", "DE"]`(同一模块两种都有:`UK`140 / `["DE"]`80 /
`["UK"]`75 / `DE`10 / `["UK", "DE"]`5 / `["DE", "UK"]`4 / `ES`1),服务层归一为 `UK` / `UK/DE`,
多国家不截断成第一个(多国家任务共 9 条:定时匹配 5、店铺数据抓取 4);
- **取数位置**:`selectTaskCountries` 按页内 biz 任务号主键点查,**不进列表主查询** ——
那条 UNION 的既有护栏是不碰 `request_json`(大 JSON 列是列表慢查询的主因之一)。
实测同形状点查 20 行 45ms,与不带 JSON 表达式的 41ms 同量级;
- 品牌任务没有国家维度(该表 14 列无相关字段),且品牌 id 会与 biz id 撞号,所以按 `brand` 行筛掉、不发查询;
- 按用户定案**只加列不动筛选**:不加国家下拉、不加 `country` 查询参数。
### 「是否正常在跑」判定
- 进行中且 `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/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;`status=ACTIVE` = 三个进行中状态合并,其余按单值);字段:id、taskNo、moduleType、moduleLabel、status、userId、username、deviceId、webDevice、shopName、shopCount、country、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 筛选;**不传 status = 只看在跑**(等待 0 ∪ 处理中 1 各拉一页合并,历史终态不再展示) |
## 前端页面
`admin-frontend-vue/src/pages/task-center/`:
- `TaskCenterBoardPage.vue`:外层页签 + 汇总卡(总店铺/在跑店铺/进行中任务/今日完成/疑似卡住)+
筛选栏(账号/业务/状态/店铺/时间范围);
- 店铺筛选:`el-select class="admin-filter" filterable clearable`(`admin-filter` 把控件补到 42px,
与同行原生控件同高,`align-items: flex-end` 的筛选行里 label 才不会被顶偏),
候选 = 店铺库(`shop-options`);看板下线后不再并入「看板上出现过的店铺」,
店铺已从店铺库删掉但任务还在的情形,改用账号或业务筛;
- 页签一「客户端任务」:表格(账号、店铺、国家、业务、状态、任务ID、开始、最近上报、结束、进度)
+ 详情 `el-drawer`(设备名、当前处理与分组明细只在详情出现;「操作」列已删,任务ID 单元格是详情入口);
状态下拉默认「在跑」(`ACTIVE` 哨兵,见「状态筛选」节),国家列只展示不可筛;
采集数据行的进度文案 = 客户端那句「关键词进度:第 N/总 个」;
- 页签二「变体采集」:**只看在跑**——状态下拉三项(在跑=不传 status/等待执行/处理中,历史终态不提供入口),
表格(账号、任务号、状态、开始/更新时间、进度文字 res_mes);徽章是在跑条数,麦象单状态拉取上限 200,
触顶时服务层记 warn 且翻页尾部会缺行;
- 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(task-center 四支共 77 例:Mapper SQL 29 + 服务层 33 + 组裁剪 7 + 变体 8)。
`TaskCenterQueryServiceTest` 守「在跑店铺 = 进行中任务挂到的去重店铺数」「多店任务每店各计一次」
「两种写法归一行」「两个来源指向同一家店不重复计」「品牌任务不查店铺来源」「快照 scope 不是店铺」
「品牌行撞号时不继承 biz 行店铺」「卡住边界 9/10/11 分钟」「列表不查设备名」,
本轮新增「`ACTIVE` 哨兵展开成三个进行中状态」「单状态仍按单值下发、空值不下发筛选」
「国家两种 JSON 形态都归一(`["UK"]`→`UK`、`["UK", "DE"]`→`UK/DE`、缺字段→`null`)」
「品牌行不发国家查询」;
`TaskCenterQueryMapperSqlTest` 守 SQL:店铺筛选带模块白名单 + 精确匹配、进行中任务查询不带筛选占位符、
`current_scope_key` 不出现在店铺位置,并用反射断言 `selectRequestJson`/`selectResultItemShops`/
设备花名册那批方法已不存在;组裁剪(超管直通 / 空集 `IN(-1)` / 组内多用户)、V138 幂等同前,
本轮新增「状态筛选渲染成 `IN (…)` 且绑定顺序 = PENDING/RUNNING/SCHEDULED」「单状态仍是单元素 `IN`」
「国家查询按线上实测的 7 条 JSON 路径顺序逐条定位、只按主键批查、整条不出现 `result_json` 列名」
「状态字面量与 `ACTIVE_STATUS_SET`/`ACTIVE_STATUSES` 三处同源」;
- 前端:`tests/task-center-board.test.ts`(22 例)守接口清单(5 个)、设备维度不得回流(`deviceTotal`/
`deviceOnline`/`/devices`/`filter.deviceId` 全部断言不存在)、**店铺看板整条不得回流**
(`在跑店铺看板`/`selectShop`/`shopFilterOptions`/`fetchTaskCenterShops`/`moduleSummary` 与 `/shops` 全部断言不存在)、
筛选参数与三种空态,本轮新增「采集数据行文案为「关键词进度:第 N/总 个」且 N 封顶总个数」
「国家列只展示:`row.country || '—'`,同时断言 `filter.country` 与 `country` 查询参数都不存在」
「默认筛选 `status = ACTIVE`,重置后仍是 ACTIVE」「列头顺序含国家、空态 colspan 随列数走」;
- 护栏自证:4 个变异点(国家路径顺序调换 / 哨兵不展开 / 归一只取第一个 / 采集文案分支删掉)
全部被对应用例抓到,注入文件按还原前读进内存的字节回写并复验一致;
- 麦象:多 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 行:触顶时该数会偏小,服务层 `log.warn` 报出来,其余三张卡
仍按 SQL 精确计数(实测在跑任务为数十量级);
- 组裁剪按 **任务发起账号(user_id)** 判定任务可见性,店铺库按 `created_by_id`;
店铺若跨组共用,任务仍按账号归组,不会因为店铺同名而串组;
- 品牌任务状态小写、其余大写,**接口层统一转大写**,前端只认一套;
- 变体采集无店铺归属(麦象侧无此数据),页签二不显示店铺列。
- **国家列是「读得到才显示」,不是保证有值**:`biz_file_task`/`brand_crawl_tasks` 都没有国家列,
值只埋在 `request_json` 里,且线上有 7 种拼法、裸串(`UK`)与数组文本(`["UK", "DE"]`)两种形态。
近 7 天实测 315/451 = 69.8%(12 个模块里 5 个能取到,见「国家列」节);取不到即显示「—」,
与「该任务没有国家」在 UI 上不可区分——这是刻意的:不为此建列、不做迁移。
多国家用 `/` 连接成一个字符串,不展开成多行。老客户端可能写第 8 种拼法:读不到的按「—」处理,
补路径要同步改这条护栏用例(它钉的就是当前 7 条的顺序与条数)。
- 国家**只按主键批查当前页**(≤ 页大小个 id),不进列表 UNION:一旦把 `request_json` 塞进主查询,
就是已知的「列表查询拉大 JSON 列」慢 SQL 老问题。线上实测该表达式 20 行一页 45ms,
同口径不取国家 41ms,差值可忽略;但这一条只对「当前页」成立,不许改成全表扫或加进 `COLS_T`。
- 品牌行**不发国家查询**:`brand_crawl_tasks` 14 个线上真实列里没有任何国家字段,
且其 id 与 `biz_file_task.id` 会撞号,若按 id 去查会拿别的任务的国家糊上去。
- 默认筛选变成「在跑」(`ACTIVE` = 待执行 ∪ 执行中 ∪ 已排期)、**创建时间不限**:这是**行为变更**,
进页面不再看到终态任务,要看历史必须换状态;默认不锁时间是为了让列表条数与卡片「进行中任务」
同源(见「默认视图不锁创建时间」节,实测 39 vs 21 的差就是被"今天"挡掉的 18 个跨天在跑任务)。
合并口径只在服务层 `statusFilter` 一处展开,状态成员由 `ACTIVE_STATUSES_ORDERED` 与
`ACTIVE_STATUS_SET`/`ACTIVE_STATUSES` 三处同源测试钉住——新增进行中状态时若漏改,测试即红。
- 采集数据进度文案改成客户端口径,**只改文字不改数字**:后端对 COLLECT_DATA 令
`progressFailed = 0` 并把 `progressSuccess` 夹在 `[0, total]`,故 `已完成行数 + 1` 与客户端
「第 N 个」同源;`Math.min(total, done + 1)` 保证跑完时显示「第 总/总 个」而不是「第 总+1/总 个」。