Product Design Methodology — CUJ 四步走

Section 1: 方法论概览

四层流水线 (4-Layer Pipeline)

1. CUJ (Critical User Journey) — 识别"什么最重要" (产品/UX 视角)
2. User Flow (流程图) — 定义"怎么走" (设计/技术视角)
3. BDD Scenarios (Given-When-Then) — 定义"什么算对" (业务↔工程桥梁)
4. E2E Test Code — 自动验证 (integration_test / Playwright)

Section 2: 适用范围

Section 3: CUJ 优先级体系

Section 4: 各层详解

Layer 1: CUJ (Critical User Journey)

关键用户旅程，定义用户完成核心任务的完整路径。

Layer 2: User Flow (流程图)

将 CUJ 转化为页面级流程图，定义页面跳转和决策点。

Layer 3: BDD Scenarios (Given-When-Then)

用业务语言描述测试场景，连接产品需求和技术实现。

# Scenario: 客人成功预约服务

Given 用户已登录 Guest App
  And 用户在服务选择页
  And "Manicure" 服务可用

When 用户点击 "Manicure"
  And 用户选择 "Any Technician"
  And 用户选择明天下午 2:00 PM 的时段
  And 用户填写联系信息（姓名、电话）
  And 用户点击 "Confirm Booking"

Then 系统应显示 "Booking Successful" 消息
  And 用户应看到预约确认页
  And 预约应出现在 "My Appointments" 列表中

Layer 4: E2E Test Code

将 BDD 场景转化为可执行的自动化测试代码。

// Flutter Integration Test 示例
testWidgets('CUJ1: Guest books a manicure service', (tester) async {
  // Given: 用户已登录
  await _login(tester, 'guest@example.com', 'password123');
  await tester.pumpAndSettle();

  // When: 选择服务
  await tester.tap(find.text('Manicure'));
  await tester.pumpAndSettle();

  // When: 选择技师和时间
  await tester.tap(find.text('Any Technician'));
  await tester.pumpAndSettle();

  await tester.tap(find.byType(TimeSlotCard).first);
  await tester.pumpAndSettle();

  // When: 填写信息并确认
  await tester.enterText(find.byType(TextField).first, 'John Doe');
  await tester.enterText(find.byType(TextField).last, '555-0123');
  await tester.tap(find.text('Confirm Booking'));
  await tester.pumpAndSettle();

  // Then: 验证成功
  expect(find.text('Booking Successful'), findsOneWidget);
  expect(find.byType(SuccessPage), findsOneWidget);
});

Section 5: 轻量化执行方案

✅ 建议做的事

• 从 P0 CUJ 开始，优先覆盖核心路径
• 每周迭代 1-2 条 CUJ，持续积累
• BDD 场景保持简洁（每个 3-5 步）
• E2E 测试与 BDD 场景 1:1 映射
• 定期回顾和更新文档（每月）

❌ 不建议做的事

• 引入 Cucumber engine（过度工程）
• 追求 100% coverage（边际收益递减）
• 绘制精美的 Storyboard（时间成本高）
• 为每个小功能创建独立 CUJ（粒度太细）
• 在 BDD 中包含技术实现细节（违背业务语言原则）

Section 6: 概念辨析

Section 7: Web 管理端 — 按模块拆分 CUJ

为什么要拆分

• 规模差异: Guest App 25 页 / 7 CUJ → 一个文档；Web App 134 页 + 37 弹窗 → 硬塞一个文档会失控
• 角色差异: Mobile 单角色线性流程；Web 多角色（Admin/Manager/Employee）在模块间自由切换
• 维护性: 按模块拆分后可以分工并行，改一个模块不影响其他文档
• 追溯性: 每个文档的 Coverage Gap 直接对应该模块的 E2E spec 文件

建议的拆分方案

Section 8: Page↔CUJ 追溯矩阵 (Traceability Matrix)

方法论: 四层追溯

Step 1: Page Registry（自动）

