# 客户端任务管理(后台看板)实现计划 > **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 captor = ArgumentCaptor.forClass(FileTaskEntity.class); verify(fileTaskMapper).insert(captor.capture()); assertEquals("device-abc", captor.getValue().getDeviceId()); } @Test void parseAndCreateTask_blankDeviceIdStoredAsNull() { service.parseAndCreateTask(request, " "); ArgumentCaptor 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 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 个客户端模块) AND t.user_id IN (...) AND t.module_type = #{moduleType} AND UPPER(t.status) = #{status} AND t.device_id = #{deviceId} AND t.created_at >= #{startTime} AND t.created_at <= #{endTime} 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},'%')) ) 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 同款过滤(moduleType 非 BRAND 时该分支恒空) ) 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 固定(不做配置)。