# 发型模板制作任务 Implementation Plan

> **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:** 构建真实可用的发型模板制作闭环，支持动态素材、模板制作任务页、step1/step2 AI 编排，以及成功后回写 `hair_template`。

**Architecture:** 后端以 `hair_template` 作为模板实体、以 `hair_template_make_task` 作为制作过程状态源；前端创建模板后进入新的任务详情页，持续轮询本系统后端；后端在任务详情查询时刷新 step1/step2 外部 AI 任务状态并推进下一阶段，避免引入额外的后台 worker。

**Tech Stack:** NestJS 11、Prisma 6、Jest、React 19、React Router 7、Vitest、Testing Library

## Global Constraints

- 数据库语义必须严格遵循 `backend/docs/数据库设计.md` 中的 `hair_template`、`hair_template_make_task`、`system_config` 定义。
- 本次不新增后台常驻 worker、消息队列或定时补偿任务。
- 模板新建页沿用现有 UI 骨架，不做大重构。
- 参考发型图片上传类型固定为 `ai-template-origin-image`。
- 模特、服装、背景都采用“预设或上传二选一”，最终统一提交 URL。
- 模特来自 `system_config.config_group = 'ai-model'`，服装来自 `clothing`，背景来自 `background`。
- step1 模板地址来自 `system_config.config_group = 'template-step1'` 的 `config_value`。
- `backend/src/step2` 只保存静态 `config.json` / `content.json`，运行时文件必须写入系统临时目录。
- step2 成功后才回写 `hair_template.cover_url` 与 `hair_template.template_url`，此前模板不可视为可用模板。
- 前端只轮询本系统后端，不能直连 AI 服务。
- 测试优先覆盖真实回归风险：创建双写、详情推进、前端轮询、动态素材提交。

---

## File Structure

### Backend

- Modify: `backend/prisma/schema.prisma`
  - 补 `SystemConfig` Prisma model，并为模板任务链路补必要的 enum/字段映射引用。
- Modify: `backend/src/modules/templates/templates.module.ts`
  - 注入 `ConfigModule`、`StorageModule`、`PrismaModule`、AI client 和任务 runner。
- Modify: `backend/src/modules/templates/templates.controller.ts`
  - 承载 `GET /templates/assets`、`POST /templates/make-tasks`、`GET /templates/make-tasks/:taskId`、模板列表/详情接口入口。
- Modify: `backend/src/modules/templates/templates.service.ts`
  - 承载素材查询、创建任务、查询任务详情、模板列表/详情查询。
- Create: `backend/src/modules/templates/template-ai.client.ts`
  - 抽象可复用的 `executeTemplate()` 和 `getResult()`。
- Create: `backend/src/modules/templates/template-task-runner.ts`
  - 负责 step1 发起、step1 刷新、step2 组包发起、step2 刷新与回写。
- Create: `backend/src/modules/templates/template-task-files.ts`
  - 负责临时目录、下载文件、复制 step2 静态文件、打 zip、清理目录。
- Create: `backend/src/modules/templates/dto/get-template-assets.dto.ts`
  - 定义素材列表返回 DTO。
- Create: `backend/src/modules/templates/dto/create-template-make-task.dto.ts`
  - 定义创建任务请求 DTO。
- Create: `backend/src/modules/templates/dto/template-make-task-detail.dto.ts`
  - 定义任务详情返回 DTO。
- Create: `backend/src/modules/templates/dto/list-templates-item.dto.ts`
  - 收敛模板列表项含任务状态的返回结构。
- Create: `backend/src/modules/templates/templates.service.spec.ts`
  - 单元测试模板创建、状态推进与失败路径。
- Create: `backend/test/templates.e2e-spec.ts`
  - E2E 覆盖素材接口、创建任务、查询任务详情。

### Frontend

- Modify: `frontend/src/config/routes.ts`
  - 增加模板任务页路由。
- Modify: `frontend/src/App.tsx`
  - 注册新路由。
- Modify: `frontend/src/services/api/contracts.ts`
  - 增加模板素材、创建任务、任务详情相关类型，并为模板列表增加 `makeTaskId` / `makeTaskStatus`。
- Modify: `frontend/src/services/api/templates.ts`
  - 增加 `getTemplateAssets()`、`createTemplateMakeTask()`、`getTemplateMakeTaskById()`。
- Modify: `frontend/src/pages/dashboard/templates/TemplateFormPage.tsx`
  - 改为动态素材与上传切换，提交后跳任务页。
- Create: `frontend/src/pages/dashboard/templates/TemplateMakeTaskPage.tsx`
  - 展示任务进度并轮询。
- Create: `frontend/src/pages/dashboard/templates/__tests__/TemplateFormPage.test.tsx`
  - 覆盖动态素材、上传切换、提交跳转。
- Create: `frontend/src/pages/dashboard/templates/__tests__/TemplateMakeTaskPage.test.tsx`
  - 覆盖处理中轮询、成功停止轮询、失败展示。
- Modify: `frontend/src/pages/dashboard/templates/TemplateListPage.tsx`
  - 根据模板任务状态决定跳任务页或模板详情页。
- Modify: `frontend/src/__tests__/App.test.tsx`
  - 覆盖模板任务页路由。
- Modify: `frontend/src/i18n/locales/zh/translation.json`
- Modify: `frontend/src/i18n/locales/ja/translation.json`
  - 增加任务页、动态素材、失败文案。
- Modify: `frontend/public/css/aitori.css`
  - 追加模板任务页与素材来源切换样式。

## Task 1: 搭好后端模板任务基础设施

