Web 员工模块 — CUJ 关键用户旅程

Employees, Schedules, Time Clock & Payroll | 更新时间: 2026-02-09

架构概览

数据关系

flowchart TB
    EMP["employees\n基本信息/角色/门店"] --> SCH["employee_schedules\n每日排班 (date-specific)"]
    EMP --> WKS["employee_work_schedules\n周模板 (recurring)"]
    EMP --> CAP["employee_service_capabilities\n服务能力"]
    EMP --> PIN["employee_pins\nPIN 打卡码"]
    EMP --> TC["time_cards\n每日考勤卡"]
    TC --> TP["time_punches\n打卡记录"]
    EMP --> PR["payroll_reports\n工资单"]
    EMP --> APT["appointments\n被分配的预约"]

    WKS -->|"AutoSchedule\n模板生成"| SCH
    SCH -->|"影响"| AVAIL["可预约时段\nemployee_available_start_times"]
    TC -->|"汇总到"| PR

排班层级

打卡类型

目录

CUJ 总览与优先级矩阵

CUJ-D1: 员工列表与详情管理

P0 人事基础 — 员工 CRUD、服务能力、特殊权限、门店调动

用户流程

flowchart TD
    A["侧边栏 → Employees"] --> B["员工列表\n筛选: 门店/职位/状态"]
    B --> C{操作?}
    C -->|"添加"| D["AddEmployeeModal\n姓名/邮箱/角色/门店"]
    D --> E["自动生成 employee ID"]
    C -->|"查看详情"| F["/employees/id"]
    F --> G["Tab 1: 基本信息\n姓名/邮箱/角色/职位/头像"]
    F --> H["Tab 2: 服务能力\n多选 checklist"]
    F --> I["Tab 3: 特殊权限\nGRANT/DENY (super_admin only)"]
    C -->|"停用"| J["is_active → false\n不再出现在排班/预约"]

    style B fill:#2196F3,stroke:#1565C0,color:#fff
    style F fill:#4CAF50,stroke:#2E7D32,color:#fff

BDD 场景

场景 D1.1: 查看员工列表 — 筛选与搜索

测试: employees.spec.ts

场景 D1.2: 添加新员工

测试: full-flow/02c-employee-crud.spec.ts

场景 D1.3: 管理服务能力

场景 D1.4: 管理特殊权限 (super_admin only)

场景 D1.5: 停用/终止员工

CUJ-D2: 排班管理

P0 运营基础 — 技师排班直接影响 employee_available_start_times，进而影响可预约时段

用户流程

flowchart TD
    A["/employees/schedules\n排班总览"] --> B{视图模式?}
    B -->|"List"| C["表格视图\n排班统计/今日状态"]
    B -->|"Kanban"| D["ScheduleKanbanBoard\n周视图所有技师"]
    D --> E{操作?}
    E -->|"手动"| F["点击空白格子\n设置时间段"]
    E -->|"模板"| G["WeeklyTemplateModal\n编辑周模板"]
    E -->|"自动生成"| H["GenerateScheduleModal\n按模板批量生成N周"]
    E -->|"智能排班"| I["AutoScheduleModal\n规则自动生成"]

    C --> J["点击员工\n→ /schedules/employeeId"]
    J --> K["个人日历视图\n月度排班详情"]

    style A fill:#2196F3,stroke:#1565C0,color:#fff
    style K fill:#4CAF50,stroke:#2E7D32,color:#fff

BDD 场景

场景 D2.1: 手动创建排班

测试: full-flow/02d-schedule-crud.spec.ts

场景 D2.2: 使用模板批量生成排班

测试: schedule-templates/schedule-generation.spec.ts

场景 D2.3: 设置休假

场景 D2.4: 查看个人排班日历

CUJ-D3: PIN 打卡与考勤

P0 考勤管理 — PIN/Click 两种打卡方式，自动计算迟到/早退

用户流程

flowchart TD
    A["/employees/time-clock\nQuickClockPanel"] --> B{打卡方式?}
    B -->|"PIN 打卡"| C["输入 4-6 位 PIN"]
    B -->|"Click 打卡"| D["选择员工\n点击打卡按钮"]
    C --> E{PIN 正确?}
    E -->|"否"| F["错误提示\n失败次数+1"]
    F --> G{5次失败?}
    G -->|"是"| H["PIN 锁定 30 分钟"]
    G -->|"否"| C
    E -->|"是"| I{当前状态?}
    D --> I
    I -->|"未打卡"| J["Clock In\n记录上班时间"]
    I -->|"已打卡"| K["Clock Out\n记录下班时间"]
    I -->|"休息中"| L["Break End\n结束休息"]
    J --> M["对比排班计算\n迟到分钟数"]
    K --> N["对比排班计算\n早退分钟数"]

    style A fill:#2196F3,stroke:#1565C0,color:#fff
    style J fill:#4CAF50,stroke:#2E7D32,color:#fff
    style K fill:#FF9800,stroke:#E65100,color:#fff

BDD 场景

场景 D3.1: PIN 打卡上班

测试: time-clock.spec.ts

场景 D3.2: PIN 打卡下班

场景 D3.3: 休息打卡

场景 D3.4: PIN 锁定 — 5 次失败

场景 D3.5: PIN 设置

测试: time-clock.spec.ts (部分覆盖)

CUJ-D4: 工时卡与补卡审批

P1 考勤审核 — 双模式查看工时，补卡需管理员审批

用户流程

flowchart TD
    A["/employees/time-cards"] --> B{用户角色?}
    B -->|"员工"| C["My Time Cards\n只看自己的记录"]
    B -->|"管理员"| D["All Time Cards\n所有员工 + 筛选"]
    D --> E["Tab: cards / pending"]
    E -->|"cards"| F["工时卡列表\n汇总: 总天数/总工时/迟到数/早退数"]
    E -->|"pending"| G["待审批补卡列表"]
    G --> H{审批操作}
    H -->|"批准"| I["approveMakeupPunch\n补卡写入工时卡"]
    H -->|"拒绝"| J["rejectMakeupPunch\n填写拒绝原因"]

    C --> K["查看详情\nTimeCardDetailModal"]
    F --> K
    K --> L["打卡明细\nclock_in/out/break 时间线"]

    style A fill:#2196F3,stroke:#1565C0,color:#fff
    style I fill:#4CAF50,stroke:#2E7D32,color:#fff
    style J fill:#f44336,stroke:#c62828,color:#fff

BDD 场景

场景 D4.1: 员工查看自己的工时卡

场景 D4.2: 管理员查看所有工时卡

场景 D4.3: 提交补卡申请

场景 D4.4: 审批补卡 — 批准

场景 D4.5: 导出工时卡 CSV

CUJ-D5: 小费管理

P1 收入管理 — 查看技师小费明细

BDD 场景

场景 D5.1: 查看小费汇总

测试: employees/tips.spec.ts

场景 D5.2: 员工查看自己的小费

CUJ-D6: 工资单

P2 薪酬管理 — 生成和管理员工工资单

工资单状态流转

flowchart LR
    A["draft\n草稿"] -->|"finalizePayroll()"| B["finalized\n已确认"]
    B -->|"markAsPaid()"| C["paid\n已发放"]

BDD 场景

场景 D6.1: 生成工资单

测试: payroll.spec.ts (部分覆盖)

场景 D6.2: 确认并发放工资

跨模块链接

关键业务规则