Story 11.1: Platform 管理 Page Object 开发

Status: done

Story

作为测试开发者，我想要创建 Platform（平台）管理的 Page Object，以便为 Platform 管理功能的 E2E 测试封装页面元素和操作方法。

Acceptance Criteria

AC1: 创建 PlatformPageObject 类
- 类文件路径: web/tests/e2e/pages/admin/platform-management.page.ts
- 使用 Playwright Page 对象作为构造参数
- 遵循项目现有 Page Object 设计模式（与 order-management.page.ts 和 region-management.page.ts 保持一致）
AC2: 实现列表页元素定位
- 页面标题定位器
- 创建平台按钮
- 搜索输入框和搜索按钮
- 平台列表表格
AC3: 实现创建/编辑对话框元素定位
- 对话框标题定位器（区分创建/编辑）
- 表单字段定位器：
  - 平台名称（必填）
  - 联系人
  - 联系电话
  - 联系邮箱
- 提交按钮（创建/更新）
- 取消按钮
AC4: 实现删除确认对话框元素定位
- 确认删除对话框标题
- 确认删除按钮
- 取消删除按钮
AC5: 提供常用操作方法
- goto(): 导航到平台管理页面
- createPlatform(): 创建平台（完整流程）
- editPlatform(): 编辑平台（完整流程）
- deletePlatform(): 删除平台（完整流程）
- searchByName(): 按平台名称搜索
- platformExists(): 验证平台是否存在
AC6: 代码质量标准
- 通过 ESLint 检查，无警告和错误
- 通过 TypeScript 类型检查，无 any 类型
- 所有公共方法有完整的 JSDoc 注释

Tasks / Subtasks

[x] 任务 1: 创建 PlatformPageObject 类基础结构 (AC: 1, 6)
- 创建文件 web/tests/e2e/pages/admin/platform-management.page.ts
- 定义 PlatformPageObject 类，接受 Page 参数
- 定义类型接口（PlatformData, FormSubmitResult 等）
[x] 任务 2: 实现列表页选择器 (AC: 2)
- 定义页面标题选择器
- 定义创建平台按钮选择器
- 定义搜索输入框和按钮选择器
- 定义平台列表表格选择器
[x] 任务 3: 实现对话框相关选择器和方法 (AC: 3, 4)
- 定义创建对话框标题选择器
- 定义编辑对话框标题选择器
- 定义表单字段选择器
- 定义提交/取消按钮选择器
- 定义删除确认对话框选择器
[x] 任务 4: 实现基础导航和验证方法 (AC: 5, 6)
- 实现 goto() 方法
- 实现 expectToBeVisible() 方法
- 添加 JSDoc 注释
[x] 任务 5: 实现 CRUD 操作方法 (AC: 5)
- 实现 createPlatform(data) 方法
- 实现 editPlatform(platformName, data) 方法
- 实现 deletePlatform(platformName) 方法
- 添加 JSDoc 注释
[x] 任务 6: 实现搜索和验证方法 (AC: 5)
- 实现 searchByName(name) 方法
- 实现 platformExists(platformName) 方法
- 添加 JSDoc 注释
[x] 任务 7: 代码质量验证 (AC: 6)
- 运行 ESLint 检查，修复所有问题
- 运行 TypeScript 类型检查，修复所有问题
- 确保 JSDoc 注释完整

Dev Notes

Epic 11 背景和目标

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

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

实体关系链：

Platform (平台)
  ↓ 1:N
Company (公司) - 必须 platformId
  ↓ 1:N
Order (订单) - 必须 companyId

重要性说明：

Platform 是订单创建的必要条件
Company 是订单和企业用户的必要条件（关联 Platform）
Story 11.1 是 Epic 11 的第一个 Story，为后续测试提供 Page Object 基础

架构模式和约束

参考现有 Page Object 模式：

order-management.page.ts (web/tests/e2e/pages/admin/order-management.page.ts)
- 使用 Playwright Page 和 Locator 作为核心类型
- 定义常量（ORDER_STATUS, WORK_STATUS 等）
- 定义数据接口（OrderData, OrderPersonData 等）
- 定义网络响应接口（NetworkResponse）
- 定义表单提交结果接口（FormSubmitResult）
- 提供完整的 CRUD 操作方法
- 使用 @d8d/e2e-test-utils 工具函数（如 selectRadixOption）
region-management.page.ts (web/tests/e2e/pages/admin/region-management.page.ts)
- 使用类似的结构和模式
- 定义区域层级常量和类型
- 提供树形结构相关方法（expandNode, collapseNode 等）
- 处理异步加载和懒加载场景

关键模式总结：

模式	描述	示例
类型定义	定义常量和接口	ORDER_STATUS, OrderData
选择器定义	在构造函数中定义 Locator	this.pageTitle, this.addButton
导航方法	goto() 和 expectToBeVisible()	async goto()
CRUD 方法	提供完整流程方法	async createOrder(data)
表单处理	填写表单 + 提交验证	async fillOrderForm(), submitForm()
网络响应	监听 API 响应，返回结果	responseHandler
Toast 验证	检查 sonner toast 消息	errorToast, successToast