**Files:**
- Create: `backend/src/modules/templates/template-ai.client.ts`
- Create: `backend/src/modules/templates/dto/get-template-assets.dto.ts`
- Create: `backend/src/modules/templates/dto/create-template-make-task.dto.ts`
- Create: `backend/src/modules/templates/dto/template-make-task-detail.dto.ts`
- Modify: `backend/prisma/schema.prisma`
- Modify: `backend/src/modules/templates/templates.module.ts`
- Test: `backend/src/modules/templates/templates.service.spec.ts`

**Interfaces:**
- Consumes: `PrismaService`, `ConfigService`, `StorageService`
- Produces: `TemplateAiClient.executeTemplate(template: string, inputs: Record<string, unknown>): Promise<{ taskId: string }>`
- Produces: `TemplateAiClient.getResult(taskId: string): Promise<{ status: 'processing' | 'successes' | 'failed'; message: string; images: string[] }>`
- Produces: `CreateTemplateMakeTaskDto`
- Produces: `TemplateAssetsDto`
- Produces: Prisma model `SystemConfig`

- [ ] **Step 1: 写后端单元测试骨架，锁定将来依赖的接口名**

```ts
describe('TemplatesService', () => {
  it('lists grouped template assets from system_config', async () => {
    const result = await service.getTemplateAssets();

    expect(result).toEqual({
      models: expect.any(Array),
      clothes: expect.any(Array),
      backgrounds: expect.any(Array),
    });
  });
});
```

Run: `cd /Users/yuchen/Documents/hairstylist/backend && npm test -- --runInBand src/modules/templates/templates.service.spec.ts`
Expected: FAIL with `Cannot find module './templates.service.spec.ts'` or missing method/type errors.

- [ ] **Step 2: 在 Prisma schema 中补 `SystemConfig` model**

```prisma
model SystemConfig {
  id          BigInt            @id @default(autoincrement()) @db.UnsignedBigInt
  configKey   String            @map("config_key") @db.VarChar(100)
  configName  String            @map("config_name") @db.VarChar(200)
  configGroup String            @map("config_group") @db.VarChar(50)
  configValue String?           @map("config_value") @db.Text
  valueType   SystemConfigValueType @default(STRING) @map("value_type")
  sort        Int               @default(0)
  remark      String?           @default("") @db.VarChar(500)
  createTime  DateTime          @default(now()) @map("create_time")
  updateTime  DateTime          @updatedAt @map("update_time")
  isDeleted   Int               @default(0) @map("is_deleted") @db.UnsignedTinyInt

  @@unique([configKey, isDeleted], map: "uk_config_key")
  @@index([configGroup, isDeleted], map: "idx_config_group")
  @@map("system_config")
}
```

Run: `cd /Users/yuchen/Documents/hairstylist/backend && npm run prisma:validate`
Expected: PASS with `The schema at prisma/schema.prisma is valid`.

- [ ] **Step 3: 创建模板任务 DTO 与通用 AI client**

```ts
export class CreateTemplateMakeTaskDto {
  @IsString()
  templateName!: string;

  @IsIn(['LONG', 'MEDIUM', 'SHORT', 'DYE'])
  category!: 'LONG' | 'MEDIUM' | 'SHORT' | 'DYE';

  @IsIn(['DRAFT', 'PUBLIC'])
  status!: 'DRAFT' | 'PUBLIC';

  @IsOptional()
  @IsString()
  description?: string;

  @IsOptional()
  @IsArray()
  @IsString({ each: true })
  tags?: string[];

  @IsUrl()
  refHairUrl!: string;

  @IsUrl()
  modelUrl!: string;

  @IsUrl()
  clothesUrl!: string;

  @IsUrl()
  backgroundUrl!: string;
}
```

```ts
@Injectable()
export class TemplateAiClient {
  constructor(private readonly configService: ConfigService) {}

  async executeTemplate(template: string, inputs: Record<string, unknown>) {
    const response = await fetch(`${this.configService.getOrThrow<string>('aiSimulation.baseUrl')}/execute`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ template, inputs }),
    });

    if (!response.ok) {
      throw new ServiceUnavailableException('AI 模板任务创建失败');
    }

    const data = (await response.json()) as { taskId?: string };
    if (!data.taskId) {
      throw new ServiceUnavailableException('AI 模板任务创建失败');
    }

    return { taskId: data.taskId };
  }
}
```

- [ ] **Step 4: 把新依赖接入 `TemplatesModule`**

```ts
@Module({
  imports: [AuthModule, PrismaModule, ConfigModule, StorageModule],
  controllers: [TemplatesController],
  providers: [TemplatesService, TemplateAiClient, TemplateTaskRunner],
})
export class TemplatesModule {}
```

- [ ] **Step 5: 让测试通过到“素材接口可被定义”的程度**

```ts
async getTemplateAssets() {
  return {
    models: [],
    clothes: [],
    backgrounds: [],
  };
}
```

Run: `cd /Users/yuchen/Documents/hairstylist/backend && npm test -- --runInBand src/modules/templates/templates.service.spec.ts`
Expected: PASS for the new skeleton test.

- [ ] **Step 6: 提交本任务**

```bash
cd /Users/yuchen/Documents/hairstylist
git add backend/prisma/schema.prisma backend/src/modules/templates
git commit -m "feat: scaffold template make task backend"
```

## Task 2: 实现后端素材接口与创建任务双写

**Files:**
- Modify: `backend/src/modules/templates/templates.controller.ts`
- Modify: `backend/src/modules/templates/templates.service.ts`
- Modify: `backend/src/modules/templates/templates.service.spec.ts`
- Create: `backend/src/modules/templates/dto/list-templates-item.dto.ts`
- Test: `backend/test/templates.e2e-spec.ts`

