Etusivu Tutki Apua
Rekisteröidy Kirjaudu sisään
188-template-179
/
mini-starter
haarautettu lähteestä 155-template-138/mini-starter
2
0
Haarauta 0
Tiedostot
Puu: 9c813ba3d5
Haarat Tunnisteet
mini-starter
/
_bmad-output
/
implementation-artifacts
/
13-12-statistics-page-validation.md

13-12-statistics-page-validation.md 13 KB
Historia Raaka

Story 13.12: 数据统计页测试与功能修复

Status: ready-for-dev

元数据

  • Epic: Epic 13 - 跨端数据同步测试
  • 状态: ready-for-dev
  • 优先级: P1
  • 故事点: 8

用户故事

作为企业管理员，我在企业小程序的数据统计页能查看各种统计数据，包括在职人数、平均薪资、在职率、新增人数等，并且可以通过年份和月份筛选器查看不同时期的统计数据。统计数据应该从后台 API 动态获取，而非硬编码。

验收标准

AC 1: 数据统计页可访问性和 UI 验证

Given 用户已登录企业小程序 When 用户点击底部导航的"数据"tab Then 应能成功导航到数据统计页 And 页面应显示筛选器区域（年份选择器、月份选择器） And 页面应显示 4 个统计卡片（在职人数、平均薪资、在职率、新增人数） And 页面应显示 6 个统计图表（残疾类型分布、性别分布、年龄分布、户籍省份分布、在职状态统计、薪资分布）

AC 2: 筛选器功能验证（修复后）

Given 用户在数据统计页 When 用户选择年份（如 2026） And 用户选择月份（如 1月） Then 页面应重新获取该年月的统计数据 And 统计卡片应显示更新后的数据 And 统计图表应显示更新后的数据

AC 3: 统计卡片数据验证（修复后）

Given 用户在数据统计页 When 页面加载完成 Then 统计卡片应显示从 API 获取的真实数据 And "在职人数"应显示当前在职人员总数 And "平均薪资"应显示所有在职人员的平均薪资 And "在职率"应显示在职人数占总人数的百分比 And "新增人数"应显示本月新增的人员数 And 每个统计卡片应显示与上月对比的数据

AC 4: 统计图表数据验证（修复后）

Given 用户在数据统计页 When 页面加载完成 Then "残疾类型分布"图表应显示各类残疾的人数分布 And "性别分布"图表应显示男女人数分布 And "年龄分布"图表应显示各年龄段人数分布 And "户籍省份分布"图表应显示各省份人数分布 And "在职状态统计"图表应显示各种工作状态的人数分布 And "薪资分布"图表应显示各薪资区间的人数分布

AC 5: API 支持年月查询参数（修复）

Given 数据统计 API 端点已实现 When 前端请求统计数据时传递 year 和 month 参数 Then API 应返回该年月的统计数据 And 如果未传递参数，应返回当前年月的统计数据

任务

任务 0: Bug 修复 - 统计卡片数据硬编码问题

  • 修改 yongren-statistics-ui 包中的统计卡片组件
  • 将硬编码的数据改为从 API 获取
  • 确保 API 调用正确处理响应数据

任务 1: Bug 修复 - API 支持年月查询参数

  • 修改 statistics-module 中的 API 路由
  • 为所有统计 API 端点添加 year 和 month 查询参数支持
    • /api/statistics/employment-count
    • /api/statistics/average-salary
    • /api/statistics/employment-rate
    • /api/statistics/new-count
    • /api/statistics/disability-type-distribution
    • /api/statistics/gender-distribution
  • 更新 API schema 以支持可选的 year 和 month 参数
  • 如果未传递参数，默认使用当前年月

任务 2: Bug 修复 - 筛选器连接到数据刷新逻辑

  • 修改筛选器组件，监听年份和月份的变化
  • 当筛选器值变化时，触发数据重新获取
  • 传递选中的年月参数到 API 请求
  • 显示加载状态，直到数据返回

任务 3: 准备 Page Object

  • 在 enterprise-mini.page.ts 中添加数据统计页相关方法：
    • navigateToStatisticsPage()
    • selectYear(year: number)
    • selectMonth(month: number)
    • getStatisticsCards()
    • expectStatisticsCardData(cardName: string, expected: any)
    • getStatisticsCharts()
    • expectChartData(chartName: string, expected: any)

任务 4: 创建 E2E 测试文件

  • 创建 web/tests/e2e/specs/cross-platform/statistics-page-validation.spec.ts

任务 5: 实现测试用例 - AC1 可访问性和 UI 验证

  • 测试：验证数据统计页可以正常访问
  • 测试：验证筛选器 UI 元素存在
  • 测试：验证 4 个统计卡片显示
  • 测试：验证 6 个统计图表显示

