# Story 8.1: 创建区域管理 Page Object

Status: ready-for-dev

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

## Story

作为测试开发者，
我想要创建区域管理的 Page Object，
以便组织区域管理相关的页面元素和操作。

## Acceptance Criteria

**Given** Epic 2 的 Page Object 模式已验证
**When** 创建 `web/tests/e2e/pages/admin/region-management.page.ts`
**Then** 定义区域列表页面的选择器和操作方法
**And** 定义添加区域对话框的选择器和操作方法
**And** 定义编辑区域对话框的选择器和操作方法
**And** 遵循现有 Page Object 设计模式
**And** 所有方法有完整的 TypeScript 类型定义

**Given** 区域管理 Page Object 已创建
**When** 编写区域列表查看测试用例
**Then** 验证区域列表按预期加载
**And** 验证区域数据的正确展示（名称、层级、状态等）
**And** 验证分页功能（如适用）
**And** 验证搜索功能（如适用）
**And** 测试在真实浏览器中通过

## Tasks / Subtasks

- [ ] 创建 RegionManagementPage 类基础结构 (AC: #)
  - [ ] 定义页面选择器（页面标题、新增按钮、表格等）
  - [ ] 实现构造函数和初始化逻辑
- [ ] 实现页面导航方法 (AC: #)
  - [ ] 实现 goto() 方法导航到区域管理页面
  - [ ] 实现 expectToBeVisible() 验证页面元素可见性
- [ ] 实现区域列表相关方法 (AC: #)
  - [ ] 定义列表表格、搜索输入框、搜索按钮等选择器
  - [ ] 实现 searchByName() 搜索方法
  - [ ] 实现 regionExists() 验证区域是否存在
- [ ] 实现添加区域对话框方法 (AC: #)
  - [ ] 定义添加区域对话框选择器
  - [ ] 实现 openAddDialog() 打开添加对话框
  - [ ] 实现 fillRegionForm() 填写区域表单
  - [ ] 实现 submitForm() 提交表单
- [ ] 实现编辑区域对话框方法 (AC: #)
  - [ ] 定义编辑区域对话框选择器
  - [ ] 实现 openEditDialog() 打开编辑对话框
  - [ ] 实现区域信息编辑方法
- [ ] 实现删除区域相关方法 (AC: #)
  - [ ] 定义删除确认对话框选择器
  - [ ] 实现 confirmDelete() 确认删除
  - [ ] 实现 cancelDelete() 取消删除
- [ ] 添加 TypeScript 类型定义 (AC: #)
  - [ ] 定义 RegionData 接口
  - [ ] 定义所有方法的参数和返回值类型
- [ ] 遵循现有 Page Object 设计模式 (AC: #)
  - [ ] 参考 disability-person.page.ts 的代码风格
  - [ ] 使用一致的命名约定
  - [ ] 使用 e2e-test-utils 工具函数

## Dev Notes

### Epic 8 背景和上下文

**Epic 8: 区域管理 E2E 测试 (Epic B - 业务测试 Epic)**

这是 Epic B（区域管理业务测试）的第一个 Story。Epic 8 的目标是为区域管理功能建立完整的 E2E 测试覆盖，验证省/市/区/街道的添加、编辑、删除和级联选择功能。

**依赖:**
- Epic 1: ✅ 已完成（Select 工具基础框架）
- Epic 2: ✅ 已完成（Select 工具在真实 E2E 测试中验证）
- Epic 3: ✅ 已完成（文件上传工具、级联选择工具）

**业务分组:**
- Epic A（残疾人管理）- 已完成基础工具验证
- Epic B（区域管理）- 当前目标
- Epic C（e2e-test-utils 包维护）- 支持性任务

### Page Object 设计模式参考

基于 `web/tests/e2e/pages/admin/disability-person.page.ts` 的成功经验，区域管理 Page Object 应遵循以下设计模式：

**1. 类结构模式:**
```typescript
export class RegionManagementPage {
  readonly page: Page;
  // 页面级选择器
  readonly pageTitle: Locator;
  readonly addButton: Locator;
  // ...其他选择器

  constructor(page: Page) {
    this.page = page;
    // 初始化所有选择器
  }

  // 导航方法
  async goto() { }

  // 表单操作方法
  async openAddDialog() { }
  async fillRegionForm(data: RegionData) { }
  async submitForm() { }

  // 列表操作方法
  async searchByName(name: string) { }
  async regionExists(name: string): Promise<boolean> { }
}
```

**2. 选择器定义模式:**
- 使用 `page.getByRole()` 优先（无障碍属性）
- 使用 `page.getByLabel()` 表单字段
- 使用 `page.getByText()` 或 `page.locator()` 作为兜底
- 所有选择器定义为 `readonly Locator` 类型

**3. 方法命名约定:**
- 导航方法: `goto()`
- 断言方法: `expectToBeVisible()`, `expectSuccess()`
- 操作方法: 动词开头，如 `openAddDialog()`, `fillRegionForm()`
- 查询方法: 返回 boolean，如 `regionExists()`

### 区域管理功能分析

基于现有项目架构和残疾人管理功能的经验，区域管理页面可能包含以下元素：

**页面元素（需要验证实际 DOM 结构）:**
- 页面标题: "区域管理"
- 新增按钮: "新增区域" 或类似文本
- 搜索输入框: 占位符可能为 "搜索区域名称"
- 搜索按钮: "搜索" 或图标按钮
- 数据表格: 显示区域列表
  - 列: 区域名称、区域代码、层级（省/市/区/街道）、状态、操作

**表单字段（需要验证实际 DOM 结构）:**
- 区域名称: 文本输入框
- 区域代码: 文本输入框
- 区域层级: Radix UI Select（省/市/区/街道）
- 父级区域: 级联 Radix UI Select（选择上级区域）
- 状态: Radix UI Select 或 Switch（启用/禁用）
- 备注: 文本域

**对话框元素（需要验证实际 DOM 结构）:**
- 添加区域对话框
- 编辑区域对话框
- 删除确认对话框

### 可用的 e2e-test-utils 工具

根据 `packages/e2e-test-utils/src/index.ts`，以下工具可用于区域管理测试：

```typescript
// Radix UI Select 工具
import { selectRadixOption, selectRadixOptionAsync } from '@d8d/e2e-test-utils';

// 省市区级联选择工具（非常适合区域管理）
import { selectCascade, selectProvinceCity } from '@d8d/e2e-test-utils';

// 文件上传工具（如果区域有图标上传）
import { uploadFileToField } from '@d8d/e2e-test-utils';
```

**关键工具 - selectCascade:**
```typescript
/**
 * 级联选择工具
 * 用于省市区四级级联选择
 *
 * @param page - Playwright Page 对象
 * @param selections - 选择项数组 [{label: '省份', value: '广东省'}, ...]
 * @param options - 配置选项
 */
async function selectCascade(
  page: Page,
  selections: Array<{label: string, value: string}>,
  options?: CascadeSelectOptions
): Promise<void>
```

### 项目结构笔记

**目标文件位置:**
```
web/tests/e2e/pages/admin/region-management.page.ts
```

**导入路径:**
```typescript
import { Page, Locator } from '@playwright/test';
import { selectRadixOption, selectCascade } from '@d8d/e2e-test-utils';
```

**测试文件位置（后续 Story）:**
```
web/tests/e2e/specs/admin/region-management.spec.ts
```

### TypeScript 类型定义

推荐定义以下类型：

```typescript
/**
 * 区域数据接口
 */
export interface RegionData {
  /** 区域名称 */
  name: string;
  /** 区域代码 */
  code?: string;
  /** 区域层级（省/市/区/街道） */
  level: 'province' | 'city' | 'district' | 'street';
  /** 父级区域名称 */
  parentRegion?: string;
  /** 状态 */
  status?: 'enabled' | 'disabled';
  /** 备注 */
  remark?: string;
}

/**
 * 表单提交结果
 */
export interface FormSubmitResult {
  success: boolean;
  message?: string;
  errorMessage?: string;
}
```

### DOM 结构探索步骤

在实现 Page Object 之前，需要探索实际 DOM 结构：

1. **启动开发服务器**（如果未运行）:
   ```bash
   cd web && pnpm dev
   ```

2. **导航到区域管理页面**:
   - URL: `/admin/regions` 或类似路径

3. **使用 Playwright Inspector 或浏览器开发者工具**:
   - 检查页面元素的 `data-testid`, `role`, `aria-label`
   - 记录表单字段的选择器策略
   - 验证 Radix UI Select 的 DOM 结构

4. **记录发现**:
   - 对话框触发器的选择器
   - 表单字段的 label 文本
   - 表格的 CSS 类或结构
   - Toast 消息的选择器

### 与残疾人管理 Page Object 的主要差异

| 方面 | 残疾人管理 | 区域管理 |
|------|-----------|----------|
| 主要实体 | 残疾人个人 | 区域（省市区街道） |
| 树形结构 | 否 | 是（四级层级） |
| 级联选择 | 省市区三级 | 可能需要四级 |
| 图片上传 | 身份证、残疾证照片 | 可能无或区域图标 |
| 动态列表 | 银行卡、备注、回访 | 可能无 |
| 删除约束 | 较少 | 有子级区域不能删除 |

### 测试隔离策略

为支持未来的并行执行（Epic 9），考虑测试数据隔离：

```typescript
/**
 * 生成唯一区域名称（用于测试隔离）
 */
function generateUniqueRegionName(prefix: string = '测试区域'): string {
  const timestamp = Date.now();
  const random = Math.floor(Math.random() * 1000);
  return `${prefix}_${timestamp}_${random}`;
}
```

### 常见陷阱和注意事项

**基于 Architecture.md 的 TypeScript + Playwright 陷阱:**

1. **DOM 结构假设必须验证 ⚠️**
   - 不能基于理想模型开发选择器
   - 必须在真实组件上验证 DOM 结构
   - Radix UI Select 的 DOM 可能随版本变化

2. **选择器策略优先级:**
   - `data-testid` → `aria-label` + role → text content
   - 推荐在组件上添加 `data-testid`

3. **精确文本匹配:**
   - 使用 `:text-is()` 而非 `:has-text()`
   - 避免部分匹配导致误选

4. **超时配置:**
   - 使用 `DEFAULT_TIMEOUTS` 常量
   - 网络空闲等待使用用户自定义超时值

5. **避免使用 page.evaluate():**
   - 优先使用 Playwright API
   - 使用 `element.textContent()` 而非 `page.evaluate()`

## Dev Agent Record

### Agent Model Used

Claude Opus 4 (claude-opus-4-5-20251101)

### Debug Log References

### Completion Notes List

### File List

## Project Context Reference

### 关键项目规则摘要

**技术栈:**
- Playwright 1.55.0 - E2E 测试框架
- TypeScript 5.9.3 - 严格模式
- @d8d/e2e-test-utils - 内部测试工具包

**测试命令:**
```bash
# 运行所有 E2E 测试
pnpm test:e2e:chromium

# 运行单个测试文件
pnpm test:e2e:chromium region-management

# 快速失败模式（调试时使用）
timeout 60 pnpm test:e2e:chromium region-management
```

**包管理:**
- 使用 pnpm（版本 10.18.3）
- 内部包使用 workspace 协议: `@d8d/e2e-test-utils@workspace:*`

**命名约定:**
- 文件名: kebab-case (如: `region-management.page.ts`)
- 类名: PascalCase (如: `RegionManagementPage`)
- 函数/变量: camelCase (如: `goto()`, `searchByName()`)

### 必须遵循的架构决策

**来自 Architecture.md 的关键决策:**

1. **选择器策略（混合策略优先级）:**
   - `data-testid` - 最高优先级
   - `aria-label` + role - 无障碍标准
   - Text content + role - 兜底方案

2. **错误处理策略:**
   - 使用 `E2ETestError` 类（来自 e2e-test-utils）
   - 包含完整 ErrorContext

3. **类型系统:**
   - 所有方法必须有完整的 TypeScript 类型定义
   - 禁止使用 `any` 类型

4. **测试基础设施:**
   - 测试文件位置: `web/tests/e2e/specs/admin/`
   - Page Object 位置: `web/tests/e2e/pages/admin/`
   - Fixtures 位置: `web/tests/e2e/fixtures/`

### TypeScript + Playwright 陷阱预防

**来自 Architecture.md "TypeScript + Playwright 常见陷阱" 部分:**

⚠️ **DOM 结构假设必须验证**
- 不能基于理想模型开发选择器
- 必须在真实组件上验证 DOM 结构
- 单元测试无法发现真实 DOM 问题

✅ **正确做法:**
```typescript
// 使用 Playwright API 而非 page.evaluate()
const text = await element.textContent();

// 使用精确文本匹配
page.locator(`.option:text-is("广东省")`)

// 使用 data-testid 作为首选
page.getByTestId('region-name-input')
```

❌ **避免:**
```typescript
// 避免使用 page.evaluate()
const text = await page.evaluate(el => el.textContent, element);

// 避免部分文本匹配
page.locator(`.option:has-text("广东省")`)
```

### 代码质量检查清单

基于 Architecture.md 的实现检查清单：

**代码质量:**
- [ ] 所有导出方法都有完整的 JSDoc
- [ ] 内部方法使用 `@internal` 标记
- [ ] 错误处理提供友好消息

**选择器策略:**
- [ ] 优先使用 `data-testid` 或 `getByRole()`
- [ ] 文本选择器使用精确匹配
- [ ] DOM 结构基于真实组件验证

**配置和超时:**
- [ ] 超时值使用合理配置
- [ ] 网络操作使用 `waitForLoadState('networkidle')`

**DOM 操作:**
- [ ] 避免使用 `page.evaluate()`
- [ ] 优先使用 Playwright API

### 参考文档位置

| 文档 | 路径 |
|------|------|
| PRD | `_bmad-output/planning-artifacts/prd.md` |
| Architecture | `_bmad-output/planning-artifacts/architecture.md` |
| Epics | `_bmad-output/planning-artifacts/epics.md` |
| Project Context | `_bmad-output/project-context.md` |
| 参考Page Object | `web/tests/e2e/pages/admin/disability-person.page.ts` |
| e2e-test-utils | `packages/e2e-test-utils/src/index.ts` |

### 相关 Epic 和 Story

**前置 Epic:**
- Epic 1: ✅ 完成 - Select 工具基础框架
- Epic 2: ✅ 完成 - Select 工具在真实 E2E 测试中验证
- Epic 3: ✅ 完成 - 文件上传工具、级联选择工具

**当前 Epic (Epic 8):**
- Story 8.1: 📝 当前 - 创建区域管理 Page Object
- Story 8.2: ⏳ 待开始 - 编写区域列表查看测试
- Story 8.3: ⏳ 待开始 - 编写添加区域测试
- Story 8.4: ⏳ 待开始 - 编写编辑区域测试
- Story 8.5: ⏳ 待开始 - 编写删除区域测试
- Story 8.6: ⏳ 待开始 - 编写级联选择完整流程测试

**后续 Epic:**
- Epic 9: 🔄 进行中 - 残疾人管理完整 E2E 测试覆盖

## Completion Status

**Story ID:** 8.1
**Story Key:** 8-1-region-page-object
**Epic:** Epic 8 - 区域管理 E2E 测试 (Epic B)
**Status:** ready-for-dev

**交付物:**
- [x] Story 文档创建完成
- [ ] RegionManagementPage 类实现
- [ ] TypeScript 类型定义
- [ ] DOM 结构探索和验证
- [ ] 代码审查和测试

**下一步操作:**
1. 运行 `/bmad:bmm:workflows:dev-story` 开始实现
2. 探索区域管理页面的实际 DOM 结构
3. 实现 RegionManagementPage 类
4. 编写基础测试验证 Page Object 可用性

**Ultimate context engine analysis completed - comprehensive developer guide created**