**Interfaces:**
- Consumes: `CreateTemplateMakeTaskDto`, `TemplateAiClient.executeTemplate()`
- Produces: `TemplatesService.getTemplateAssets(): Promise<{ models: AssetOptionDto[]; clothes: AssetOptionDto[]; backgrounds: AssetOptionDto[] }>`
- Produces: `TemplatesService.createTemplateMakeTask(stylistId: bigint, dto: CreateTemplateMakeTaskDto): Promise<{ templateId: string; taskId: string; totalTaskId: string; taskStatus: 'WAIT' | 'PROCESSING' | 'FAILED' }>`
- Produces: `GET /api/v1/templates/assets`
- Produces: `POST /api/v1/templates/make-tasks`

- [ ] **Step 1: 先写创建任务单元测试**

```ts
it('creates hair_template and hair_template_make_task, then starts step1', async () => {
  prisma.systemConfig.findMany.mockResolvedValue([
    { id: BigInt(9), configGroup: 'template-step1', configValue: 'https://cdn.example.com/step1.json', isDeleted: 0 },
  ]);
  aiClient.executeTemplate.mockResolvedValue({ taskId: 'step1-task-1' });
  prisma.$transaction.mockImplementation(async (callback) =>
    callback({
      hairTemplate: { create: jest.fn().mockResolvedValue({ id: BigInt(101) }) },
      hairTemplateMakeTask: { create: jest.fn().mockResolvedValue({ id: BigInt(88) }) },
    }),
  );

  const result = await service.createTemplateMakeTask(BigInt(1), dto);

  expect(result).toEqual({
    templateId: '101',
    taskId: '88',
    totalTaskId: expect.stringContaining('tmpl_'),
    taskStatus: 'PROCESSING',
  });
});
```

Run: `cd /Users/yuchen/Documents/hairstylist/backend && npm test -- --runInBand src/modules/templates/templates.service.spec.ts`
Expected: FAIL with `createTemplateMakeTask is not a function` or unmet mock expectations.

- [ ] **Step 2: 实现素材接口**

```ts
async getTemplateAssets() {
  const rows = await this.prisma.systemConfig.findMany({
    where: {
      isDeleted: 0,
      configGroup: { in: ['ai-model', 'clothing', 'background'] },
    },
    orderBy: [{ sort: 'asc' }, { id: 'asc' }],
  });

  const mapRow = (row: SystemConfig) => ({
    id: row.id.toString(),
    name: row.configName,
    url: row.configValue ?? '',
    configKey: row.configKey,
  });

  return {
    models: rows.filter((row) => row.configGroup === 'ai-model').map(mapRow),
    clothes: rows.filter((row) => row.configGroup === 'clothing').map(mapRow),
    backgrounds: rows.filter((row) => row.configGroup === 'background').map(mapRow),
  };
}
```

- [ ] **Step 3: 实现创建任务双写与 step1 发起**

```ts
async createTemplateMakeTask(stylistId: bigint, dto: CreateTemplateMakeTaskDto) {
  const step1Template = await this.getRequiredStep1TemplateUrl();
  const totalTaskId = `tmpl_${Date.now()}_${randomUUID()}`;

  const created = await this.prisma.$transaction(async (tx) => {
    const template = await tx.hairTemplate.create({
      data: {
        templateName: dto.templateName,
        coverUrl: '',
        status: dto.status,
        category: dto.category,
        tags: (dto.tags ?? []).join(','),
        description: dto.description ?? null,
        modelUrl: dto.modelUrl,
        clothesUrl: dto.clothesUrl,
        backgroundUrl: dto.backgroundUrl,
        refHairUrl: dto.refHairUrl,
        hairstylistId: stylistId,
        templateUrl: '',
        isSystemTemplate: 'NO',
      },
    });

    const task = await tx.hairTemplateMakeTask.create({
      data: {
        totalTaskId,
        step1TaskId: '',
        step2TaskId: '',
        taskStatus: 'WAIT',
        templateId: template.id,
        step1Resource: JSON.stringify({ templateUrl: step1Template, lastError: null }),
        step2Resource: JSON.stringify({ uploadedZipUrl: null, lastError: null }),
        refHairUrl: dto.refHairUrl,
        modelUrl: dto.modelUrl,
        clothesUrl: dto.clothesUrl,
        backgroundUrl: dto.backgroundUrl,
      },
    });

    return { template, task };
  });

  const step1 = await this.templateAiClient.executeTemplate(step1Template, {
    image: dto.refHairUrl,
  });

  await this.prisma.hairTemplateMakeTask.update({
    where: { id: created.task.id },
    data: {
      step1TaskId: step1.taskId,
      taskStatus: 'PROCESSING',
      step1Resource: JSON.stringify({ templateUrl: step1Template, lastError: null }),
    },
  });

  return {
    templateId: created.template.id.toString(),
    taskId: created.task.id.toString(),
    totalTaskId,
    taskStatus: 'PROCESSING' as const,
  };
}
```

- [ ] **Step 4: 暴露控制器接口**

```ts
@UseGuards(JwtAuthGuard)
@Controller('templates')
export class TemplatesController {
  @Get('assets')
  assets() {
    return this.templatesService.getTemplateAssets();
  }

  @Post('make-tasks')
  createMakeTask(@Req() request: AuthenticatedRequest, @Body() body: CreateTemplateMakeTaskDto) {
    return this.templatesService.createTemplateMakeTask(BigInt(request.user.stylistId), body);
  }
}
```

- [ ] **Step 5: 补 E2E 测试**