任务 6: 实现测试用例 - AC2 筛选器功能验证（修复后）

  • 测试：选择年份后数据更新
  • 测试：选择月份后数据更新
  • 测试：筛选器变化后显示加载状态

任务 7: 实现测试用例 - AC3 统计卡片数据验证（修复后）

  • 测试：验证在职人数数据正确性
  • 测试：验证平均薪资数据正确性
  • 测试：验证在职率数据正确性
  • 测试：验证新增人数数据正确性
  • 测试：验证月度对比数据显示

任务 8: 实现测试用例 - AC4 统计图表数据验证（修复后）

  • 测试：验证残疾类型分布图表数据
  • 测试：验证性别分布图表数据
  • 测试：验证年龄分布图表数据
  • 测试：验证户籍省份分布图表数据
  • 测试：验证在职状态统计图表数据
  • 测试：验证薪资分布图表数据

任务 9: 实现测试用例 - AC5 API 年月参数验证

  • 测试：验证 API 不传参数时返回当前年月数据
  • 测试：验证 API 传递年月参数时返回对应数据
  • 测试：验证边界情况（无效年月参数）

任务 10: 集成测试与稳定性验证

  • 测试：完整的数据统计页用户流程
  • 测试：快速切换年月的边界情况
  • 测试：无数据时的显示状态
  • 稳定性验证：连续运行 10 次，100% 通过

Dev Notes

Epic 13 背景和依赖

Epic 13: 跨端数据同步测试 (Epic E)

  • 目标: 验证后台操作后小程序端的数据同步，覆盖完整的业务流程
  • 业务分组: Epic E（跨端数据同步测试）
  • 背景: 真实用户旅程跨越管理后台和小程序，需要验证数据同步的正确性和时效性
  • 依赖:
    • Epic 10: ✅ 已完成（订单管理 E2E 测试）
    • Epic 12: 🔄 进行中（小程序登录测试）

数据统计页 URL

/mini/#/mini/pages/yongren/statistics/index

数据统计页字段清单

筛选功能

  • 年份选择器：2022-2026
  • 月份选择器：1-12月

统计卡片（4个）

  • 在职人数：count_employed，带月度对比
  • 平均薪资：avg_salary，带月度对比
  • 在职率：employment_rate，带月度对比
  • 新增人数：count_new_month，带月度对比

统计图表（6个）

  • 残疾类型分布：disabilityType（柱状图）
  • 性别分布：gender（柱状图）
  • 年龄分布：age（饼图）
  • 户籍省份分布：province（条形图）
  • 在职状态统计：employmentStatus（环形图）
  • 薪资分布：salary（条形图）

相关文件

  • 页面源码: mini/src/pages/yongren/statistics/index.tsx
  • 统计UI包: mini-ui-packages/yongren-statistics-ui/
  • API 路由: allin-packages/statistics-module/src/routes/statistics.routes.ts
  • API Schema: allin-packages/statistics-module/src/schemas/statistics.schema.ts

已知问题

  1. 统计卡片数据硬编码

    • 当前状态：数据是硬编码在组件中
    • 影响：显示的数据不是真实的统计数据
    • 修复方案：调用 API 获取真实数据

  2. API 不支持年月查询参数

    • 当前状态：API 端点不接受 year 和 month 参数
    • 影响：无法按年月筛选统计数据
    • 修复方案：为所有统计 API 添加 year 和 month 查询参数支持

  3. 筛选器未连接到数据刷新逻辑

    • 当前状态：切换年份和月份不会触发数据刷新
    • 影响：筛选器功能无效
    • 修复方案：监听筛选器变化并触发数据重新获取

测试开发流程（Playwright MCP 持续验证）

本 Story 采用 Playwright MCP 持续验证的测试开发流程：

  1. 即时验证: 在开发过程中立即使用 Playwright MCP 验证，不等到专门的 E2E Story
  2. 持续反馈: 每完成一个功能模块立即验证，快速发现问题
  3. 减少返工: 早期发现问题可以减少后期返工成本

任务流程:

任务 0-2 (Bug 修复) → 任务 3 (Page Object) → 任务 4-9 (E2E 测试) → 任务 10 (稳定性验证)

Page Object 设计

EnterpriseMiniPage 扩展方法:

// 导航到数据统计页
async navigateToStatisticsPage(): Promise<void>

// 筛选器操作
async selectYear(year: number): Promise<void>
async selectMonth(month: number): Promise<void>

// 获取统计卡片数据
async getStatisticsCards(): Promise<StatisticsCardData[]>
async expectStatisticsCardData(cardName: string, expected: any): Promise<void>

// 获取统计图表数据
async getStatisticsCharts(): Promise<StatisticsChartData[]>
async expectChartData(chartName: string, expected: any): Promise<void>

E2E 测试用例设计

AC1: 可访问性和 UI 验证

