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

Status: ready-for-dev

Story

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

注意： 此 Story 标记为"可选"，原因：

Channel 是订单的可选字段（订单创建时不需要选择渠道）
不阻塞其他 Epic 的开发
可在有额外时间时实现

Acceptance Criteria

AC1: 基本创建渠道测试
- 测试文件路径: web/tests/e2e/specs/admin/channel-create.spec.ts
- 使用 ChannelManagementPage（已在 Story 11.7 完成）
- 验证填写渠道名称后可以成功创建
- 验证创建成功后渠道出现在列表中
- 测试结束后清理测试数据
AC2: 完整表单字段测试
- 测试填写所有可选字段（渠道类型、联系人、联系电话、描述）
- 验证所有填写的字段数据正确保存
- 验证渠道列表正确显示所有信息
AC3: 表单验证测试
- 测试未填写渠道名称时的表单验证
- 测试取消创建操作
- 测试关闭对话框取消创建
AC4: 对话框元素验证
- 验证创建渠道对话框的所有字段存在
- 验证必填和可选字段正确标识
AC5: 数据唯一性测试
- 验证不同测试使用不同的渠道名称（避免冲突）
- 使用时间戳确保唯一性

Tasks / Subtasks

[ ] 任务 1: 创建测试文件和基础结构 (AC: 1, 5)
- 创建文件 web/tests/e2e/specs/admin/channel-create.spec.ts
- 导入测试依赖和 ChannelManagementPage
- 加载测试用户数据 test-users.json
- 设置测试基础描述：test.describe('渠道创建功能', () => { ... })
- 添加 beforeEach 登录和导航逻辑
[ ] 任务 2: 基本创建流程测试 (AC: 1, 5)
- 测试：应该成功创建渠道（填写所有字段）
- 测试：创建后渠道应该出现在列表中
- 使用时间戳生成唯一渠道名称
- 验证 API 响应成功
- 验证渠道存在于列表中
- 测试结束后清理测试数据
[ ] 任务 3: 完整表单字段测试 (AC: 2)
- 测试：应该保存所有填写的字段数据
- 测试：应该支持不同的渠道类型
- 测试：应该支持不同的联系人信息
- 验证所有字段正确显示在列表中
[ ] 任务 4: 表单验证测试 (AC: 3)
- 测试：未填写渠道名称时应显示内联验证错误
- 测试：应该能取消创建渠道操作
- 测试：应该能通过关闭对话框取消创建
[ ] 任务 5: 对话框元素验证 (AC: 4)
- 测试：应该显示创建渠道对话框的所有字段
- 验证渠道名称输入框（必填）
- 验证可选字段输入框
- 验证创建和取消按钮
[ ] 任务 6: 数据唯一性测试 (AC: 5)
- 测试：不同测试应该使用不同的渠道名称
- 使用时间戳确保唯一性
- 验证多个渠道可以独立存在
[ ] 任务 7: 运行测试并验证 (AC: 全部)
- 运行 pnpm test:e2e:chromium channel-create
- 验证所有测试通过
- 修复发现的问题

Dev Notes

Epic 11 背景和目标

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

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

实体关系链：

Platform (平台)
  ↓ 1:N
Company (公司) - 必须 platformId
  ↓ 1:N
Order (订单) - 必须 companyId
  ↓
Channel (渠道) - 订单的可选条件

Story 11.8 可选性的原因：

Channel 是订单的可选字段
- 在订单创建表单中，channelId 是可选的（optional()）
- 订单可以不选择渠道直接创建
- 不像 Platform 和 Company，它们是创建订单的必要条件
优先级较低
- Story 11.1-11.6 已经覆盖了 Platform 和 Company 的完整测试
- 这些是阻塞后续 Epic（用户管理、跨端测试）的核心功能
- Channel 管理测试可以延后实现
实现时机
- 如果订单管理测试（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. 测试文件结构：

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. 数据唯一性策略：

const timestamp = Date.now();
const platformName = `测试平台_${timestamp}`;

3. 基本创建测试流程：

生成唯一数据
调用 Page Object 的 create 方法
验证 API 响应成功
验证数据出现在列表中
清理测试数据

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

测试套件结构：