```ts
it('/api/v1/templates/assets (GET) returns grouped asset options', async () => {
  const token = await signToken();

  await prisma.systemConfig.createMany({
    data: [
      { configKey: 'e2e-model', configName: '模特', configGroup: 'ai-model', configValue: 'https://cdn.example.com/model.jpg' },
      { configKey: 'e2e-clothes', configName: '服装', configGroup: 'clothing', configValue: 'https://cdn.example.com/clothes.jpg' },
      { configKey: 'e2e-background', configName: '背景', configGroup: 'background', configValue: 'https://cdn.example.com/background.jpg' },
    ] as never,
  });

  const response = await request(app.getHttpServer())
    .get('/api/v1/templates/assets')
    .set('Authorization', `Bearer ${token}`)
    .expect(200);

  expect(response.body.data.models[0]).toMatchObject({ name: '模特' });
});
```

```ts
it('/api/v1/templates/make-tasks (POST) creates template and task rows', async () => {
  const token = await signToken();
  executeTemplate.mockResolvedValueOnce({ taskId: 'template-e2e-step1' });

  const response = await request(app.getHttpServer())
    .post('/api/v1/templates/make-tasks')
    .set('Authorization', `Bearer ${token}`)
    .send({
      templateName: 'e2e-template',
      category: 'LONG',
      status: 'DRAFT',
      refHairUrl: 'https://cdn.example.com/ref.jpg',
      modelUrl: 'https://cdn.example.com/model.jpg',
      clothesUrl: 'https://cdn.example.com/clothes.jpg',
      backgroundUrl: 'https://cdn.example.com/background.jpg',
    })
    .expect(201);

  expect(response.body.data.taskStatus).toBe('PROCESSING');
});
```

Run: `cd /Users/yuchen/Documents/hairstylist/backend && npm test -- --runInBand src/modules/templates/templates.service.spec.ts && npm run test:e2e -- templates.e2e-spec.ts`
Expected: PASS for assets/create task tests.

- [ ] **Step 6: 提交本任务**

```bash
cd /Users/yuchen/Documents/hairstylist
git add backend/src/modules/templates backend/test/templates.e2e-spec.ts
git commit -m "feat: add template make task creation APIs"
```

## Task 3: 实现 step1/step2 推进、zip 组装与任务详情接口

**Files:**
- Create: `backend/src/modules/templates/template-task-files.ts`
- Create: `backend/src/modules/templates/template-task-runner.ts`
- Modify: `backend/src/modules/templates/templates.service.ts`
- Modify: `backend/src/modules/templates/templates.controller.ts`
- Modify: `backend/src/modules/templates/templates.service.spec.ts`
- Modify: `backend/test/templates.e2e-spec.ts`

**Interfaces:**
- Consumes: `TemplateAiClient.getResult()`, `StorageService.uploadBuffer()`
- Produces: `TemplateTaskRunner.refreshTask(stylistId: bigint, taskId: string): Promise<TemplateMakeTaskDetailDto>`
- Produces: `GET /api/v1/templates/make-tasks/:taskId`
- Produces: helper `prepareStep2Bundle(input: PrepareStep2BundleInput): Promise<{ zipUrl: string; localFiles: Record<string, string> }>`

- [ ] **Step 1: 先写任务推进单元测试**

```ts
it('promotes a task from PROCESSING to STEP1_SUCCESS when step1 finishes', async () => {
  prisma.hairTemplateMakeTask.findFirst.mockResolvedValue({
    id: BigInt(88),
    templateId: BigInt(101),
    taskStatus: 'PROCESSING',
    step1TaskId: 'step1-task-1',
    step2TaskId: '',
    step1ResultImg: '',
    refHairUrl: 'https://cdn.example.com/ref.jpg',
    modelUrl: 'https://cdn.example.com/model.jpg',
    clothesUrl: 'https://cdn.example.com/clothes.jpg',
    backgroundUrl: 'https://cdn.example.com/background.jpg',
    step1Resource: JSON.stringify({ templateUrl: 'https://cdn.example.com/step1.json' }),
    step2Resource: JSON.stringify({}),
    updateTime: new Date(Date.now() - 20_000),
  });
  aiClient.getResult.mockResolvedValue({
    status: 'successes',
    message: '',
    images: ['https://cdn.example.com/step1-result.jpg'],
  });
  fileRunner.downloadToTempFile.mockResolvedValue('/tmp/task-1/hairstyle.jpg');

  const detail = await service.getTemplateMakeTaskDetail(BigInt(1), '88');

  expect(prisma.hairTemplateMakeTask.update).toHaveBeenCalledWith(
    expect.objectContaining({
      data: expect.objectContaining({
        taskStatus: 'STEP1_SUCCESS',
        step1ResultImg: 'https://cdn.example.com/step1-result.jpg',
      }),
    }),
  );
  expect(detail.step1.resultImage).toBe('https://cdn.example.com/step1-result.jpg');
});
```

Run: `cd /Users/yuchen/Documents/hairstylist/backend && npm test -- --runInBand src/modules/templates/templates.service.spec.ts`
Expected: FAIL because `getTemplateMakeTaskDetail` and file helpers are missing.

- [ ] **Step 2: 实现临时文件和 zip 组装 helper**

```ts
export async function prepareStep2Bundle(input: PrepareStep2BundleInput) {
  const workDir = await mkdtemp(join(tmpdir(), `template-make-${input.totalTaskId}-`));

  await copyFile(input.step2ConfigPath, join(workDir, 'config.json'));
  await copyFile(input.step2ContentPath, join(workDir, 'content.json'));
  await downloadFile(input.step1ResultImg, join(workDir, 'hairstyle.jpg'));
  await downloadFile(input.clothesUrl, join(workDir, 'input-outfit.jpg'));
  await downloadFile(input.backgroundUrl, join(workDir, 'input-background.jpg'));

  const zipPath = join(workDir, 'template.zip');
  await zipDirectory(workDir, zipPath, ['template.zip']);

  return {
    workDir,
    zipPath,
    localFiles: {
      step1Image: join(workDir, 'hairstyle.jpg'),
      clothes: join(workDir, 'input-outfit.jpg'),
      background: join(workDir, 'input-background.jpg'),
      zip: zipPath,
    },
  };
}
```

