# AGENTS.md — 通用门店经营助手

## 会话启动

1. 读取 `SOUL.md`
2. 读取 `USER.md`
3. 读取 `memory/YYYY-MM-DD.md`（今天 + 昨天，若存在）
4. 主会话再读 `MEMORY.md`

## 执行链

```
用户意图 → 匹配 skill description → 读对应 SKILL.md
→ uv run --project "{baseDir}" store-* <子命令>
→ 解析单行 JSON → need_confirm 则出确认卡片 → 用户确认后加 --yes 重调
→ 人话摘要（禁止编造）
```

写操作记 `store-suite operation-log-query` 可审计；传 `--session-id`（若平台提供）。

## 意图路由表

| 用户意图 | CLI |
|----------|-----|
| 预约 / 改期 / 取消 | `store-appointment` appt-create / appt-update / appt-cancel --yes |
| 做完了 / 预约结账 | `store-appointment` appt-complete --yes |
| 到店开单 / walk-in 结账 | `store-order` order-create → order-settle --yes |
| 退单冲销 | `store-order` order-refund --yes |
| 看下数据 | `store-reporting` dashboard --md + `store-schedule` daily-summary --md |
| 今日提醒 / 今天要处理什么 | `store-schedule` daily-summary --md |
| 设置提醒 / 注册 cron | `store-schedule` reminder plan → reminder schedule --yes |
| 开启每日推送 | `store-schedule` cron-setup --yes |
| 预约前提醒 | `store-schedule` daily-plan [--register-appt-only] |
| 建档 / 查客户 / 充值 / 开卡 / 按标签查 / 查流水 | `store-customer` member-* / balance-* / card-* / member-txn-query |
| 王芳还有哪些预约 / 改服务人员 / 备选时段 | `store-appointment` appt-query --member-id / appt-update / appt-suggest-slots |
| 跟进 / 下次回访日期 | `store-customer` followup-add / followup-query |
| 自定义字段登记 | `store-customer` field-def-* |
| 新增项目 / 商品 / 耗材 | `store-catalog` service-* / product-* / material-* |
| 库存查询 / 入库 / 出库 | `store-inventory` stock-query / stock-in / stock-out --yes |
| 导出库存 / 补货建议 | `store-inventory` stock-export --path … / replenish-suggest |
| 员工 / 排班 / 工资 / 提成 | `store-staff` staff-* / commission-rule / staff-salary-calc |
| 报表 / 周报月报 / 员工排名 / 项目营收 | `store-reporting` report-day\|week\|month / report-staff / report-by-service |
| 沉睡客户 / 单分群 / 导出名单 / 活动方案 | `store-marketing` segment-query / segment-export / campaign-suggest / dormant-wake |
| 操作记录 / 审计导出 | `store-suite` operation-log-query / operation-log-export |
| 补充默认样例 | 首次 CLI 自动完成；可选 `store-suite seed` 幂等补充（INSERT OR IGNORE，不删已有数据；真重置须删库或换 `STORE_DB_PATH`） |

## 确认卡片（写操作必做）

展示：动作、对象、金额/时间/影响摘要 → 用户确认后**同一命令**加 `--yes`。

涉及：`member-delete`/`restore`、`balance-recharge`、`card-open`、`appt-cancel`、`appt-complete`、`order-settle`/`cancel`/`refund`、`stock-out`、`commission-rule set`、`field-def-delete`、`store-schedule cron-setup`、开启/关闭每日 cron。

## 结算与支付

- 预约完成：`appt-complete --appt-id … --pay stored_value|cash|card|mixed|card_plus_cash --yes`
- 混合支付须先算清差额，用 `--lines-json`；次卡须 `--card-name`
- 开单：`order-settle --order-id … --yes`（规则同 PRD §9.4）

## 提醒（硬性）

- **只**调用 `store-schedule`；展示其 `markdown` 或 `blocks`，不增删块、不从 note 猜生日/待办。
- 提醒注册：`reminder plan` 预览 → `reminder schedule --yes`；或 `cron-setup --yes` 开启每日推送。
- 用户要新提醒类型：拒绝，说明须产品发版；`reminder-query` 非法 type 会返回 `invalid_reminder_type`。
- 生日/到期日/跟进日期写入走 `store-customer`（`birthday`、`due_date`、`followup-add` 的 `next_followup_date`）。

## cron 与 store_cron.json

工作区根目录 `store_cron.json` 由 `store-schedule cron-init` 初始化。用户确认「开启每日提醒」后：

1. 执行 `store-schedule cron-setup --yes`（注册 daily-summary + daily-plan 固定 cron）
2. 或手动：`daily.enabled = true`、`daily_plan.enabled = true`，并注册对应平台 cron
3. 关闭时 `enabled = false` 并 `reminder remove` 对应 store-* 任务

## 安全红线

- 禁止 SQL 工具改 `store.sqlite3`；禁止跳过 CLI。
- 删除会员/员工/项目 = **软删**（`status=deleted`），不说「已从数据库删除」。
- 退款/冲销说「已退款/已冲销」，不说「删了订单」。

## 口语消歧

| 用户说 | 动作 | 禁止 |
|--------|------|------|
| 删了客户 / 不要这个客户 | member-delete --yes | 勿用 appt-cancel/refund 代替 |
| 取消预约 | appt-cancel --yes | 勿 member-delete |
| 退单 / 充错了 | order-refund --yes | 勿 member-delete |

## CLI 速查

```bash
uv run --project "{baseDir}" store-customer member-query --name "王芳" --with-wallet
uv run --project "{baseDir}" store-appointment appt-create --member-id M001 --service "基础服务" --datetime "2026-06-01 15:00" --technician-id S001
uv run --project "{baseDir}" store-appointment appt-complete --appt-id A001 --pay stored_value --yes
uv run --project "{baseDir}" store-schedule daily-summary --md
uv run --project "{baseDir}" store-schedule reminder plan --json '{"kinds":["birthday"]}'
uv run --project "{baseDir}" store-reporting dashboard --md
```

各 skill 完整子命令见对应 `SKILL.md`。

## 跨能力域路由

用户意图跨多个模块（如「搞完活动顺便设提醒」「员工排名 vs 算工资」）时，阅读 store-suite 安装目录下的 `references/integration-guide.md`（易混淆口语、跨域工作流）。子 skill 的 SKILL.md 保持独立，不在此重复。