基本创建流程测试
- 应该成功创建渠道（填写所有字段）
- 创建后渠道应该出现在列表中
完整表单字段测试
- 应该保存所有填写的字段数据
- 应该支持不同的渠道类型
- 应该支持不同的联系人信息
表单验证测试
- 未填写渠道名称时应显示内联验证错误
- 应该能取消创建渠道操作
- 应该能通过关闭对话框取消创建
对话框元素验证
- 应该显示创建渠道对话框的所有字段
数据唯一性测试
- 不同测试应该使用不同的渠道名称
测试后清理验证
- 应该能成功删除测试创建的渠道

ChannelData 接口

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

API 端点参考

// 创建渠道
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

关键测试原则：

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

测试数据唯一性策略

使用时间戳确保唯一性：

const timestamp = Date.now();
const uniqueId = `channel_${timestamp}`;
const channelName = `测试渠道_${uniqueId}`;

测试数据清理：

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

测试夹具配置

test-setup.ts 中的 fixture（已在 Story 11.7 添加）：

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 中学到的关键经验：

Toast 检测不可靠：
- Toast 消息有时出现得很快
- 已改用 API 响应验证作为主要验证方式
表格列顺序：
- Channel 表格列顺序：渠道ID(0), 渠道名称(1), 渠道类型(2), 联系人(3), 联系电话(4), 创建时间(5), 操作(6)
- 使用 nth(1) 检查渠道名称列
测试数据要求：
- 后端 Zod schema 要求字段类型正确
- 空字符串在某些字段中是有效值（有默认值）
- 测试不填的可选字段应该设为 undefined
页面刷新：
- 创建/删除数据后需要刷新页面或重新导航
- 使用 page.reload() 或 goto() 刷新
选择器优先级：
- 优先使用 data-testid（最稳定）
- 其次使用 role + name（较稳定）
- 避免使用文本选择器（可能变化）
编辑表单 data-testid 缺失：
- 从 ChannelManagementPage 的经验，编辑表单缺少 data-testid
- 已使用 getByRole('form') + getByLabel() 组合定位

已知问题和注意事项

页面路由：
- 渠道管理页面路由：/admin/channels（已确认）
data-testid 不完整：
- ChannelManagement UI 组件的 data-testid 设置不完整
- 编辑表单字段缺少显式的 data-testid
- Page Object 已使用 role + label 组合定位
渠道名称全局唯一：
- 渠道名称全局唯一，不是在某个父级下唯一
- 测试使用时间戳确保唯一性
删除限制：
- 只有禁用状态的渠道才能删除
- Page Object 的 deleteChannel() 使用 API 直接删除，绕过 UI 限制
状态显示：
- 状态字段存在，但表格中未显示状态列
- 测试中不需要验证状态显示

实现决策点

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

是否需要渠道管理测试？
- 订单管理测试（Epic 10）是否需要验证渠道选择功能？
- 如果订单创建流程中渠道选择是关键步骤，则需要实现
优先级评估：
- Epic 11 的核心目标（Platform + Company）已完成
- Channel 管理测试优先级低于其他 Epic
- 可以在有空余时间时实现
实现范围：
- 如果实现，建议实现完整的创建测试
- 如果不实现，可以在后续有需要时补充

可选性说明

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

业务优先级低 - Channel 是订单的可选字段，不影响核心业务流程
依赖关系弱 - 不阻塞其他 Epic 的开发
时间资源有限 - Epic 11 的核心目标（Platform + Company）已实现
可延后实现 - 当发现确实需要渠道管理测试时，再实现此 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 基础配置管理测试
Story 11.2 Platform 创建测试 - 参考测试模式
Story 11.7 Channel Page Object - Page Object 参考
PlatformManagementPage - 参考模式
ChannelManagementPage - 使用此 Page Object
Platform Create 测试 - 测试模式参考
测试标准
Web UI 测试标准

Dev Agent Record

Agent Model Used

claude-opus-4-5-20251101

Debug Log References

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

Completion Notes List

已完成的工作：

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

文档包含内容：

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 状态为 ready-for-dev

Change Log

2026-01-12

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

11-8-channel-create-test.md 17 KB История Директен файл