- [ ] **Step 3: 实现 `TemplateTaskRunner.refreshTask()`**

```ts
async refreshTask(stylistId: bigint, taskId: string) {
  const task = await this.getOwnedTask(stylistId, taskId);

  if (task.taskStatus === 'WAIT') {
    return this.tryStartStep1(task);
  }

  if (task.taskStatus === 'PROCESSING' && task.step1TaskId && !task.step1ResultImg) {
    return this.refreshStep1(task);
  }

  if (task.taskStatus === 'STEP1_SUCCESS' && !task.step2TaskId) {
    return this.startStep2(task);
  }

  if (task.taskStatus === 'PROCESSING' && task.step2TaskId) {
    return this.refreshStep2(task);
  }

  return this.buildDetail(task);
}
```

- [ ] **Step 4: 在 step2 成功时回写 `hair_template`**

```ts
await this.prisma.$transaction([
  this.prisma.hairTemplate.update({
    where: { id: task.templateId! },
    data: {
      coverUrl: resultImage,
      templateUrl: uploadedZipUrl,
    },
  }),
  this.prisma.hairTemplateMakeTask.update({
    where: { id: task.id },
    data: {
      taskStatus: 'STEP2_SUCCESS',
      step2ResultImg: resultImage,
      step2Resource: JSON.stringify({
        uploadedZipUrl,
        resultImage,
        lastError: null,
      }),
    },
  }),
]);
```

- [ ] **Step 5: 暴露详情接口并补 e2e**

```ts
@Get('make-tasks/:taskId')
detail(@Req() request: AuthenticatedRequest, @Param('taskId') taskId: string) {
  return this.templatesService.getTemplateMakeTaskDetail(BigInt(request.user.stylistId), taskId);
}
```

```ts
it('/api/v1/templates/make-tasks/:taskId (GET) promotes step1 and step2 states', async () => {
  getResult
    .mockResolvedValueOnce({ status: 'successes', message: '', images: ['https://cdn.example.com/step1.jpg'] })
    .mockResolvedValueOnce({ status: 'successes', message: '', images: ['https://cdn.example.com/final-cover.jpg'] });

  const response = await request(app.getHttpServer())
    .get(`/api/v1/templates/make-tasks/${taskId}`)
    .set('Authorization', `Bearer ${token}`)
    .expect(200);

  expect(response.body.data.taskStatus).toMatch(/STEP1_SUCCESS|PROCESSING|STEP2_SUCCESS/);
});
```

Run: `cd /Users/yuchen/Documents/hairstylist/backend && npm test -- --runInBand src/modules/templates/templates.service.spec.ts && npm run test:e2e -- templates.e2e-spec.ts`
Expected: PASS for step promotion, bundle upload, and detail endpoint tests.

- [ ] **Step 6: 提交本任务**

```bash
cd /Users/yuchen/Documents/hairstylist
git add backend/src/modules/templates backend/test/templates.e2e-spec.ts
git commit -m "feat: add template make task polling workflow"
```

## Task 4: 接入前端 API、路由与任务页骨架

**Files:**
- Modify: `frontend/src/config/routes.ts`
- Modify: `frontend/src/App.tsx`
- Modify: `frontend/src/services/api/contracts.ts`
- Modify: `frontend/src/services/api/templates.ts`
- Create: `frontend/src/pages/dashboard/templates/TemplateMakeTaskPage.tsx`
- Modify: `frontend/src/__tests__/App.test.tsx`

**Interfaces:**
- Consumes: `GET /templates/assets`, `POST /templates/make-tasks`, `GET /templates/make-tasks/:taskId`
- Produces: `TemplateAssetOption`, `TemplateMakeTaskCreateResult`, `TemplateMakeTaskDetail`
- Produces: route `/:locale/templates/tasks/:taskId`

- [ ] **Step 1: 先写前端路由测试**

```tsx
it('renders template make task route', async () => {
  window.history.replaceState({}, '', '/zh/templates/tasks/88');

  render(<App />);

  await waitFor(() => {
    expect(screen.getByText('template-make-task-page')).toBeInTheDocument();
  });
});
```

Run: `cd /Users/yuchen/Documents/hairstylist/frontend && npm test -- src/__tests__/App.test.tsx`
Expected: FAIL because the new page route is not registered.

- [ ] **Step 2: 扩展 contracts 与 API 方法**

```ts
export type TemplateAssetOption = {
  id: string;
  name: string;
  url: string;
  configKey: string;
};

export type TemplateMakeTaskDetail = {
  id: string;
  templateId: string;
  templateName: string;
  taskStatus: 'WAIT' | 'PROCESSING' | 'STEP1_SUCCESS' | 'STEP2_SUCCESS' | 'FAILED';
  errorMessage: string | null;
  createTime: string;
  refHairUrl: string;
  modelUrl: string;
  clothesUrl: string;
  backgroundUrl: string;
  step1: {
    taskId: string;
    status: string;
    templateUrl: string | null;
    resultImage: string | null;
  };
  step2: {
    taskId: string;
    status: string;
    bundleUrl: string | null;
    resultImage: string | null;
  };
  template: {
    coverUrl: string;
    templateUrl: string;
    status: 'DRAFT' | 'PUBLIC';
  };
};

export type TemplateEntity = {
  id: string;
  name: string;
  category: string;
  status: string;
  description: string;
  tags: string[];
  image?: string;
  makeTaskId?: string;
  makeTaskStatus?: 'WAIT' | 'PROCESSING' | 'STEP1_SUCCESS' | 'STEP2_SUCCESS' | 'FAILED';
  templateUrl?: string;
};
```

