49c3fc1491
`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」, 代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红), 跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
720 lines
32 KiB
Markdown
720 lines
32 KiB
Markdown
# 客户端任务管理(后台看板)实现计划
|
||
|
||
> **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 固定(不做配置)。
|