📋 Appointment 状态流转规范

状态列表

状态	中文名称	说明
`pending`	待确认	预约创建，等待确认
`confirmed`	已确认	预约已确认
`checked_in`	已签到	客户已到店
`in_progress`	服务中	正在服务
`completed`	服务完成	服务结束，paid_amount = 0
`pending_payment`	待付款	部分付款，paid_amount > 0 但 < total
`finished`	已结账	全额付款完成，paid_amount = total
`closed`	已关闭	最终状态
`cancelled`	已取消	预约取消，不在 Board 显示
`no_show`	未到店	客户爽约

正常业务流程

pending ──► confirmed ──► checked_in ──► in_progress ──► completed
   │            │             │              │              │
   │            │             │              │              │
   └────────────┴─────────────┴──────────────┴──────────────┘
                              │
                              ▼
                    (可从任意前置状态直接跳转到 completed)

付款流程

                         completed
                    (服务完成, paid_amount = 0)
                             │
           ┌─────────────────┼─────────────────┐
           ▼                 │                 ▼
      部分付款               │             全额付款
           │                 │                 │
           ▼                 │                 ▼
   pending_payment           │            finished
  (paid_amount > 0)          │       (paid_amount = total)
           │                 │                 │
           │    补齐付款     │                 │
           └────────────────►│                 │
                             │                 ▼
                             │              closed
                             │           (最终状态)
                             │
                             ▼
                         cancelled
                    (可从 completed 取消)

退款流程

全额退款

finished ──► 全额退款 ──► completed
              │
              ├── paid_amount = 0
              └── payment_status = pending

部分退款

finished ──► 部分退款 ──► pending_payment
              │
              ├── paid_amount > 0
              └── payment_status = partial

状态判断规则（基于 amount_due）

公式：amount_due = total_amount - paid_amount

amount_due	含义	status	payment_status
= total_amount	完全没付钱 (paid_amount = 0)	`completed`	`pending`
> 0 且 < total_amount	付了部分，未付完	`pending_payment`	`partial`
= 0	全额付清 (paid_amount = total)	`finished`	`paid`

付款/退款状态变化表

操作	amount_due 变化	status	payment_status
服务完成（未付款）	= total_amount	`completed`	`pending`
部分付款	> 0 且 < total	`pending_payment`	`partial`
全额付款	= 0	`finished`	`paid`
全额退款	= total_amount	`completed`	`pending`
部分退款	> 0 且 < total	`pending_payment`	`partial`
手动关闭	-	`closed`	不变

取消规则

状态	可取消	原因
`pending`	✅	服务完成前
`confirmed`	✅	服务完成前
`checked_in`	✅	服务完成前
`in_progress`	✅	服务完成前
`completed`	✅	paid_amount = 0，无欠款
`pending_payment`	❌	paid_amount > 0，有欠款
`finished`	❌	已结账，需先全额退款
`closed`	❌	最终状态，不可变更

取消流程图

┌─────────────────────────────────────────────────────────────────┐
│  可取消的状态 (paid_amount = 0)                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  pending ─┬─► cancelled ──► 不在 Board 显示                     │
│  confirmed ─┤                                                   │
│  checked_in ─┤                                                  │
│  in_progress ─┤                                                 │
│  completed ──┘                                                  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│  不可取消的状态                                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  pending_payment ──► 需先退款至 paid_amount=0 ──► completed     │
│                                                  ──► 可取消     │
│                                                                 │
│  finished ──► 需先全额退款 ──► completed ──► 可取消              │
│                                                                 │
│  closed ──► 最终状态，不可变更                                   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

状态转换矩阵

从 ↓ 到 →	pending	confirmed	checked_in	in_progress	completed	pending_payment	finished	closed	cancelled	no_show
`pending`	-	✅	✅	✅	✅	-	-	-	✅	✅
`confirmed`	✅	-	✅	✅	✅	-	-	-	✅	✅
`checked_in`	✅	✅	-	✅	✅	-	-	-	✅	-
`in_progress`	✅	✅	✅	-	✅	-	-	-	✅	-
`completed`	-	-	-	-	-	部分付款	全额付款	-	✅	-
`pending_payment`	-	-	-	-	全额退款	-	补齐付款	-	❌	-
`finished`	-	-	-	-	全额退款	部分退款	-	✅	❌	-
`closed`	-	-	-	-	-	-	-	-	❌	-
`cancelled`	-	-	-	-	-	-	-	-	-	-
`no_show`	-	-	-	-	-	-	-	-	-	-

说明

pending, confirmed, checked_in, in_progress 这四个状态之间可以互相切换
closed 只能从 finished 状态转换过来

更新日期: 2026-02-02