```ts
export async function getTemplateAssets() {
  return http.get<{ models: TemplateAssetOption[]; clothes: TemplateAssetOption[]; backgrounds: TemplateAssetOption[] }>('/templates/assets');
}

export async function createTemplateMakeTask(input: CreateTemplateMakeTaskInput) {
  return http.post<TemplateMakeTaskCreateResult>('/templates/make-tasks', input);
}

export async function getTemplateMakeTaskById(taskId: string) {
  return http.get<TemplateMakeTaskDetail>(`/templates/make-tasks/${encodeURIComponent(taskId)}`);
}
```

- [ ] **Step 3: 注册路由与占位页面**

```tsx
export function TemplateMakeTaskPage() {
  return <div>template-make-task-page</div>;
}
```

```tsx
<Route
  path={routes.templateTaskDetail}
  element={
    <RequireAuth>
      <TemplateMakeTaskPage />
    </RequireAuth>
  }
/>
```

```ts
templateTaskDetail: '/:locale/templates/tasks/:taskId',
```

- [ ] **Step 4: 让路由测试通过**

Run: `cd /Users/yuchen/Documents/hairstylist/frontend && npm test -- src/__tests__/App.test.tsx`
Expected: PASS with the new route rendered.

- [ ] **Step 5: 提交本任务**

```bash
cd /Users/yuchen/Documents/hairstylist
git add frontend/src/config/routes.ts frontend/src/App.tsx frontend/src/services/api frontend/src/pages/dashboard/templates/TemplateMakeTaskPage.tsx frontend/src/__tests__/App.test.tsx
git commit -m "feat: scaffold template make task frontend route"
```

## Task 5: 改造模板新建页为动态素材与任务跳转

**Files:**
- Modify: `frontend/src/pages/dashboard/templates/TemplateFormPage.tsx`
- Create: `frontend/src/pages/dashboard/templates/__tests__/TemplateFormPage.test.tsx`
- Modify: `frontend/src/services/api/media.ts`
- Modify: `frontend/src/i18n/locales/zh/translation.json`
- Modify: `frontend/src/i18n/locales/ja/translation.json`
- Modify: `frontend/public/css/aitori.css`

**Interfaces:**
- Consumes: `uploadMedia(file, type)`, `getTemplateAssets()`, `createTemplateMakeTask()`
- Produces: form submit payload `{ templateName, category, status, description, tags, refHairUrl, modelUrl, clothesUrl, backgroundUrl }`
- Produces: custom upload media type `ai-template-origin-image`

- [ ] **Step 1: 先写模板新建页测试**

```tsx
it('loads dynamic assets, uploads custom files, and redirects to the task page', async () => {
  getTemplateAssets.mockResolvedValue({
    models: [{ id: 'm1', name: '模特A', url: 'https://cdn.example.com/model-a.jpg', configKey: 'm1' }],
    clothes: [{ id: 'c1', name: '服装A', url: 'https://cdn.example.com/clothes-a.jpg', configKey: 'c1' }],
    backgrounds: [{ id: 'b1', name: '背景A', url: 'https://cdn.example.com/background-a.jpg', configKey: 'b1' }],
  });
  uploadMedia.mockResolvedValue({ url: 'https://cdn.example.com/uploaded-model.jpg' });
  createTemplateMakeTask.mockResolvedValue({ taskId: '88', templateId: '101', totalTaskId: 'tmpl_x', taskStatus: 'PROCESSING' });

  render(<TemplateFormPage />);

  expect(await screen.findByText('模特A')).toBeInTheDocument();
  await userEvent.click(screen.getByRole('radio', { name: '上传自定义模特' }));
  await userEvent.upload(screen.getByLabelText('上传模特图片'), new File(['x'], 'model.jpg', { type: 'image/jpeg' }));
  await userEvent.click(screen.getByRole('button', { name: 'AI生成' }));

  await waitFor(() => {
    expect(createTemplateMakeTask).toHaveBeenCalledWith(expect.objectContaining({
      modelUrl: 'https://cdn.example.com/uploaded-model.jpg',
    }));
    expect(navigate).toHaveBeenCalledWith('/zh/templates/tasks/88');
  });
});
```

Run: `cd /Users/yuchen/Documents/hairstylist/frontend && npm test -- src/pages/dashboard/templates/__tests__/TemplateFormPage.test.tsx`
Expected: FAIL because `getTemplateAssets` and task redirect behavior do not exist.

- [ ] **Step 2: 调整上传类型和素材加载逻辑**

```ts
const [assets, setAssets] = useState<{ models: TemplateAssetOption[]; clothes: TemplateAssetOption[]; backgrounds: TemplateAssetOption[] }>({
  models: [],
  clothes: [],
  backgrounds: [],
});

useEffect(() => {
  getTemplateAssets().then(setAssets).catch(() => setAssets({ models: [], clothes: [], backgrounds: [] }));
}, []);

const referenceImage = (await uploadMedia(referenceFile, 'ai-template-origin-image')).url;
```

- [ ] **Step 3: 为模特、服装、背景增加“预设/上传”切换**

```tsx
type AssetSource = 'preset' | 'upload';

const [modelSource, setModelSource] = useState<AssetSource>('preset');
const [uploadedModelUrl, setUploadedModelUrl] = useState('');

const finalModelUrl =
  modelSource === 'upload'
    ? uploadedModelUrl
    : assets.models.find((item) => item.id === selectedModelId)?.url ?? '';
```

```tsx
<button type="button" onClick={() => setModelSource('preset')}>使用预设</button>
<button type="button" onClick={() => setModelSource('upload')}>上传自定义模特</button>
```

- [ ] **Step 4: 改为调用创建任务接口并跳任务页**

