# Story 11.8: 创建测试渠道（可选）

Status: done

<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->

## Story

作为测试开发者，
我想要编写创建渠道的 E2E 测试（可选），
以便验证渠道创建功能（如需要）。

**注意：** 此 Story 标记为"可选"，原因：
1. Channel 是订单的可选字段（订单创建时不需要选择渠道）
2. 不阻塞其他 Epic 的开发
3. 可在有额外时间时实现

## Acceptance Criteria

1. **AC1: 基本创建渠道测试**
   - 测试文件路径: `web/tests/e2e/specs/admin/channel-create.spec.ts`
   - 使用 ChannelManagementPage（已在 Story 11.7 完成）
   - 验证填写渠道名称后可以成功创建
   - 验证创建成功后渠道出现在列表中
   - 测试结束后清理测试数据

2. **AC2: 完整表单字段测试**
   - 测试填写所有可选字段（渠道类型、联系人、联系电话、描述）
   - 验证所有填写的字段数据正确保存
   - 验证渠道列表正确显示所有信息

3. **AC3: 表单验证测试**
   - 测试未填写渠道名称时的表单验证
   - 测试取消创建操作
   - 测试关闭对话框取消创建

4. **AC4: 对话框元素验证**
   - 验证创建渠道对话框的所有字段存在
   - 验证必填和可选字段正确标识

5. **AC5: 数据唯一性测试**
   - 验证不同测试使用不同的渠道名称（避免冲突）
   - 使用时间戳确保唯一性

## Tasks / Subtasks

- [x] 任务 1: 创建测试文件和基础结构 (AC: 1, 5)
  - [x] 创建文件 `web/tests/e2e/specs/admin/channel-create.spec.ts`
  - [x] 导入测试依赖和 ChannelManagementPage
  - [x] 加载测试用户数据 `test-users.json`
  - [x] 设置测试基础描述：`test.describe('渠道创建功能', () => { ... })`
  - [x] 添加 beforeEach 登录和导航逻辑

- [x] 任务 2: 基本创建流程测试 (AC: 1, 5)
  - [x] 测试：应该成功创建渠道（填写所有字段）
  - [x] 测试：创建后渠道应该出现在列表中
  - [x] 使用时间戳生成唯一渠道名称
  - [x] 验证 API 响应成功
  - [x] 验证渠道存在于列表中
  - [x] 测试结束后清理测试数据

- [x] 任务 3: 完整表单字段测试 (AC: 2)
  - [x] 测试：应该保存所有填写的字段数据
  - [x] 测试：应该支持不同的渠道类型
  - [x] 测试：应该支持不同的联系人信息
  - [x] 验证所有字段正确显示在列表中

- [x] 任务 4: 表单验证测试 (AC: 3)
  - [x] 测试：未填写渠道名称时应显示内联验证错误
  - [x] 测试：应该能取消创建渠道操作
  - [x] 测试：应该能通过关闭对话框取消创建

- [x] 任务 5: 对话框元素验证 (AC: 4)
  - [x] 测试：应该显示创建渠道对话框的所有字段
  - [x] 验证渠道名称输入框（必填）
  - [x] 验证可选字段输入框
  - [x] 验证创建和取消按钮

- [x] 任务 6: 数据唯一性测试 (AC: 5)
  - [x] 测试：不同测试应该使用不同的渠道名称
  - [x] 使用时间戳确保唯一性
  - [x] 验证多个渠道可以独立存在

- [x] 任务 7: 运行测试并验证 (AC: 全部)
  - [x] 运行 `pnpm test:e2e:chromium channel-create`
  - [x] 验证所有测试通过
  - [x] 修复发现的问题

## Dev Notes

### Epic 11 背景和目标

**Epic 11: 基础配置管理测试 (Epic F)**

为平台、公司、渠道配置管理编写 E2E 测试，为后续用户管理和跨端测试提供必要的测试数据。

**实体关系链：**
```
Platform (平台)
  ↓ 1:N
Company (公司) - 必须 platformId
  ↓ 1:N
Order (订单) - 必须 companyId
  ↓
Channel (渠道) - 订单的可选条件
```

**Story 11.8 可选性的原因：**

1. **Channel 是订单的可选字段**
   - 在订单创建表单中，`channelId` 是可选的（`optional()`）
   - 订单可以不选择渠道直接创建
   - 不像 Platform 和 Company，它们是创建订单的必要条件

2. **优先级较低**
   - Story 11.1-11.6 已经覆盖了 Platform 和 Company 的完整测试
   - 这些是阻塞后续 Epic（用户管理、跨端测试）的核心功能
   - Channel 管理测试可以延后实现

