Files
crawler-plugin/docs/plans/16-client-task-console.md
T
huangzd1997 49c3fc1491 docs(仓库): 规划文档改为入库,落盘品牌库/去重库每公司一套二期方案
`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」,
代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红),
跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
2026-10-04 13:51:16 +08:00

720 lines
32 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.
# 客户端任务管理(后台看板)实现计划
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 后台新增「客户端任务管理」页面(两页签:客户端任务 / 变体采集),管理员按组查看每台客户端的任务执行情况,超管可看全部。
**Architecture:** 新模块包 `modules/taskcenter/`(1 controller + 2 service + 1 mapper + VO),任务列表 = `biz_file_task`(12 客户端模块)与 `brand_crawl_tasks`(BRAND)UNION 合并;设备号在 13 个创建入口以方法参数从 JWT 注入并落库(V138 加列);权限复用菜单授权 + 组范围裁剪;前端新页面 `task-center/board` 走现有 admin 注册表。
**Tech Stack:** Java 21 / Spring Boot 3.3.9 / MyBatis-Plus(`@Select` 注解 SQL)/ Flyway;Vue 3 + TS + Element Plus + vitest;麦象 Flask(FastAPI)`maixiang_task_api`。
**Spec:** `crawler-plugin/docs/specs/16-client-task-console.md`
## Global Constraints
- Flyway 只能新增 `V138__*.sql`;历史迁移一字不改;`backend-java/docs/migration-inventory.md` 必须同步(`MigrationInventoryTest` 断言文档含 "V138")。
- 菜单/权限复用现有机制(`columns` + `user_column_permission`),不新建权限体系。
- device_id 只认 JWT 签名 claim(`AdminAuthSupport.currentDeviceId`),**绝不接受客户端可控的请求头/请求体**。
- 生产红线(记忆):生产写操作只交付命令不自行执行;发布前跑三条取证;只 `git add` 自己的文件。
- Java 测试 JUnit5 + Mockito(`@ExtendWith(MockitoExtension.class)`);命令 `cd backend-java && mvn -o test -Dtest=XxxTest`。
- 每个接口的鉴权三步:`requireAdminOrInternal` → `requireClientTaskCenterAccess` → `resolveAccessScope` 裁剪。
---
### Task 1: V138 迁移(device_id 两列 + 菜单行)+ 迁移盘点同步
**Files:**
- Create: `backend-java/src/main/resources/db/V138__client_task_console.sql`
- Modify: `backend-java/docs/migration-inventory.md`
- Test: `backend-java/src/test/java/com/nanri/aiimage/config/MigrationInventoryTest.java`(既有,跑通即可)
**Interfaces:**
- Produces: `biz_file_task.device_id` / `brand_crawl_tasks.device_id`(`VARCHAR(128) NULL`);菜单行 `column_key='admin_task_center'`。
**Steps:**
- [ ] **Step 1: 写迁移文件**(幂等,对齐 V130/V127 写法)
```sql
-- V138: 客户端任务管理(后台看板)——任务记录设备号 + 菜单
--
-- 设备号取自 JWT 签名的 deviceId claim(AdminAuthSupport.currentDeviceId),
-- 由各模块创建入口显式落库;历史任务为 NULL(列表显示「未记录」,不回填)。
-- 品牌检测任务自建 brand_crawl_tasks 表,同样补列。
--
-- 幂等:列/索引/菜单行均仅当不存在时创建。回滚:DROP 两列与索引 + DELETE 菜单行(见文件尾注释)。
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;
-- 菜单:客户端任务管理(挂「记录与版本」分组下;仅插 columns,不写 user_column_permission
-- —— 管理员默认不可见,超管在「用户管理 → 菜单权限」授权后可见)
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');
-- 回滚(手工):
-- 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';
```
- [ ] **Step 2: 跑迁移盘点测试确认变红**(文档还没写 V138)
Run: `cd backend-java && mvn -o test -Dtest=MigrationInventoryTest`
Expected: FAIL —— `inventoryDocCommittedAndConsistent` 断言「文档应记录最新版本 V138」
- [ ] **Step 3: 同步盘点文档**
`backend-java/docs/migration-inventory.md` 更新:文件数 136→137;范围 `V1..V137`→`V1..V138`;
最新版本→`V138__client_task_console.sql`;快照日期→2026-09-28。
- [ ] **Step 4: 再跑,确认全绿**
Run: `cd backend-java && mvn -o test -Dtest=MigrationInventoryTest`
Expected: PASS
- [ ] **Step 5: Commit**
```bash
git add backend-java/src/main/resources/db/V138__client_task_console.sql backend-java/docs/migration-inventory.md
git commit -m "feat(taskcenter): V138 任务设备号列与客户端任务管理菜单"
```
---
### Task 2: 13 个创建入口记录 device_id + 续跑继承
**Files:**
- Modify: `common/security/AdminAuthSupport.java`(加静态 `normalizeDeviceId`)
- Modify: `modules/task/model/entity/FileTaskEntity.java`(加 `deviceId` 字段)
- Modify(每模块:controller 1 行 + service 签名/落库):
- `modules/publish/`(PublishController:46、PublishTaskService.parseAndCreateTask)
- `modules/deletebrand/`(DeleteBrandRunController:59、DeleteBrandRunService.run)
- `modules/productrisk/`(ProductRiskResolveController:139、ProductRiskTaskService.createTask:523)
- `modules/pricetrack/`(PriceTrackController:192、PriceTrackTaskService.createTask:504)
- `modules/shopmatch/`(ShopMatchController:133、ShopMatchTaskService.createTask:441)
- `modules/patroldelete/`(PatrolDeleteController:234、PatrolDeleteTaskService.createTask:282)
- `modules/queryasin/`(QueryAsinTaskController:195、QueryAsinTaskService.createTask:282)
- `modules/withdraw/`(WithdrawTaskController:130、WithdrawTaskService.createTask:169)
- `modules/appearancepatent/`(AppearancePatentController:52、AppearancePatentTaskService.parseAndCreateTask:152)
- `modules/similarasin/`(SimilarAsinController:86、SimilarAsinTaskService.parseAndCreateTask:386)
- `modules/collectdata/`(CollectDataController:46、CollectDataService.parseAndCreateTask:242)
- `modules/shopdatacrawl/`(ShopDataCrawlTaskController:178、ShopDataCrawlTaskService.createTask:552)
- `modules/brand/`(BrandTaskController:64+75、BrandTaskService.createTask:143 / createTaskAndBuildPayload:172)
- Modify: `modules/task/service/TaskResumeService.java:184`(`buildResumeTask` 继承 `original.getDeviceId()`)
- Test: 每模块既有 service 测试补一条 deviceId 落库断言(如 `SimilarAsinTaskServiceParsePreviewTest`)
**Interfaces:**
- Produces: `AdminAuthSupport.normalizeDeviceId(String) → String|null`;service 创建方法新签名统一为 `xxx(request, String deviceId)`(brand 为 `createTask(Long userId, BrandTaskCreateRequest request, String deviceId)`)。
**Steps:**
- [ ] **Step 1: 写失败测试(先取一个模块:similarasin)**
在 `SimilarAsinTaskServiceParsePreviewTest` 加:
```java
@Test
void parseAndCreateTask_recordsSignedDeviceId() {
// mock 既有的 parse 前置(沿用本类既有 setup)
service.parseAndCreateTask(request, "device-abc");
ArgumentCaptor<FileTaskEntity> captor = ArgumentCaptor.forClass(FileTaskEntity.class);
verify(fileTaskMapper).insert(captor.capture());
assertEquals("device-abc", captor.getValue().getDeviceId());
}
@Test
void parseAndCreateTask_blankDeviceIdStoredAsNull() {
service.parseAndCreateTask(request, " ");
ArgumentCaptor<FileTaskEntity> captor = ArgumentCaptor.forClass(FileTaskEntity.class);
verify(fileTaskMapper).insert(captor.capture());
assertNull(captor.getValue().getDeviceId());
}
```
- [ ] **Step 2: 跑测试确认失败**(编译失败:方法不存在 / getter 不存在)
Run: `cd backend-java && mvn -o test -Dtest=SimilarAsinTaskServiceParsePreviewTest`
Expected: FAIL(compile error `cannot find symbol: method parseAndCreateTask(args, String)`)
- [ ] **Step 3: 实现**
`AdminAuthSupport` 加:
```java
/** 归一化设备标识:空白 → null(未记录);否则 trim 后原样。 */
public static String normalizeDeviceId(String deviceId) {
return deviceId == null || deviceId.isBlank() ? null : deviceId.trim();
}
```
`FileTaskEntity` 加:
```java
/** 创建任务的客户端设备(JWT 签名 deviceId claim);历史任务为 null。 */
private String deviceId;
```
每个 service 创建方法:签名加尾参 `String deviceId`,insert 前加
`task.setDeviceId(AdminAuthSupport.normalizeDeviceId(deviceId));`
每个 controller 调用点:注入 `AdminAuthSupport`(多数已有),
`service.createTask(request, adminAuthSupport.currentDeviceId(request))`;
brand 两处 `brandTaskService.createTaskAndBuildPayload(userId, request, adminAuthSupport.currentDeviceId(request))`。
`TaskResumeService.buildResumeTask` 加:`resume.setDeviceId(original.getDeviceId());`
- [ ] **Step 4: 跑 similarasin 测试确认通过**
Run: `cd backend-java && mvn -o test -Dtest=SimilarAsinTaskServiceParsePreviewTest`
Expected: PASS
- [ ] **Step 5: 其余 12 模块同模式补齐(含测试断言)**
每模块一条 `xxx_recordsSignedDeviceId` 断言(captor 捕获 entity 断言 deviceId)。
既有测试调用点补第二参数(用 `""` 或 `"dev-1"`)。
- [ ] **Step 6: 全量编译 + 相关测试**
Run: `cd backend-java && mvn -o test -Dtest='*TaskServiceTest,*Parse*Test,ShopDataCrawlOwnerColumnTest,TaskResumeServiceTest,Brand*Test'`
Expected: PASS(无编译错误,设备断言全绿)
- [ ] **Step 7: Commit**
```bash
git add backend-java/src/main/java/com/nanri/aiimage/common/security/AdminAuthSupport.java \
backend-java/src/main/java/com/nanri/aiimage/modules/{publish,deletebrand,productrisk,pricetrack,shopmatch,patroldelete,queryasin,withdraw,appearancepatent,similarasin,collectdata,shopdatacrawl,brand} \
backend-java/src/main/java/com/nanri/aiimage/modules/task
git commit -m "feat(taskcenter): 13 个客户端任务创建入口记录 JWT 设备号"
```
---
### Task 3: taskcenter 模块骨架 + 权限 + 组裁剪 + overview 接口
**Files:**
- Create: `modules/taskcenter/controller/AdminTaskCenterController.java`
- Create: `modules/taskcenter/service/TaskCenterScopeService.java`
- Create: `modules/taskcenter/service/TaskCenterQueryService.java`
- Create: `modules/taskcenter/mapper/TaskCenterQueryMapper.java`
- Create: `modules/taskcenter/model/vo/TaskCenterOverviewVo.java`
- Modify: `modules/permission/service/PermissionMenuService.java`(加 `requireClientTaskCenterAccess`)
- Test: Create: `backend-java/src/test/java/com/nanri/aiimage/modules/taskcenter/service/TaskCenterScopeServiceTest.java`
**Interfaces:**
- Produces:
- `record ScopeContext(boolean allUsers, Set<Long> visibleUserIds)`;`TaskCenterScopeService.resolve(Long operatorId)`
- `PermissionMenuService.requireClientTaskCenterAccess(AdminUserEntity operator)`(403 或放行)
- `GET /api/admin/task-center/overview` → `{deviceTotal, deviceOnline, runningTasks, todayFinishedTasks, stuckTasks}`
**Steps:**
- [ ] **Step 1: 写失败测试**
```java
@ExtendWith(MockitoExtension.class)
class TaskCenterScopeServiceTest {
@Mock AdminUserMapper adminUserMapper;
@Mock ShopManageGroupMapper shopManageGroupMapper;
@Spy @InjectMocks TaskCenterScopeService service;
@Test
void superAdminSeesAll() { /* role=super_admin → allUsers=true, visibleUserIds 空 */ }
@Test
void adminGetsSelfPlusGroupUsersPlusManaged() {
// 组 [7,8] → users [11,12];managed [13];本人 5 → visible={5,11,12,13}
}
@Test
void adminWithNoGroupHasOnlySelf() { /* visible={本人},不越权 */ }
}
```
Run: `cd backend-java && mvn -o test -Dtest=TaskCenterScopeServiceTest` → FAIL
- [ ] **Step 2: 实现 scope service**
`TaskCenterScopeService.resolve(Long operatorId)`:照抄 `DedupeTotalDataService.resolveAccessScope:1179-1205`
(`getOperator` → `isSuperAdmin`(`DeviceSessionPolicy.resolveRole`)→ `selectAccessibleGroupIds` +
`selectUserIdsByGroupIds` + `selectManagedMemberUserIds`,LinkedHashSet 去重)。
- [ ] **Step 3: 权限方法**
`PermissionMenuService` 加(口径照抄 `requireShopDataCrawlTaskAccess:462`):
```java
/** 「客户端任务管理」菜单访问检查;超管直通。 */
public void requireClientTaskCenterAccess(AdminUserEntity operator) {
ensureAdminOperatorIfPresent(operator);
if (operator == null || operator.getId() == null || operator.getId() <= 0) {
throw new BusinessException(403, "需要管理员权限");
}
if (isSuperAdmin(operator)) {
return;
}
PermissionMenuEntity menu = requireDataPermission("admin_task_center", "客户端任务管理菜单");
if (!hasEffectiveColumnPermission(operator.getId(), menu.getId())) {
throw new BusinessException(403, "无权查看客户端任务管理");
}
}
```
- [ ] **Step 4: controller + overview 查询**
`AdminTaskCenterController`(`@RequestMapping("/api/admin/task-center")`)私有方法
`resolveOperator(request)` = `requireAdminOrInternal` + `requireClientTaskCenterAccess`;
overview = `TaskCenterQueryService.overview(scope)`:
- runningTasks / stuckTasks / todayFinishedTasks:3 条 count SQL(mapper)
- deviceTotal / deviceOnline:复用 Task 4 的设备查询(本任务先返回 0,Task 4 接线)
- [ ] **Step 5: 跑测试 + 手动 curl 契约(本地)**
Run: `cd backend-java && mvn -o test -Dtest=TaskCenterScopeServiceTest`
Expected: PASS
- [ ] **Step 6: Commit**
```bash
git add backend-java/src/main/java/com/nanri/aiimage/modules/taskcenter backend-java/src/main/java/com/nanri/aiimage/modules/permission/service/PermissionMenuService.java backend-java/src/test/java/com/nanri/aiimage/modules/taskcenter
git commit -m "feat(taskcenter): 模块骨架 + 菜单权限 + 组范围裁剪 + overview"
```
---
### Task 4: devices 接口(设备花名册)
**Files:**
- Modify: `modules/taskcenter/mapper/TaskCenterQueryMapper.java`(加 4 条 @Select)
- Modify: `modules/taskcenter/service/TaskCenterQueryService.java`(`devices(scope)` + overview 接线)
- Create: `modules/taskcenter/model/vo/TaskCenterDeviceVo.java`
- Test: `TaskCenterQueryServiceTest`(Mockito mock mapper,断言 Java 侧合并逻辑)
**Interfaces:**
- Produces: `GET /api/admin/task-center/devices` → `List<{deviceId,deviceName,lastActiveAt,online,runningTasks,recentTaskAt}>`
**Steps:**
- [ ] **Step 1: 写失败测试**
```java
@Test void mergeDeviceRoster_taskDeviceAndLogDeviceUnion() { /* 任务设备 + 日志设备并集;同名取日志名 */ }
@Test void onlineThreshold_isFiveMinutes() { /* lastActive 4:59 → online=true;5:01 → false */ }
@Test void blankDeviceIdExcluded() { /* '' / null 不参与 */ }
```
Run: `mvn -o test -Dtest=TaskCenterQueryServiceTest` → FAIL
- [ ] **Step 2: mapper SQL**
```sql
-- 任务设备(近 30 天创建过任务)
SELECT device_id, MAX(updated_at) AS last_active FROM biz_file_task
WHERE device_id IS NOT NULL AND device_id <> '' AND created_at >= #{since} AND user_id IN (...)
GROUP BY device_id
-- 品牌设备同理(brand_crawl_tasks);运行中任务数(两表各一条,status IN 参数化)
-- 日志设备(近 7 天上报)
SELECT device_id, MAX(device_name) AS device_name, MAX(last_upload_at) AS last_upload_at
FROM device_log_file
WHERE source='client' AND last_upload_at >= #{since7} AND uid IN (...)
GROUP BY device_id
```
Java 侧:并集 → 在线 = max(last_upload_at, last_active) ≥ now-5min → 排序(在线优先、名称)。
`web-` 前缀单独标注 `webDevice=true`(前端显示「网页」,不参与设备总数?——参与,但命名区分;总数含网页登录标记的过滤由前端展示层决定,本任务接口照常返回)。
- [ ] **Step 3: overview 的 deviceTotal/deviceOnline 从本查询派生**
- [ ] **Step 4: 跑测试**
Run: `mvn -o test -Dtest=TaskCenterQueryServiceTest` → PASS
- [ ] **Step 5: Commit**
```bash
git add backend-java/src/main/java/com/nanri/aiimage/modules/taskcenter backend-java/src/test/java/com/nanri/aiimage/modules/taskcenter
git commit -m "feat(taskcenter): 设备花名册与在线判定"
```
---
### Task 5: tasks 列表接口(两表 UNION + 筛选 + 店铺/进度装配)
**Files:**
- Modify: `modules/taskcenter/mapper/TaskCenterQueryMapper.java`
- Modify: `modules/taskcenter/service/TaskCenterQueryService.java`
- Create: `modules/taskcenter/model/vo/TaskCenterTaskRowVo.java`、`TaskCenterTaskPageVo.java`
- Test: `TaskCenterQueryServiceTest`
**Interfaces:**
- Produces: `GET /api/admin/task-center/tasks?page&pageSize&username&moduleType&status&deviceId&shop&startTime&endTime`
→ `{items:[TaskCenterTaskRowVo], total, page, pageSize}`
- `TaskCenterTaskRowVo`: `id, taskNo, moduleType, moduleLabel, status, userId, username, deviceId, deviceName, webDevice, shopName, shopCount, createdAt, finishedAt, progressTotal, progressSuccess, progressFailed, currentScope, message, stuck`
**Steps:**
- [ ] **Step 1: 写失败测试(Java 侧装配逻辑)**
```java
@Test void usernameFilterResolvesToUserIdsIntersectVisible(); // users LIKE → ∩ visible;空集 → 空页
@Test void shopFilterExistsClauseIncluded(); // captor 检查 wrapper/参数传递
@Test void stuckFlag_boundary(); // RUNNING 9:59min → false;10:01 → true
@Test void progressFallback_snapshotThenFileCount(); // 快照优先;无快照用文件计数
@Test void moduleLabelUsesRegistry(); // labels() 中文名;BRAND 大写
```
Run: `mvn -o test -Dtest=TaskCenterQueryServiceTest` → FAIL
- [ ] **Step 2: mapper SQL(UNION 主体 + count)**
```sql
SELECT * FROM (
SELECT t.id, t.task_no, t.module_type, t.status, t.user_id, t.device_id,
t.created_at, t.finished_at, t.updated_at,
t.source_file_count AS total_cnt, t.success_file_count AS success_cnt, t.failed_file_count AS failed_cnt,
0 AS is_brand
FROM biz_file_task t
WHERE t.module_type IN (12 个客户端模块)
<if> AND t.user_id IN (...) </if> <if> AND t.module_type = #{moduleType} </if>
<if> AND UPPER(t.status) = #{status} </if> <if> AND t.device_id = #{deviceId} </if>
<if> AND t.created_at >= #{startTime} </if> <if> AND t.created_at <= #{endTime} </if>
<if test="shop != null">
AND ( EXISTS (SELECT 1 FROM biz_publish_file p WHERE p.task_id=t.id AND p.shop_name LIKE CONCAT('%',#{shop},'%'))
OR EXISTS (SELECT 1 FROM biz_task_result_item i WHERE i.task_id=t.id AND i.scope_key LIKE CONCAT('%',#{shop},'%'))
OR EXISTS (SELECT 1 FROM biz_file_result f WHERE f.task_id=t.id AND f.source_filename LIKE CONCAT('%',#{shop},'%'))
OR EXISTS (SELECT 1 FROM biz_task_progress_snapshot s WHERE s.task_id=t.id AND s.current_scope_key LIKE CONCAT('%',#{shop},'%')) )
</if>
UNION ALL
SELECT b.id, CONCAT('brand-', b.id), 'BRAND', UPPER(b.status), b.user_id, b.device_id,
b.created_at,
CASE WHEN b.status IN ('success','failed','cancelled') THEN b.updated_at END,
b.updated_at,
b.progress_total, b.progress_current, 0, 1
FROM brand_crawl_tasks b
WHERE 1=1
<if> 同款过滤(moduleType 非 BRAND 时该分支恒空) </if>
) m
ORDER BY m.created_at DESC, m.id DESC
LIMIT #{limit} OFFSET #{offset}
```
count 同结构(`SELECT (SELECT COUNT(*) ...) + (SELECT COUNT(*) ...) AS total`)。
- [ ] **Step 3: service 装配**
- username → `SELECT id FROM users WHERE username LIKE` → 与 visible 求交;空 → 直接空页
- 当页行批量装配:username(users IN)、deviceName(Task 4 设备名映射)、shop(3 表批量 GROUP_CONCAT:
`SELECT task_id, GROUP_CONCAT(DISTINCT shop) FROM ... WHERE task_id IN (...) GROUP BY task_id`)、
progress(快照 `task_id IN (...)` 批量;缺的行用行内文件计数)、stuck(RUNNING && updated_at < now-10min)
- status 输出已大写(brand 分支 UPPER)
- [ ] **Step 4: 跑测试**
Run: `mvn -o test -Dtest=TaskCenterQueryServiceTest` → PASS
- [ ] **Step 5: Commit**
```bash
git add backend-java/src/main/java/com/nanri/aiimage/modules/taskcenter backend-java/src/test/java/com/nanri/aiimage/modules/taskcenter
git commit -m "feat(taskcenter): 两表 UNION 任务列表 + 筛选 + 店铺/进度装配"
```
---
### Task 6: tasks/detail 详情接口
**Files:**
- Modify: `modules/taskcenter/mapper/TaskCenterQueryMapper.java`、`service/TaskCenterQueryService.java`
- Create: `modules/taskcenter/model/vo/TaskCenterTaskDetailVo.java`
- Test: `TaskCenterQueryServiceTest`
**Interfaces:**
- Produces: `GET /api/admin/task-center/tasks/detail?taskNo=brand-12|PUBLISH-xxx`
→ `{...TaskCenterTaskRowVo 字段, shops:[{scopeKey,total,success,failed}], progress:{...}, errorMessage}`
**Steps:**
- [ ] **Step 1: 写失败测试**
```java
@Test void detailBrandPrefixRoutesToBrandTable(); // brand-12 → brand_crawl_tasks
@Test void detailOutOfScopeDenied(); // user_id 不在 visible → 空/403 语义(按空返回,前端提示)
@Test void detailShopsAggregatedFromResultItem(); // biz_task_result_item 按 scope_key 聚合
```
Run: `mvn -o test -Dtest=TaskCenterQueryServiceTest` → FAIL
- [ ] **Step 2: 实现**
按 `taskNo` 前缀分流:`brand-` → brand 表;否则 biz_file_task(user_id 必须 ∈ visible 或超管)。
shops:`SELECT scope_key, COUNT(*), SUM(status='SUCCESS') ... GROUP BY scope_key`(result_item)+ PUBLISH 走 publish_file GROUP BY shop_name。
progress:快照行 + 文件计数兜底(同 Task 5)。
- [ ] **Step 3: 跑测试 + Commit**
Run: `mvn -o test -Dtest=TaskCenterQueryServiceTest` → PASS
```bash
git add backend-java/src/main/java/com/nanri/aiimage/modules/taskcenter backend-java/src/test/java/com/nanri/aiimage/modules/taskcenter
git commit -m "feat(taskcenter): 任务详情接口"
```
---
### Task 7: variant-tasks 接口(麦象代理)+ MaixiangConsoleClient 扩展
**Files:**
- Modify: `modules/notification/client/MaixiangConsoleClient.java`(BatchTaskItem 加 resMes;加多 uid 分页方法)
- Create: `modules/taskcenter/service/TaskCenterVariantService.java`
- Modify: `modules/taskcenter/controller/AdminTaskCenterController.java`
- Test: `MaixiangConsoleClientTest`(既有测试类扩展)、`TaskCenterVariantServiceTest`
**Interfaces:**
- Produces: `GET /api/admin/task-center/variant-tasks?page&pageSize&status&taskType`
→ `{items:[{taskId,uid,username,status,resMes,taskData,createTime,updateTime}], total, page, pageSize}`
- `MaixiangConsoleClient.batchTasksPage(String uidsCsv, Integer status, String taskType, int page, int pageSize)`
**Steps:**
- [ ] **Step 1: 写失败测试**
```java
@Test void batchTasksPage_buildsUidCsvAndPaging(); // url 含 uid=a,b&page=2&page_size=15
@Test void parseBatchTaskPage_readsResMes(); // items[0].res_mes 解析进 record
@Test void variantService_mapsUidToUsername(); // uid → users.username;不可见 uid 不进结果
```
Run: `mvn -o test -Dtest='MaixiangConsoleClientTest,TaskCenterVariantServiceTest'` → FAIL
- [ ] **Step 2: 实现**
- `BatchTaskItem` 追加 `String resMes`(`node.path("res_mes").asText("")`;`task_data` 原样透传为 JsonNode→String)
- 新方法:`batchTasksPage` 走 `/api/console/batch/tasks`,参数 `uid`(逗号分隔,来自可见用户)、`status`(可空)、`task_type`(可空)、`page/page_size`
- service:可见用户 → uidsCsv;无可见用户直接空页;返回行 uid → username 映射
- 麦象不可达时返回空页 + 记日志(页面不炸)
- [ ] **Step 3: 跑测试 + Commit**
Run: `mvn -o test -Dtest='MaixiangConsoleClientTest,TaskCenterVariantServiceTest'` → PASS
```bash
git add backend-java/src/main/java/com/nanri/aiimage/modules/notification/client/MaixiangConsoleClient.java \
backend-java/src/main/java/com/nanri/aiimage/modules/taskcenter backend-java/src/test/java/com/nanri/aiimage
git commit -m "feat(taskcenter): 变体采集接口(麦象代理,多 uid + res_mes)"
```
---
### Task 8: 麦象侧 `/api/console/batch/tasks` 多 uid 与 res_mes
**Files:**
- Modify: `maixiang_run_task/maixiang_task_api/main.py`(`console_batch_tasks`)
- Test: `maixiang_run_task/tests/`(pytest,若目录不存在则新建 `test_console_batch_tasks.py`)
**Interfaces:**
- Produces(接口契约,Java 侧依赖):
- `uid=A,B` → `IN (A,B)`;缺省/单值语义不变
- items 增加 `res_mes`(str)与 `task_data`(原样)
**Steps:**
- [ ] **Step 1: 写失败测试**
```python
def test_multi_uid_filter(client, db): ... # uid=a,b 只返回 a/b 的任务
def test_single_uid_backward_compat(client, db): ...
def test_items_include_res_mes(client, db): ...
```
Run: `cd maixiang_run_task && python -m pytest maixiang_task_api/tests -k console_batch -q`(或既有测试路径)
Expected: FAIL
- [ ] **Step 2: 实现**
```python
if uid:
uid_list = [u.strip() for u in uid.split(",") if u.strip()]
if len(uid_list) == 1:
query = query.filter(AllTask.uid == uid_list[0])
elif uid_list:
query = query.filter(AllTask.uid.in_(uid_list))
...
items.append({
...既有字段...,
"res_mes": r.res_mes or "",
"task_data": r.task_data,
})
```
- [ ] **Step 3: 跑测试**
Run: `cd maixiang_run_task && python -m pytest maixiang_task_api/tests -k console_batch -q` → PASS
- [ ] **Step 4: Commit**(maixiang_run_task 是否同一 git 仓?否 —— 属工作区非 git 目录,
按发布脚本 `scripts/_deploy_maixiang_api.py` 部署;本地改动记录在提交信息里)
```bash
git add -A # 仅当 maixiang_run_task 在某个 git 仓内;否则跳过 commit,改动由发布脚本上传
```
---
### Task 9: 前端 api + 路由 + 页面骨架(页签/筛选/汇总卡/设备条)
**Files:**
- Create: `admin-frontend-vue/src/api/task-center.ts`
- Create: `admin-frontend-vue/src/pages/task-center/TaskCenterBoardPage.vue`
- Modify: `admin-frontend-vue/src/router/routes.ts`(adminPages 追加)
- Modify: `admin-frontend-vue/src/layout/operation-guides.ts`(补 `admin_task_center`)
- Test: `admin-frontend-vue/src/__tests__/`(或既有测试目录)新增 `TaskCenterBoardPage` 相关
**Interfaces:**
- Consumes: Task 3-7 的 5 个接口
- Produces: 页面路由 `task-center/board`(menuKey `admin_task_center`)
**Steps:**
- [ ] **Step 1: 写失败测试**(对齐既有 vitest 风格)
```ts
it('renders overview metrics after load', ...)
it('switches tab to variant list', ...)
```
Run: `cd admin-frontend-vue && npx vitest run TaskCenter` → FAIL
- [ ] **Step 2: api 文件**
照 `src/api/device-logs.ts` 模式(`http.get` + `unwrap`),导出 5 个函数 + TS 接口。
- [ ] **Step 3: 路由 + guides**
```ts
{ path: 'task-center/board', menuKey: 'admin_task_center', title: '客户端任务管理', load: () => import('@/pages/task-center/TaskCenterBoardPage.vue') },
```
guides:`admin_task_center: { text: '按账号和设备查看客户端任务执行情况;点击设备可筛选该设备任务,点任务查看明细。', steps: ['选择筛选条件', '查看设备与任务', '打开任务详情'] }`
- [ ] **Step 4: 页面骨架**
`TaskCenterBoardPage.vue`:`panel-box` + `.form-row` 筛选(账号输入、业务下拉=模块 labels、状态下拉、设备下拉、店铺输入、时间范围)+ 汇总卡(5 指标)+ 设备卡条 + `el-tabs`(客户端任务 / 变体采集)。
样式类复用 DeviceLogsPage 的全局样式(`btn/btn-ghost/form-row/panel-box`);进度用 CSS 条(无图表库)。
- [ ] **Step 5: 跑测试 + 既有门禁**
Run: `cd admin-frontend-vue && npx vitest run TaskCenter && npx vitest run align-operation-guide`
Expected: PASS(guides 对齐测试绿)
- [ ] **Step 6: Commit**
```bash
git add admin-frontend-vue/src/api/task-center.ts admin-frontend-vue/src/pages/task-center admin-frontend-vue/src/router/routes.ts admin-frontend-vue/src/layout/operation-guides.ts admin-frontend-vue/src/__tests__(相关文件)
git commit -m "feat(taskcenter): 前端页面骨架与接口层"
```
---
### Task 10: 前端任务表格 + 详情抽屉
**Files:**
- Modify: `TaskCenterBoardPage.vue`(+ 可选子组件 `components/`)
**Steps:**
- [ ] **Step 1: 写失败测试**:表格列渲染(账号/设备/店铺/业务/状态/起止/进度)、stuck 标记、点击行打开抽屉
- [ ] **Step 2: 实现**:`el-table` + `el-drawer`(对齐 `ImageVideoTasksPage.vue` 用法);
状态色彩映射沿用 tasks 域归一;设备列显示 `deviceName || 截断 deviceId`,`webDevice` 显示「网页」徽标;
进度列 `成功 X / 总 Y` + CSS 进度条 + 失败红色角标;`stuck` 显示「疑似卡住」黄标
- [ ] **Step 3: 跑测试** → PASS
- [ ] **Step 4: Commit**(同上文件)
---
### Task 11: 前端变体采集页签 + 轮询
**Files:**
- Modify: `TaskCenterBoardPage.vue`
**Steps:**
- [ ] **Step 1: 写失败测试**:变体表渲染 res_mes;30s 轮询在 `document.hidden` 时暂停、卸载清理
- [ ] **Step 2: 实现**:变体表格(账号、任务号、状态、开始/更新时间、进度文字)+ 手动刷新;
轮询用 `setInterval` + `visibilitychange` 监听(对齐既有页面惯例)
- [ ] **Step 3: 跑测试** → PASS
- [ ] **Step 4: Commit**
---
### Task 12: 前端单测补全 + 构建验证
**Files:**
- Test: `admin-frontend-vue/src/**/*.{spec,test}.ts`
**Steps:**
- [ ] **Step 1: 补边界测试**:空数据显示、筛选重置、分页切换、接口失败 toast
- [ ] **Step 2: 构建**
Run: `cd admin-frontend-vue && npx vue-tsc --noEmit && npm run build`(或项目既有 build 命令)
Expected: 无 TS 错误、构建成功
- [ ] **Step 3: Commit**
---
### Task 13: 集成验证 + 发布准备(只交付命令,不执行生产写操作)
**Steps:**
- [ ] **Step 1: 后端全量测试**
Run: `cd backend-java && mvn -o test`
Expected: 与基线一致(既有多路会话遗留红项须先甄别归属)
- [ ] **Step 2: 打包 + 产物自查**
Run: `mvn -o clean package -DskipTests`(约 2.5 分钟,162MB)
自查:python zipfile 读 `BOOT-INF/classes/application.yml` 与 V138 资源是否存在、新 class 是否在包内。
- [ ] **Step 3: 发布前三取证**(见记忆 java-backend-release-path)
1. 新默认值是否被 `application-server.yml`/env 覆盖(本次无新配置键,跳过项说明)
2. 线上跑到哪一笔:用 V138 后探针(`brand_crawl_tasks.device_id` 列存在性)
3. 在飞任务:`docker logs java-server --since 3m | grep -aoiE "appearance-patent|similar-asin"`
- [ ] **Step 4: 交付发布命令清单**(用户执行)
- 麦象:`python scripts/_deploy_maixiang_api.py`(先)
- Java:`GIT_TERMINAL_PROMPT=0 GCM_INTERACTIVE=never GCM_PROVIDER=basic git push origin master` → `python scripts/_deploy_jar_and_restart_both.py <本地jar>`
- 后台前端:`python scripts/_deploy_admin_vue.py`
- 回滚口径:jar 备份 `.bak-*`;前端上一版;菜单行删除。
---
## Self-Review 记录
- Spec 覆盖:13 模块设备记录(T2)、V138(T1)、5 接口(T3-T7)、麦象(T8)、前端(T9-T12)、权限/裁剪(T3)、店铺/进度/卡住口径(T4-T6)、发布(T13)✓
- 类型一致性:`ScopeContext`(T3)→ T4-T7 复用;`TaskCenterTaskRowVo`(T5)→ T6 详情复用;`BatchTaskItem.resMes`(T7)→ 麦象 items.res_mes(T8)契约一致 ✓
- 已知取舍:详情接口越权返回空(不 403),前端提示「任务不存在或无权限」;轮询周期 30s 固定(不做配置)。