脚本自动扫描所有 page.tsx 和 *Modal*.tsx / *Dialog*.tsx，生成注册表。

// page-registry.json 格式
{
  "pages": [
    {
      "id": "admin-appointments",
      "route": "/admin/appointments",
      "file": "src/app/[locale]/[tenant]/admin/appointments/page.tsx",
      "module": "appointments",
      "cuj_refs": [],           // ← 由 Step 3 填充
      "e2e_refs": [],           // ← 由 Step 3 填充
      "status": "uncovered"     // uncovered | covered | exempt
    }
  ],
  "modals": [
    {
      "id": "new-appointment-modal",
      "file": "src/components/Appointment/NewAppointmentModal.tsx",
      "module": "appointments",
      "cuj_refs": [],
      "e2e_refs": [],
      "status": "uncovered"
    }
  ]
}

Step 2: CUJ 文档中标注触及的页面（人工）

每个 CUJ 文档的 User Flow 和 BDD Scenarios 中，用 <!-- TOUCHES: page-id, modal-id --> 注释标注触及的页面和弹窗。

<!-- ======= CUJ-1: 日结关账完整流程 ======= -->
<!-- TOUCHES: admin-day-end-closeout, day-end-closeout-modal,
              currency-count-modal, close-register-modal,
              unlock-closeout-modal -->

<h3>User Flow</h3>
<div class="mermaid">
  flowchart TD
    A[日结主页 admin-day-end-closeout] --> B[点击开始日结]
    B --> C[DayEndCloseoutModal 5步流程]
    ...
</div>

<h3>BDD Scenarios</h3>
<!-- ... Given/When/Then ... -->
<p class="test-file">E2E: day-end-closeout.spec.ts</p>

Step 3: Traceability Matrix（自动校验）

校验脚本读取 Page Registry + 所有 CUJ 文档中的 TOUCHES 注释，输出追溯矩阵。

// 校验脚本: scripts/check-cuj-coverage.js
//
// 输入:
//   1. page-registry.json（自动生成）
//   2. notes/product-design/web-*.html（人工标注 TOUCHES）
//   3. frontend/web_app/tests/e2e/*.spec.ts（E2E 测试文件）
//
// 输出:
//   ✅ admin-appointments     → W-APT-CUJ-1, W-APT-CUJ-2  → appointments-board.spec.ts
//   ✅ new-appointment-modal  → W-APT-CUJ-1               → appointments-board.spec.ts
//   ❌ admin-gift-cards       → (NOT COVERED)              → (NO E2E)
//   ⚠️ admin-storybook        → EXEMPT (internal tool)
//   ❌ refund-modal           → (NOT COVERED)              → (NO E2E)

Step 4: Gap Report（输出）

Gap Report 将未覆盖的页面/弹窗分为三类：

Exempt（豁免）页面的判定标准

• 开发工具: storybook, developer-settings, sync-config, cost-calculator, competitor-analysis
• 测试页面: chat-test, voice-test, booking/test
• 法律页面: terms, privacy
• 监控页面: monitoring/dashboard
• 平台管理: platform/* (内部运营，非客户功能)
• 通用组件: ConfirmDialog (被所有模块共用，不属于特定 CUJ)

实施节奏

总结

相关文档:

• Mobile Apps:
  • Guest App CUJ 文档 (7 CUJs, 25 pages)
  • Employee App CUJ 文档 (5 CUJs, 24 pages)
  • Kiosk App CUJ 文档 (3 CUJs, 8 pages)
• Web Admin (按模块拆分, TBD):
  • web-day-end-closeout-cuj.html — 日结关账（优先）
  • web-appointments-cuj.html — 预约管理
  • web-employees-cuj.html — 员工管理
  • web-payments-cuj.html — 支付与收银
  • web-auth-cuj.html — 认证与会话
  • ... 详见 Section 7 完整列表
• Tracking:
  • CUJ 跟踪清单 (逐条 CUJ 确认状态、时间、版本)