Platform 管理组件分析

组件路径： allin-packages/platform-management-ui/src/components/PlatformManagement.tsx

关键字段： | 字段 | 类型 | 必填 | data-testid | |------|------|------|-------------| | platformName | string | 是 | platform-name-input | | contactPerson | string | 否 | contact-person-input | | contactPhone | string | 否 | contact-phone-input | | contactEmail | string | 否 | contact-email-input |

关键 data-testid 属性：

create-platform-button: 创建平台按钮
search-input: 搜索输入框
search-button: 搜索按钮
edit-button-{id}: 编辑按钮
delete-button-{id}: 删除按钮
create-platform-dialog-title: 创建对话框标题
edit-platform-dialog-title: 编辑对话框标题
create-submit-button: 创建提交按钮
update-submit-button: 更新提交按钮
confirm-delete-button: 确认删除按钮

页面路径： /admin/platforms（待确认，可能需要通过实际访问验证）

API 端点：

GET /platforms: 获取平台列表
POST /platforms: 创建平台
POST /platforms/update: 更新平台
POST /platforms/delete: 删除平台
GET /platforms/search: 搜索平台

项目结构约束

Page Object 存放路径：

web/tests/e2e/pages/admin/
├── order-management.page.ts    # 订单管理 Page Object (参考)
├── region-management.page.ts    # 区域管理 Page Object (参考)
└── platform-management.page.ts  # 平台管理 Page Object (本次创建)

测试文件路径（后续 Story 创建）：

web/tests/e2e/specs/admin/
└── platform-*.spec.ts

TypeScript 严格模式要求

根据 project-context.md：

使用 TypeScript 严格模式，无 any 类型
所有导出函数都有完整的参数类型和返回值类型
类型定义支持 IDE 自动补全和类型检查
函数命名：camelCase（如 createPlatform）

测试标准和规范

遵循项目测试标准：

docs/standards/testing-standards.md
docs/standards/web-ui-testing-standards.md

关键选择器策略：

优先使用 data-testid 属性
其次使用 ARIA role + name 组合
谨慎使用文本选择器（避免重复或不稳定）

等待策略：

使用 Playwright 的 auto-waiting 机制
关键元素使用 waitFor({ state: 'visible' })
网络请求使用 waitForLoadState('networkidle') 或 domcontentloaded

依赖关系

Epic 11 内部依赖：

Story 11.1 (当前) → Story 11.2 → Story 11.3 → ...

外部依赖：

Epic 1, 2: @d8d/e2e-test-utils 包（已存在，提供 selectRadixOption 等工具）

已知问题和注意事项

页面路由待确认：
- 平台管理页面的实际路由可能是 /admin/platforms 或其他
- 需要通过实际访问验证
- 可以参考其他管理页面的路由模式
对话框处理：
- 创建和编辑使用同一个对话框组件，通过 isCreateForm 状态区分
- 需要分别处理两种模式的定位器和操作
表单验证：
- 平台名称为必填字段
- 其他字段为可选字段
- 需要验证表单错误提示的显示

开发顺序建议

首先定义常量和类型接口
然后实现构造函数和选择器定义
实现基础导航和验证方法
实现对话框操作方法
实现 CRUD 完整流程方法
最后实现搜索和辅助方法

Dev Agent Record

Agent Model Used

Claude (d8d-model)

Debug Log References

无（初始创建）

Completion Notes List

实现完成时间: 2026-01-12

完成的工作:

创建了 PlatformManagementPage 类，遵循项目现有 Page Object 设计模式
实现了所有列表页选择器（pageTitle, createPlatformButton, searchInput, searchButton, platformTable）
实现了对话框相关选择器（创建/编辑对话框标题、表单字段、提交/取消按钮、删除确认对话框）
实现了基础导航和验证方法（goto, expectToBeVisible）
实现了完整的 CRUD 操作方法（createPlatform, editPlatform, deletePlatform）
实现了搜索和验证方法（searchByName, platformExists）
所有公共方法都包含完整的 JSDoc 注释

技术处理:

使用 data-testid 和 ARIA role 选择器定位元素，与现有 Page Object 模式保持一致
使用 Playwright Response 类型进行网络响应监听
实现了网络响应监听和 Toast 消息验证
所有方法都返回 Promise<void> 或 Promise<FormSubmitResult> 或 Promise<boolean>

代码质量:

✅ ESLint 检查通过，无警告和错误
✅ TypeScript 类型检查通过，无 any 类型
✅ 所有公共方法有完整的 JSDoc 注释

代码审查修复（AI-Review 2026-01-12）:

✅ 添加了 PLATFORM_STATUS 常量定义
✅ 优化网络监听器类型（使用 Response 类型）
✅ 改进 openEditDialog/openDeleteDialog 选择器（使用 role + name 组合）
✅ 添加 deletePlatform() 错误处理（try-catch）
✅ 改进 searchByName() 返回值（返回搜索结果验证）
✅ 改进 platformExists() 精确匹配（验证第一列文本完全匹配）

File List

新增文件:

web/tests/e2e/pages/admin/platform-management.page.ts

11-1-platform-page-object.story.md 10 KB 文件历史 原始文件