3. **实现时机**
   - 如果订单管理测试（Epic 10）发现需要渠道选择功能验证，再实现此 Story
   - 或者当有额外时间时补充渠道管理测试
   - 当前 Epic 11 的核心目标（Platform + Company）已经完成

### Channel 实体关键特点

- 渠道名称全局唯一（唯一索引：`idx_channel_name`）
- 包含渠道类型（channelType）- 区分不同渠道来源
- 联系人信息（contactPerson, contactPhone）
- 有状态字段（status: 1-启用，0-禁用）
- 删除已禁用的渠道才能删除
- 独立实体，不依赖其他表（无需关联 Platform 或 Company）

### ChannelManagementPage 已实现功能

**Story 11.7 已完成的工作：**
- ✅ 创建 `ChannelManagementPage` 类
- ✅ 定义所有选择器（页面级、对话框、表单字段、按钮）
- ✅ 实现导航和基础验证方法：`goto()`, `expectToBeVisible()`
- ✅ 实现对话框操作方法：`openCreateDialog()`, `cancelDialog()`, `waitForDialogClosed()`
- ✅ 实现表单操作方法：`fillChannelForm()`, `submitForm()`
- ✅ 实现 CRUD 操作方法：`createChannel()`, `deleteChannel()`
- ✅ 实现搜索和验证方法：`searchByName()`, `channelExists()`

### 参考测试模式（Platform Create 测试）

从 `platform-create.spec.ts` 中学习的测试模式：

**1. 测试文件结构：**
```typescript
import { test, expect } from '../../utils/test-setup';
import { readFileSync } from 'fs';
import { join, dirname } from 'path';
import { fileURLToPath } from 'url';

const testUsers = JSON.parse(readFileSync(...));

test.describe('平台创建功能', () => {
  test.beforeEach(async ({ adminLoginPage, platformManagementPage }) => {
    // 登录 + 导航
  });

  test.describe('基本创建流程测试', () => {
    // 测试用例
  });
});
```

**2. 数据唯一性策略：**
```typescript
const timestamp = Date.now();
const platformName = `测试平台_${timestamp}`;
```

**3. 基本创建测试流程：**
1. 生成唯一数据
2. 调用 Page Object 的 create 方法
3. 验证 API 响应成功
4. 验证数据出现在列表中
5. 清理测试数据

**4. 测试清理：**
- 每个测试用例结束后清理自己创建的数据
- 使用 `deleteChannel()` 方法删除测试数据
- 验证删除成功后再结束测试

### Channel 与 Platform/Company 的差异

| 特性 | Platform | Company | Channel |
|------|----------|---------|---------|
| **外键依赖** | 无 | 需要 platformId | 无 |
| **名称唯一性** | 全局 | 同平台下唯一 | 全局 |
| **必填字段** | platformName | companyName | channelName |
| **可选字段** | 联系人信息 | 地址 + platformId | channelType, description |

**Channel 特有的特点：**
- 有 channelType 字段区分不同渠道类型（如"小程序"、"网站"等）
- 联系人字段都是必填的（但有默认值空字符串）
- 与其他配置实体无关联，独立存在
- 测试时不需要先创建其他实体（不像 Company 需要 Platform）

### 测试用例设计

**测试文件：** `web/tests/e2e/specs/admin/channel-create.spec.ts`

**测试套件结构：**

1. **基本创建流程测试**
   - 应该成功创建渠道（填写所有字段）
   - 创建后渠道应该出现在列表中

2. **完整表单字段测试**
   - 应该保存所有填写的字段数据
   - 应该支持不同的渠道类型
   - 应该支持不同的联系人信息

3. **表单验证测试**
   - 未填写渠道名称时应显示内联验证错误
   - 应该能取消创建渠道操作
   - 应该能通过关闭对话框取消创建

4. **对话框元素验证**
   - 应该显示创建渠道对话框的所有字段

5. **数据唯一性测试**
   - 不同测试应该使用不同的渠道名称

6. **测试后清理验证**
   - 应该能成功删除测试创建的渠道

### ChannelData 接口

```typescript
export interface ChannelData {
  /** 渠道名称（必填） */
  channelName: string;
  /** 渠道类型（可选） */
  channelType?: string;
  /** 联系人（可选） */
  contactPerson?: string;
  /** 联系电话（可选） */
  contactPhone?: string;
  /** 描述（可选） */
  description?: string;
}
```

### API 端点参考

```typescript
// 创建渠道
POST /api/v1/channel/createChannel
Body: { channelName, channelType?, contactPerson?, contactPhone?, description? }

// 获取所有渠道
GET /api/v1/channel/getAllChannels?skip=0&take=10

// 删除渠道
POST /api/v1/channel/deleteChannel
Body: { id: number }
```

