---
name: store-customer
description: 门店会员与客户：建档、储值、次卡、跟进、导入导出、生日/到期查询。触发：建档/查客户/充值/开卡/跟进/导入客户/导出/本月生日/到期提醒。
---

# 会员与客户

面向门店会员运营的轻量 CRM：对话驱动，关键写操作经 CLI 与确认流。

## 关键原则

- **先预览、后写入**：导入须先执行 `preview` 子命令 → 用户确认 → `commit --yes`（均属 `import` 命令组）
- **删除/充值/开卡须确认**：加 `--yes`；重名或模糊命中不直接执行
- **统一数据库**：`STORE_DB_PATH`（默认 `%USERPROFILE%\.config\store-suite\store.sqlite3`）

## 首次使用

首次调用本 skill CLI 时会**自动建库并导入默认样例**（`connect()` 触发 migrate + seed），无需手动 migrate/seed。若需空库，设置 `STORE_SKIP_AUTO_SEED=1`。

## 输出格式

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

## 用法

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

## 文件导入

1. 定位文件：优先工作目录 `media/inbound/` 最新上传，或用户给定路径
2. 预览：在批量导入命令组下执行子命令 `preview`（`--path` 指向文件）
3. 向用户展示预览结果中的客户数、新字段、告警
4. 确认后写入：同一命令组下执行子命令 `commit` 并加 `--yes`

完整命令行示例见 [references/verified-queries.md](references/verified-queries.md)（「导入客户表预览」「确认导入客户」）。

支持 `.csv` / `.xlsx` / `.xls` / `.md`。分组多行记录会写入跟进记录。

## 导出

```bash
uv run {baseDir}/scripts/cli.py export file --output "./members.csv" [--with-wallet]
```

## 边界

本 skill 只写入业务数据（birthday、due_date、followup-add 等），不注册定时任务或 cron。提醒注册不属于本 skill 职责，请向用户说明需另行设置定时提醒。

## 主要子命令

| 子命令 | 用途 |
|--------|------|
| member-add / update / query / delete / restore | 会员档案 |
| member-birthdays --month 3 | 本月生日 |
| member-due --within-days 30 | N 天内生日/到期日/自定义到期 |
| member-txn-query | 流水 |
| balance-recharge / balance-query | 储值 |
| card-open / card-query / card-expiring | 次卡 |
| followup-add / followup-query / followup-due | 跟进 |
| field-def-* | 会员扩展字段 |
| 批量导入 preview / commit | 批量导入 |
| export file | 导出 |

`member-query` 扩展：`--due-within-days`、`--filters-json`、`--with-wallet --with-cards --with-profile --with-fields`

## 自然语言 → 命令

见 [references/verified-queries.md](references/verified-queries.md)。

## 示例

```bash
uv run {baseDir}/scripts/cli.py member-add --name "王芳" --phone "13900139000"
uv run {baseDir}/scripts/cli.py member-birthdays --month 3
uv run {baseDir}/scripts/cli.py balance-recharge --member-id M001 --amount 1000 --yes
```
