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

32 KiB
Raw Blame History

客户端任务管理(后台看板)实现计划

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 写法)
-- 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
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 加:

@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 加:

/** 归一化设备标识:空白 → null(未记录);否则 trim 后原样。 */
public static String normalizeDeviceId(String deviceId) {
    return deviceId == null || deviceId.isBlank() ? null : deviceId.trim();
}

FileTaskEntity 加:

/** 创建任务的客户端设备(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
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: 写失败测试
@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):

/** 「客户端任务管理」菜单访问检查;超管直通。 */
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
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: 写失败测试
@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
-- 任务设备(近 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
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 侧装配逻辑)
@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)
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
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: 写失败测试
@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

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: 写失败测试
@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

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: 写失败测试
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: 实现
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 部署;本地改动记录在提交信息里)
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 风格)
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
{ 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
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 固定(不做配置)。