```ts
const task = await createTemplateMakeTask({
  templateName: name,
  category:
    category === 'Long'
      ? 'LONG'
      : category === 'Medium'
        ? 'MEDIUM'
        : category === 'Short'
          ? 'SHORT'
          : 'DYE',
  status: status === 'Published' ? 'PUBLIC' : 'DRAFT',
  description,
  tags: tags.split(',').map((tag) => tag.trim()).filter(Boolean),
  refHairUrl: referenceImage,
  modelUrl: finalModelUrl,
  clothesUrl: finalClothesUrl,
  backgroundUrl: finalBackgroundUrl,
});

navigate(path(`/templates/tasks/${task.taskId}`));
```

- [ ] **Step 5: 更新文案与样式**

```json
"assetSource": {
  "preset": "使用预设",
  "upload": "上传自定义"
}
```

```css
.template-source-toggle {
  display: flex;
  gap: 12px;
  margin-bottom: 16px;
}
```

- [ ] **Step 6: 运行测试**

Run: `cd /Users/yuchen/Documents/hairstylist/frontend && npm test -- src/pages/dashboard/templates/__tests__/TemplateFormPage.test.tsx && npm run typecheck`
Expected: PASS with dynamic asset and redirect behavior verified.

- [ ] **Step 7: 提交本任务**

```bash
cd /Users/yuchen/Documents/hairstylist
git add frontend/src/pages/dashboard/templates/TemplateFormPage.tsx frontend/src/pages/dashboard/templates/__tests__/TemplateFormPage.test.tsx frontend/src/services/api/media.ts frontend/src/i18n/locales frontend/public/css/aitori.css
git commit -m "feat: wire template form to make task flow"
```

## Task 6: 完成模板任务页轮询与模板列表跳转分流

**Files:**
- Modify: `frontend/src/pages/dashboard/templates/TemplateMakeTaskPage.tsx`
- Create: `frontend/src/pages/dashboard/templates/__tests__/TemplateMakeTaskPage.test.tsx`
- Modify: `frontend/src/pages/dashboard/templates/TemplateListPage.tsx`
- Modify: `frontend/src/i18n/locales/zh/translation.json`
- Modify: `frontend/src/i18n/locales/ja/translation.json`
- Modify: `frontend/public/css/aitori.css`

**Interfaces:**
- Consumes: `getTemplateMakeTaskById(taskId: string): Promise<TemplateMakeTaskDetail>`
- Consumes: `TemplateEntity.makeTaskId?: string`
- Consumes: `TemplateEntity.makeTaskStatus?: 'WAIT' | 'PROCESSING' | 'STEP1_SUCCESS' | 'STEP2_SUCCESS' | 'FAILED'`
- Produces: processing poll interval `1500ms`
- Produces: list item navigation rule `makeTaskStatus in ('WAIT','PROCESSING','STEP1_SUCCESS','FAILED') -> /templates/tasks/:makeTaskId`

- [ ] **Step 1: 先写任务页轮询测试**

```tsx
it('polls until the task reaches STEP2_SUCCESS and then shows the detail CTA', async () => {
  vi.useFakeTimers();
  getTemplateMakeTaskById
    .mockResolvedValueOnce({
      id: '88',
      templateId: '101',
      templateName: '柔和层次长发',
      taskStatus: 'PROCESSING',
      errorMessage: null,
      createTime: '2026-06-28T12:00:00.000Z',
      refHairUrl: 'https://cdn.example.com/ref.jpg',
      modelUrl: 'https://cdn.example.com/model.jpg',
      clothesUrl: 'https://cdn.example.com/clothes.jpg',
      backgroundUrl: 'https://cdn.example.com/background.jpg',
      step1: { taskId: 'step1', status: 'PROCESSING', templateUrl: 'https://cdn.example.com/step1.json', resultImage: null },
      step2: { taskId: '', status: 'WAIT', bundleUrl: null, resultImage: null },
      template: { coverUrl: '', templateUrl: '', status: 'DRAFT' },
    })
    .mockResolvedValueOnce({
      id: '88',
      templateId: '101',
      templateName: '柔和层次长发',
      taskStatus: 'STEP2_SUCCESS',
      errorMessage: null,
      createTime: '2026-06-28T12:00:00.000Z',
      refHairUrl: 'https://cdn.example.com/ref.jpg',
      modelUrl: 'https://cdn.example.com/model.jpg',
      clothesUrl: 'https://cdn.example.com/clothes.jpg',
      backgroundUrl: 'https://cdn.example.com/background.jpg',
      step1: { taskId: 'step1', status: 'STEP1_SUCCESS', templateUrl: 'https://cdn.example.com/step1.json', resultImage: 'https://cdn.example.com/step1.jpg' },
      step2: { taskId: 'step2', status: 'STEP2_SUCCESS', bundleUrl: 'https://cdn.example.com/template.zip', resultImage: 'https://cdn.example.com/final.jpg' },
      template: { coverUrl: 'https://cdn.example.com/final.jpg', templateUrl: 'https://cdn.example.com/template.zip', status: 'DRAFT' },
    });

  render(<TemplateMakeTaskPage />);

  await act(async () => {
    await Promise.resolve();
  });

  await act(async () => {
    await vi.advanceTimersByTimeAsync(1500);
  });

  expect(getTemplateMakeTaskById).toHaveBeenCalledTimes(2);
  expect(screen.getByRole('link', { name: '查看模板详情' })).toBeInTheDocument();
});
```

Run: `cd /Users/yuchen/Documents/hairstylist/frontend && npm test -- src/pages/dashboard/templates/__tests__/TemplateMakeTaskPage.test.tsx`
Expected: FAIL because the page is still a stub.