### 测试标准和规范

遵循项目测试标准：
- `docs/standards/testing-standards.md`
- `docs/standards/web-ui-testing-standards.md`

**关键测试原则：**
1. 测试独立性：每个测试用例独立运行
2. 数据清理：每个测试结束后清理自己创建的数据
3. 清晰断言：使用 expect() 明确断言预期结果
4. 等待策略：使用 Playwright 的 auto-waiting

### 测试数据唯一性策略

**使用时间戳确保唯一性：**
```typescript
const timestamp = Date.now();
const uniqueId = `channel_${timestamp}`;
const channelName = `测试渠道_${uniqueId}`;
```

**测试数据清理：**
- 每个测试用例结束后清理自己创建的渠道数据
- 使用 `deleteChannel()` 方法删除测试数据
- 验证删除成功后再结束测试

### 测试夹具配置

**test-setup.ts 中的 fixture（已在 Story 11.7 添加）：**
```typescript
export const test = test.extend<{
  adminLoginPage: AdminLoginPage;
  channelManagementPage: ChannelManagementPage;
}>({
  adminLoginPage: async ({ page }, use) => {
    await use(new AdminLoginPage(page));
  },
  channelManagementPage: async ({ page }, use) => {
    await use(new ChannelManagementPage(page));
  },
});
```

### 依赖关系

**Epic 11 内部依赖：**
- Story 11.1: ✅ 已完成（PlatformManagementPage 作为参考）
- Story 11.2: ✅ 已完成（平台创建测试参考）
- Story 11.3: ✅ 已完成（平台列表测试参考）
- Story 11.4: ✅ 已完成（CompanyManagementPage 作为参考）
- Story 11.5: Backlog（创建测试公司）
- Story 11.6: ✅ 已完成（公司列表测试）
- Story 11.7: ✅ 已完成（Channel 管理 Page Object）
- Story 11.8: 创建测试渠道（当前，可选）

**外部依赖：**
- Epic 1, 2: `@d8d/e2e-test-utils` 包（已存在）
- `web/tests/e2e/utils/test-setup.ts`: channelManagementPage fixture 已添加

### 前序 Story (11.1-11.7) 关键经验

从 Story 11.1-11.7 中学到的关键经验：

1. **Toast 检测不可靠：**
   - Toast 消息有时出现得很快
   - 已改用 API 响应验证作为主要验证方式

2. **表格列顺序：**
   - Channel 表格列顺序：渠道ID(0), 渠道名称(1), 渠道类型(2), 联系人(3), 联系电话(4), 创建时间(5), 操作(6)
   - 使用 `nth(1)` 检查渠道名称列

3. **测试数据要求：**
   - 后端 Zod schema 要求字段类型正确
   - 空字符串在某些字段中是有效值（有默认值）
   - 测试不填的可选字段应该设为 undefined

4. **页面刷新：**
   - 创建/删除数据后需要刷新页面或重新导航
   - 使用 `page.reload()` 或 `goto()` 刷新

5. **选择器优先级：**
   - 优先使用 data-testid（最稳定）
   - 其次使用 role + name（较稳定）
   - 避免使用文本选择器（可能变化）

6. **编辑表单 data-testid 缺失：**
   - 从 ChannelManagementPage 的经验，编辑表单缺少 data-testid
   - 已使用 `getByRole('form')` + `getByLabel()` 组合定位

### 已知问题和注意事项

1. **页面路由：**
   - 渠道管理页面路由：`/admin/channels`（已确认）

2. **data-testid 不完整：**
   - ChannelManagement UI 组件的 data-testid 设置不完整
   - 编辑表单字段缺少显式的 data-testid
   - Page Object 已使用 `role + label` 组合定位

3. **渠道名称全局唯一：**
   - 渠道名称全局唯一，不是在某个父级下唯一
   - 测试使用时间戳确保唯一性

4. **删除限制：**
   - 只有禁用状态的渠道才能删除
   - Page Object 的 `deleteChannel()` 使用 API 直接删除，绕过 UI 限制

5. **状态显示：**
   - 状态字段存在，但表格中未显示状态列
   - 测试中不需要验证状态显示

### 实现决策点

**由于此 Story 是可选的，实现前需要确认：**

1. **是否需要渠道管理测试？**
   - 订单管理测试（Epic 10）是否需要验证渠道选择功能？
   - 如果订单创建流程中渠道选择是关键步骤，则需要实现

2. **优先级评估：**
   - Epic 11 的核心目标（Platform + Company）已完成
   - Channel 管理测试优先级低于其他 Epic
   - 可以在有空余时间时实现

3. **实现范围：**
   - 如果实现，建议实现完整的创建测试
   - 如果不实现，可以在后续有需要时补充