test('应该能够访问数据统计页', async ({ enterpriseMiniPage }) => {
  await enterpriseMiniPage.navigateToStatisticsPage();
  await expect(enterpriseMiniPage.page).toHaveURL(/\/statistics/);
});

test('应该显示所有统计卡片和图表', async ({ enterpriseMiniPage }) => {
  await enterpriseMiniPage.navigateToStatisticsPage();
  // 验证 4 个统计卡片
  await expect(enterpriseMiniPage.page.getByTestId('card-count-employed')).toBeVisible();
  await expect(enterpriseMiniPage.page.getByTestId('card-avg-salary')).toBeVisible();
  await expect(enterpriseMiniPage.page.getByTestId('card-employment-rate')).toBeVisible();
  await expect(enterpriseMiniPage.page.getByTestId('card-count-new-month')).toBeVisible();
  // 验证 6 个统计图表
  await expect(enterpriseMiniPage.page.getByTestId('chart-disability-type')).toBeVisible();
  await expect(enterpriseMiniPage.page.getByTestId('chart-gender')).toBeVisible();
  await expect(enterpriseMiniPage.page.getByTestId('chart-age')).toBeVisible();
  await expect(enterpriseMiniPage.page.getByTestId('chart-province')).toBeVisible();
  await expect(enterpriseMiniPage.page.getByTestId('chart-employment-status')).toBeVisible();
  await expect(enterpriseMiniPage.page.getByTestId('chart-salary')).toBeVisible();
});

AC2: 筛选器功能验证

test('选择年份后应更新统计数据', async ({ enterpriseMiniPage }) => {
  await enterpriseMiniPage.navigateToStatisticsPage();
  await enterpriseMiniPage.selectYear(2025);
  // 验证数据已更新
  const cards = await enterpriseMiniPage.getStatisticsCards();
  expect(cards).toHaveLength(4);
});

test('选择月份后应更新统计数据', async ({ enterpriseMiniPage }) => {
  await enterpriseMiniPage.navigateToStatisticsPage();
  await enterpriseMiniPage.selectMonth(12);
  // 验证数据已更新
  const cards = await enterpriseMiniPage.getStatisticsCards();
  expect(cards).toHaveLength(4);
});

API 修复方案

添加年月查询参数支持:

// 更新 API Schema
export const statisticsQuerySchema = z.object({
  year: z.coerce.number().min(2020).max(2030).optional(),
  month: z.coerce.number().min(1).max(12).optional(),
});

// 更新路由处理器
app.get('/api/statistics/employment-count', async (c) => {
  const { year, month } = c.req.query();
  // 如果未传递参数，使用当前年月
  const queryYear = year || new Date().getFullYear();
  const queryMonth = month || new Date().getMonth() + 1;
  // ... 查询逻辑
});

前端修复方案

连接筛选器到数据刷新:

// 监听筛选器变化
useEffect(() => {
  if (selectedYear && selectedMonth) {
    fetchStatisticsData(selectedYear, selectedMonth);
  }
}, [selectedYear, selectedMonth]);

// 获取统计数据
const fetchStatisticsData = async (year: number, month: number) => {
  setLoading(true);
  try {
    const data = await api.getStatistics({ year, month });
    setStatisticsData(data);
  } catch (error) {
    console.error('获取统计数据失败:', error);
  } finally {
    setLoading(false);
  }
};

参考文档

架构文档:

  • _bmad-output/planning-artifacts/epics.md#Epic 13
  • _bmad-output/project-context.md
  • docs/standards/e2e-radix-testing.md

相关 Story 文档:

  • 13-1-order-create-sync.md (跨端测试模式参考)
  • 12-4-enterprise-mini-page-object.md (企业小程序 Page Object)
  • 12-5-enterprise-mini-login.md (企业小程序登录测试)

Dev Agent Record

Agent Model Used

Created by user request

Debug Log References

Implementation phase - no debug yet

Completion Notes List

Story 13.12 ready for development

File List

新建的文件:

  • _bmad-output/implementation-artifacts/13-12-statistics-page-validation.md - Story 文档

待创建的文件:

  • web/tests/e2e/specs/cross-platform/statistics-page-validation.spec.ts - E2E 测试文件

待修改的文件:

  • mini/src/pages/yongren/statistics/index.tsx - 数据统计页面
  • mini-ui-packages/yongren-statistics-ui/ - 统计 UI 组件
  • allin-packages/statistics-module/src/routes/statistics.routes.ts - API 路由
  • allin-packages/statistics-module/src/schemas/statistics.schema.ts - API Schema
  • web/tests/e2e/pages/mini/enterprise-mini.page.ts - Page Object 扩展

Change Log

  • 2026-01-14: Story 13.12 创建完成
    • 数据统计页测试与功能修复需求
    • 5 个验收标准（AC）
    • 11 个任务（包含 3 个 Bug 修复任务）
    • 状态：ready-for-dev