- [ ] **Step 2: 实现任务页轮询和状态渲染**

```tsx
useEffect(() => {
  let cancelled = false;
  let timer: number | undefined;

  const load = async () => {
    const data = await getTemplateMakeTaskById(params.taskId!);
    if (cancelled) return;
    setTask(data);

    if (['WAIT', 'PROCESSING', 'STEP1_SUCCESS'].includes(data.taskStatus)) {
      timer = window.setTimeout(() => {
        void load();
      }, 1500);
    }
  };

  void load();

  return () => {
    cancelled = true;
    if (timer) window.clearTimeout(timer);
  };
}, [params.taskId]);
```

```tsx
{task.taskStatus === 'STEP2_SUCCESS' ? (
  <Link to={path(`/templates/${task.templateId}`)} className="btn btn-large btn-rounded btn-base-color">
    {pageCopy.actions.viewTemplate}
  </Link>
) : null}
```

- [ ] **Step 3: 为模板列表增加跳转分流**

```tsx
const getTemplateTarget = (template: TemplateEntity) => {
  if (
    template.makeTaskId &&
    ['WAIT', 'PROCESSING', 'STEP1_SUCCESS', 'FAILED'].includes(template.makeTaskStatus ?? '')
  ) {
    return path(`/templates/tasks/${template.makeTaskId}`);
  }

  return path(`/templates/${template.id}`);
};
```

```tsx
<Link to={getTemplateTarget(template)} className="d-block text-decoration-none">
```

- [ ] **Step 4: 更新任务页文案与样式**

```json
"templateTaskPage": {
  "title": "模板制作任务",
  "actions": {
    "viewTemplate": "查看模板详情"
  }
}
```

```css
.template-task-layout {
  display: grid;
  grid-template-columns: minmax(0, 380px) minmax(0, 1fr);
  gap: 24px;
}

.template-task-step-card.is-success {
  border-color: rgba(82, 196, 26, 0.28);
}
```

- [ ] **Step 5: 跑前端回归测试**

Run: `cd /Users/yuchen/Documents/hairstylist/frontend && npm test -- src/pages/dashboard/templates/__tests__/TemplateMakeTaskPage.test.tsx src/__tests__/App.test.tsx && npm run typecheck`
Expected: PASS with polling and routing behavior verified.

- [ ] **Step 6: 提交本任务**

```bash
cd /Users/yuchen/Documents/hairstylist
git add frontend/src/pages/dashboard/templates/TemplateMakeTaskPage.tsx frontend/src/pages/dashboard/templates/TemplateListPage.tsx frontend/src/pages/dashboard/templates/__tests__/TemplateMakeTaskPage.test.tsx frontend/src/i18n/locales frontend/public/css/aitori.css
git commit -m "feat: add template make task page"
```

## Task 7: 全量验证、文档同步与收尾

**Files:**
- Modify: `docs/superpowers/specs/2026-06-28-template-make-task-design.md` (only if implementation diverges)
- Modify: `backend/docs/数据库设计.md` (only if doc drift is found and user-approved)

**Interfaces:**
- Consumes: all prior tasks
- Produces: verified working feature branch state

- [ ] **Step 1: 运行后端验证**

Run: `cd /Users/yuchen/Documents/hairstylist/backend && npm run lint && npm test -- --runInBand src/modules/templates/templates.service.spec.ts && npm run test:e2e -- templates.e2e-spec.ts`
Expected: PASS for lint, unit tests, and e2e tests.

- [ ] **Step 2: 运行前端验证**

Run: `cd /Users/yuchen/Documents/hairstylist/frontend && npm run typecheck && npm test -- src/pages/dashboard/templates/__tests__/TemplateFormPage.test.tsx src/pages/dashboard/templates/__tests__/TemplateMakeTaskPage.test.tsx src/__tests__/App.test.tsx`
Expected: PASS for typecheck and targeted template flow tests.

- [ ] **Step 3: 手动冒烟检查**

```text
1. 登录后台并打开 /zh/templates/new
2. 选择预设模特，上传自定义服装与背景，提交任务
3. 确认页面跳转到 /zh/templates/tasks/:taskId
4. 观察 step1 -> step2 状态推进
5. 成功后点击“查看模板详情”进入模板详情页
6. 在模板列表里确认该模板卡片可进入正确页面
```

Expected: 整条链路无阻塞，成功产出封面图与模板包 URL。

- [ ] **Step 4: 如实现偏离 spec，则同步更新文档**

```md
- 若最终接口字段或任务页文案与 spec 不一致，立即更新 `docs/superpowers/specs/2026-06-28-template-make-task-design.md`
- 若数据库文档存在新增事实字段或语义修正，先确认后再更新 `backend/docs/数据库设计.md`
```

- [ ] **Step 5: 提交收尾**

```bash
cd /Users/yuchen/Documents/hairstylist
git add .
git commit -m "feat: finish template make task flow"
```

## Self-Review Checklist

- Spec coverage:
  - 动态素材接口 -> Task 2
  - 创建模板双写 -> Task 2
  - step1/step2 推进、zip 上传、回写模板 -> Task 3
  - 前端新任务页、轮询 -> Task 4 / Task 6
  - 模板新建页动态素材与跳转 -> Task 5
  - 模板列表跳转分流 -> Task 6
  - 验证与文档同步 -> Task 7
- Placeholder scan:
  - 未使用 `TBD`、`TODO`、`later`
  - 每个任务包含明确文件、接口、命令和预期结果
- Type consistency:
  - 统一使用 `CreateTemplateMakeTaskDto` / `TemplateMakeTaskDetail`
  - 统一使用 `TemplateAiClient.executeTemplate()` / `getResult()`
  - 路由统一为 `/:locale/templates/tasks/:taskId`