### 可选性说明

**标记为"可选"的原因总结：**

1. **业务优先级低** - Channel 是订单的可选字段，不影响核心业务流程
2. **依赖关系弱** - 不阻塞其他 Epic 的开发
3. **时间资源有限** - Epic 11 的核心目标（Platform + Company）已实现
4. **可延后实现** - 当发现确实需要渠道管理测试时，再实现此 Story

**何时应该实现此 Story：**
- 订单管理测试（Epic 10）中发现需要验证渠道选择功能
- 产品团队明确要求渠道管理测试覆盖
- 有额外开发时间资源

### Project Structure Notes

**测试文件存放路径：**
```
web/tests/e2e/
├── pages/admin/
│   ├── platform-management.page.ts   # 平台管理 Page Object（已完成）
│   ├── company-management.page.ts    # 公司管理 Page Object（已完成）
│   └── channel-management.page.ts    # 渠道管理 Page Object（已完成）
├── specs/admin/
│   ├── platform-create.spec.ts       # 平台创建测试（已完成）- 参考模式
│   ├── platform-list.spec.ts         # 平台列表测试（已完成）
│   ├── company-create.spec.ts        # 公司创建测试（待实现）
│   ├── company-list.spec.ts          # 公司列表测试（已完成）
│   └── channel-create.spec.ts        # 渠道创建测试（当前，可选）
└── utils/
    └── test-setup.ts                  # 测试夹具配置（已添加 channelManagementPage）
```

### References

- [Epic 11 基础配置管理测试](../planning-artifacts/epics.md#epic-11-基础配置管理测试-epic-f)
- [Story 11.2 Platform 创建测试](./11-2-platform-create-test.md) - 参考测试模式
- [Story 11.7 Channel Page Object](./11-7-channel-page-object.md) - Page Object 参考
- [PlatformManagementPage](../../web/tests/e2e/pages/admin/platform-management.page.ts) - 参考模式
- [ChannelManagementPage](../../web/tests/e2e/pages/admin/channel-management.page.ts) - 使用此 Page Object
- [Platform Create 测试](../../web/tests/e2e/specs/admin/platform-create.spec.ts) - 测试模式参考
- [测试标准](../../docs/standards/testing-standards.md)
- [Web UI 测试标准](../../docs/standards/web-ui-testing-standards.md)

## Dev Agent Record

### Agent Model Used

claude-opus-4-5-20251101

### Debug Log References

无特殊问题需要记录。Story 创建过程顺利。

### Completion Notes List

**已完成的工作：**
1. ✅ 创建 Story 11.8 文档：`11-8-channel-create-test.md`
2. ✅ 从 Epic 11、Story 11.7 和 platform-create.spec.ts 收集完整的上下文
3. ✅ 定义验收标准和任务分解
4. ✅ 记录所有必要的开发笔记（实体结构、API、测试模式等）
5. ✅ 设置状态为 `ready-for-dev`

**开发阶段（2026-01-13）：**
1. ✅ 创建测试文件 `web/tests/e2e/specs/admin/channel-create.spec.ts`
2. ✅ 实现所有 11 个测试用例
3. ✅ 修复测试超时问题（避免使用 `reload()` + `toPass()` 组合，改用 `waitForTimeout(2000)`）
4. ✅ 所有测试通过：11 passed (2.9m)

**文档包含内容：**
- Epic 11 背景和可选性说明
- Channel 实体关键特点
- ChannelManagementPage 已实现功能清单
- 参考测试模式（Platform Create）
- Channel 与 Platform/Company 的差异对比
- 完整的测试用例设计
- 测试数据唯一性策略
- API 端点参考
- 前序 Story 关键经验
- 已知问题和注意事项

**注意事项：**
- 此 Story 标记为"可选"，根据业务需求和优先级决定是否实现
- ChannelManagementPage 已在 Story 11.7 完成
- 测试模式参考 platform-create.spec.ts
- 与 Platform/Company 测试保持一致的模式

### File List

**新增文件：**
- `_bmad-output/implementation-artifacts/11-8-channel-create-test.md` - 本 story 文件
- `web/tests/e2e/specs/admin/channel-create.spec.ts` - 渠道创建测试（已实现）

**修改文件：**
- `_bmad-output/implementation-artifacts/sprint-status.yaml` - 更新 Story 11.8 状态

### Change Log

**2026-01-12**
- 创建 Story 11.8 文档
- 收集并整理所有必要的上下文信息
- 设置状态为 ready-for-dev

**2026-01-13**
- 实现渠道创建 E2E 测试（11个测试用例）
- 修复测试超时问题
- 所有测试通过：11 passed (2.9m)
- 状态更新为 done