`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」, 代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红), 跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
32 KiB
客户端任务管理(后台看板)实现计划
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(menuKeyadmin_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)
- 新默认值是否被
application-server.yml/env 覆盖(本次无新配置键,跳过项说明) - 线上跑到哪一笔:用 V138 后探针(
brand_crawl_tasks.device_id列存在性) - 在飞任务:
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 固定(不做配置)。