---
name: store-appointment
description: 预约创建/改期/取消、服务人员推荐、完成服务结算。触发：预约/改期/做完了/混合支付/多人分成。
---

# 预约与履约

## 用法

```bash
uv run {baseDir}/scripts/cli.py <子命令> ...
```

默认库：`STORE_DB_PATH`（默认 `%USERPROFILE%\.config\store-suite\store.sqlite3`）。

## 输出格式

stdout 单行 JSON：成功 `"ok": true`；需确认 `"error": "need_confirm"`；失败含 `"error"` 码。详见 [references/errors.md](references/errors.md)。

## 主要子命令

| 子命令 | 用途 |
|--------|------|
| appt-create | 创建预约 |
| appt-query | 查询预约（--member-id / --date-from / --date-to） |
| appt-update | 改期 / 改服务人员 / 改项目 |
| appt-suggest-slots | 冲突备选时段 |
| appt-cancel --yes | 取消预约 |
| appt-complete --yes | 完成服务并结算 |
| tech-recommend | 推荐可用服务人员 |
| tech-auto-assign | 自动指派服务人员 |

## 自然语言 → 命令

| 用户说 | 命令 |
|--------|------|
| 给王芳约明天下午基础服务 | `uv run {baseDir}/scripts/cli.py appt-create --member-id M001 --service "基础服务" --datetime "2026-06-01 15:00" --technician-id S001` |
| 做完了储值扣款 | `uv run {baseDir}/scripts/cli.py appt-complete --appt-id A001 --pay stored_value --yes` |
| 混合支付 200 储值 98 现金 | `uv run {baseDir}/scripts/cli.py appt-complete --appt-id A001 --pay mixed --lines-json '[{"type":"consume","amount":200},{"type":"cash","amount":98}]' --yes` |
| 谁有空做基础服务 | `uv run {baseDir}/scripts/cli.py tech-recommend --service "基础服务" --datetime "2026-06-01 15:00"` |

完整口语映射见 [references/verified-queries.md](references/verified-queries.md)。

> **预约 ID**：默认 seed 含样例 `A001`；空库须先 `appt-create`。CLI 参数 `--technician-id` 为 schema 字段名，中文称「服务人员」。

## 需要先确认的操作

- `appt-cancel`、`appt-complete` 须先展示确认卡片，用户确认后加 `--yes`。
- 次卡结算须加 `--card-name`（须为会员名下有效次卡名称）。

## 注意事项

- 数据库：`STORE_DB_PATH`（默认 `%USERPROFILE%\.config\store-suite\store.sqlite3`）。
- 完成服务（`appt-complete`）会触发支付、库存扣减、员工业绩写入；库存不足时整单回滚。
- 混合支付须 `--lines-json`；多人分成须 `--staff-lines-json`。
- 错误码见 [references/errors.md](references/errors.md)。

## 示例

```bash
uv run {baseDir}/scripts/cli.py appt-create --member-id M001 --service "基础服务" --datetime "2026-06-01 15:00" --technician-id S001
uv run {baseDir}/scripts/cli.py appt-complete --appt-id A001 --pay stored_value --yes
uv run {baseDir}/scripts/cli.py appt-complete --appt-id A002 --pay card --card-name "基础服务10次卡" --yes
uv run {baseDir}/scripts/cli.py appt-complete --appt-id A003 --pay mixed --lines-json '[{"type":"consume","amount":200},{"type":"cash","amount":98}]' --yes
uv run {baseDir}/scripts/cli.py appt-complete --appt-id A004 --staff-lines-json '[{"line":0,"staff_id":"S001","role":"primary","split":0.7},{"line":0,"staff_id":"S002","role":"assist","split":0.3}]' --yes
```
