# Story 11.1: Platform 管理 Page Object 开发

Status: done

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

## Story

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

## Acceptance Criteria

1. **AC1: 创建 PlatformPageObject 类**
   - 类文件路径: `web/tests/e2e/pages/admin/platform-management.page.ts`
   - 使用 Playwright Page 对象作为构造参数
   - 遵循项目现有 Page Object 设计模式（与 order-management.page.ts 和 region-management.page.ts 保持一致）

2. **AC2: 实现列表页元素定位**
   - 页面标题定位器
   - 创建平台按钮
   - 搜索输入框和搜索按钮
   - 平台列表表格

3. **AC3: 实现创建/编辑对话框元素定位**
   - 对话框标题定位器（区分创建/编辑）
   - 表单字段定位器：
     - 平台名称（必填）
     - 联系人
     - 联系电话
     - 联系邮箱
   - 提交按钮（创建/更新）
   - 取消按钮

4. **AC4: 实现删除确认对话框元素定位**
   - 确认删除对话框标题
   - 确认删除按钮
   - 取消删除按钮

5. **AC5: 提供常用操作方法**
   - `goto()`: 导航到平台管理页面
   - `createPlatform()`: 创建平台（完整流程）
   - `editPlatform()`: 编辑平台（完整流程）
   - `deletePlatform()`: 删除平台（完整流程）
   - `searchByName()`: 按平台名称搜索
   - `platformExists()`: 验证平台是否存在

6. **AC6: 代码质量标准**
   - 通过 ESLint 检查，无警告和错误
   - 通过 TypeScript 类型检查，无 `any` 类型
   - 所有公共方法有完整的 JSDoc 注释

## Tasks / Subtasks

- [x] 任务 1: 创建 PlatformPageObject 类基础结构 (AC: 1, 6)
  - [x] 创建文件 `web/tests/e2e/pages/admin/platform-management.page.ts`
  - [x] 定义 PlatformPageObject 类，接受 Page 参数
  - [x] 定义类型接口（PlatformData, FormSubmitResult 等）

- [x] 任务 2: 实现列表页选择器 (AC: 2)
  - [x] 定义页面标题选择器
  - [x] 定义创建平台按钮选择器
  - [x] 定义搜索输入框和按钮选择器
  - [x] 定义平台列表表格选择器

- [x] 任务 3: 实现对话框相关选择器和方法 (AC: 3, 4)
  - [x] 定义创建对话框标题选择器
  - [x] 定义编辑对话框标题选择器
  - [x] 定义表单字段选择器
  - [x] 定义提交/取消按钮选择器
  - [x] 定义删除确认对话框选择器

- [x] 任务 4: 实现基础导航和验证方法 (AC: 5, 6)
  - [x] 实现 `goto()` 方法
  - [x] 实现 `expectToBeVisible()` 方法
  - [x] 添加 JSDoc 注释

- [x] 任务 5: 实现 CRUD 操作方法 (AC: 5)
  - [x] 实现 `createPlatform(data)` 方法
  - [x] 实现 `editPlatform(platformName, data)` 方法
  - [x] 实现 `deletePlatform(platformName)` 方法
  - [x] 添加 JSDoc 注释

- [x] 任务 6: 实现搜索和验证方法 (AC: 5)
  - [x] 实现 `searchByName(name)` 方法
  - [x] 实现 `platformExists(platformName)` 方法
  - [x] 添加 JSDoc 注释

- [x] 任务 7: 代码质量验证 (AC: 6)
  - [x] 运行 ESLint 检查，修复所有问题
  - [x] 运行 TypeScript 类型检查，修复所有问题
  - [x] 确保 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 模式：**

1. **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）

2. **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`

**关键选择器策略：**
1. 优先使用 `data-testid` 属性
2. 其次使用 ARIA role + name 组合
3. 谨慎使用文本选择器（避免重复或不稳定）

**等待策略：**
- 使用 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 等工具）

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

1. **页面路由待确认：**
   - 平台管理页面的实际路由可能是 `/admin/platforms` 或其他
   - 需要通过实际访问验证
   - 可以参考其他管理页面的路由模式

2. **对话框处理：**
   - 创建和编辑使用同一个对话框组件，通过 `isCreateForm` 状态区分
   - 需要分别处理两种模式的定位器和操作

3. **表单验证：**
   - 平台名称为必填字段
   - 其他字段为可选字段
   - 需要验证表单错误提示的显示

### 开发顺序建议

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

## Dev Agent Record

### Agent Model Used

Claude (d8d-model)

### Debug Log References

无（初始创建）

### Completion Notes List

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

**完成的工作**:
1. 创建了 `PlatformManagementPage` 类，遵循项目现有 Page Object 设计模式
2. 实现了所有列表页选择器（pageTitle, createPlatformButton, searchInput, searchButton, platformTable）
3. 实现了对话框相关选择器（创建/编辑对话框标题、表单字段、提交/取消按钮、删除确认对话框）
4. 实现了基础导航和验证方法（goto, expectToBeVisible）
5. 实现了完整的 CRUD 操作方法（createPlatform, editPlatform, deletePlatform）
6. 实现了搜索和验证方法（searchByName, platformExists）
7. 所有公共方法都包含完整的 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`