# 门店套件集成指南（跨能力域路由）

> 仅在用户意图涉及多个能力域，或子命令易混淆时阅读。各子 skill 文档保持独立，本文件为**唯一**跨模块编排入口。

## 1. 职责边界

| 能力域 | skill | 负责 | 不负责 |
|--------|-------|------|--------|
| 套件内核 | store-suite | 建库、自动 seed、审计、schema | 业务 CRUD |
| 会员 CRM | store-customer | 建档、储值、次卡、跟进、导入导出、会员 field-def | cron 注册、reminder plan/schedule |
| 产品目录 | store-catalog | 服务/产品/耗材绑定 | 库存入出库 |
| 预约履约 | store-appointment | 预约 CRUD、服务人员推荐、完成结算 | 会员建档、提醒注册 |
| 订单 | store-order | 开单、结算、退款 | 预约 |
| 库存 | store-inventory | 入出库、低库存、补货建议 | 产品定义 |
| 员工 | store-staff | 档案、排班、提成、薪资核算、staff-field-def | 经营报表排名 |
| 日程提醒 | store-schedule | 九块摘要、reminder plan/schedule、daily-plan、cron | 创建会员、创建预约 |
| 经营报表 | store-reporting | dashboard、日/周/月报、report-staff | 薪资核算排名 |
| 营销 | store-marketing | 分群、活动数据、文案/海报 playbook | 提醒注册、会员建档 |

## 2. 易混淆口语 → 正确 skill

> **排名消歧**：「员工排名 / 谁业绩最好 / 经营排名」→ store-reporting（经营业绩）；「算工资 / 薪资排名 / 内部绩效排名」→ store-staff（薪资核算视角）。

| 用户说 | 匹配 skill | 子命令 |
|--------|-----------|--------|
| 员工排名 / 谁业绩最好 / 经营排名 / 员工业绩排名 | store-reporting | `report-staff --month YYYY-MM` |
| 算工资 / 薪资排名 / 内部绩效 | store-staff | `staff-salary-calc` / `staff-ranking` |
| 设置生日提醒 / 注册 cron / 每日推送 | store-schedule | `reminder plan` → `reminder schedule --yes` / `cron-setup --yes` |
| 今天要处理什么 / 今日九块提醒 | store-schedule | `daily-summary --md` |
| 今天有哪些预约（提醒视角） | store-schedule | `reminder-query --type appt_today` |
| 今天有哪些预约（列表视角） | store-appointment | `appt-query --date YYYY-MM-DD` |
| 看下数据 / 门店概况 | store-reporting | `dashboard --md` |
| 完整待办九块（非 dashboard 摘要） | store-schedule | `daily-summary --md` |

## 3. 跨域工作流

### 会员生日数据 → 提醒注册

1. **store-customer**：确保 `birthday` 已写入（`member-add` / `member-update`）
2. 用户确认要提醒 → **store-schedule**：`reminder plan --json '{"kinds":["birthday"]}'` → `reminder schedule --json '{"kinds":["birthday"]}' --yes`

### 营销方案 → 发布提醒

1. **store-marketing**：按 playbook 输出方案与发布节点摘要
2. 用户确认要提醒 → **store-schedule**：为关键节点注册 `reminder plan` / `reminder schedule`

### 预约前需会员 ID

1. **store-customer**：`member-query --name "王芳"` 取得 `member_id`
2. **store-appointment**：`appt-create --member-id M001 ...`

### 营销需会员/分群数据

1. **store-marketing**：`segment-run` / `campaign-context`
2. 需单个会员详情 → **store-customer**：`member-query --with-wallet --with-cards`
3. 需本月生日/到期名单 → **store-customer**：`member-birthdays --month N` / `member-due --within-days 30`

## 4. 跨 skill 口语映射（从各 verified-queries 迁出）

### 提醒（store-schedule）

| 用户说 | 命令 |
|--------|------|
| 生日提醒计划 | `reminder plan --json '{"kinds":["birthday"]}'` |
| 注册生日提醒 | `reminder schedule --json '{"kinds":["birthday"]}' --yes` |

### 预约查询备选（store-appointment vs store-schedule）

| 用户说 | 首选 skill | 命令 |
|--------|-----------|------|
| 今天有哪些预约 | store-appointment | `appt-query --date YYYY-MM-DD` |
| 今日预约提醒块 | store-schedule | `reminder-query --type appt_today` |

### 报表 vs 员工（store-reporting vs store-staff）

| 用户说 | skill | 命令 |
|--------|-------|------|
| 员工排名 / 谁业绩最好 / 员工业绩排名 / 经营排名 | store-reporting | `report-staff --month YYYY-MM` |
| 算工资 / 薪资排名 / 内部绩效排名 | store-staff | `staff-ranking --month YYYY-MM` |

### 待办摘要（store-reporting vs store-schedule）

| 用户说 | skill | 命令 |
|--------|-------|------|
| 看下数据（含待办摘要） | store-reporting | `dashboard --md` |
| 完整九块提醒 | store-schedule | `daily-summary --md` |

## 5. auto-seed 与半空库（store-suite）

| 场景 | 行为 |
|------|------|
| 首次空库 | migrate + 完整 seed + `starter_applied` |
| `STORE_SKIP_AUTO_SEED=1` | 只 migrate，不 seed |
| 已有 `starter_applied` | 跳过 auto-seed |
| 部分表被清空但已有 `starter_applied` | **不会** re-seed；手动 `store-suite seed` 或换 `STORE_DB_PATH` |
| 手动 `seed` | INSERT OR IGNORE，不删已有数据；默认含 field defs |

真重置：删除库文件或指向新的 `STORE_DB_PATH`。

## 6. 云端路径与备份（OpenClaw 部署）

业务 SQLite **默认不在 workspace 内**，与 agent 工作区是两套路径：

| 资源 | 默认路径（Linux 容器） | 环境变量 |
|------|------------------------|----------|
| 业务库（10 个 skill 共用） | `~/.config/store-suite/store.sqlite3` | `STORE_DB_PATH` |
| Agent 工作区 | `~/.openclaw/workspace-store/`（见 agent `.config.json`） | — |
| 工作区 cron 配置 | `{workspace}/store_cron.json` | `cron-init --path` |
| 平台 cron 注册表 | `~/.openclaw/cron/jobs.json` | `OPENCLAW_CRON_JOBS_PATH` |

**备份 / 迁移 / restore 须同时包含：**

1. **`~/.config/store-suite/`**（含 `store.sqlite3` 及 WAL 附属文件）— 会员、订单、库存等**全部经营数据**
2. **`{workspace}/`** — `store_cron.json`、上传文件 `media/inbound/`、营销风格档案等
3. **`~/.openclaw/cron/jobs.json`**（若已执行 `cron-setup`）— 每日提醒注册

仅备份 workspace **不会**包含业务库；`restore-state` 等工具默认恢复 workspace，**不包含** `~/.config/store-suite/`，还原后可能出现「工作区文件在、经营数据空」。

**生产环境可选（推荐）：** 将库放到 workspace 内，便于与工作区一并备份：

```bash
export STORE_DB_PATH="$HOME/.openclaw/workspace-store/data/store.sqlite3"
```

首次设置前确认目录存在；已有库迁移时须手动拷贝原 `store.sqlite3`，勿直接改路径导致空库。

**文件导入/导出：** CLI 不自动解析 workspace；Agent 应传**绝对路径**（如 `{workspace}/media/inbound/xxx.csv`），勿依赖相对路径与 CWD。

## 7. 结算内核（store_settlement）

`store-order` 与 `store-appointment` 共用 `store_settlement` 包（随 `store-suite>=1.1.0` 安装）：

| 模块 | 职责 |
|------|------|
| `payment.py` | 支付行解析、校验、`apply_payment_line`（order_id / appt_id） |
| `inventory.py` | `inventory_stock_out` / `inventory_stock_in` |
| `catalog.py` | `query_service_price*`、`query_product_price`、`query_service_materials` |
| `money.py` | `amounts_equal`（分位比较，减轻 float 误差） |
| `errors.py` | `SettlementError`（`store-order` 以 `OrderError` 别名导出） |

业务 skill 仅保留订单行业绩、预约完成编排等薄封装；修支付/库存 bug 应改 suite 一处。

`query_service_materials` 与 `query_service_price*` 一致：服务不存在时抛 `service_not_found`；服务存在但无绑定耗材时返回 `{}`。

## 8. CSV 导出规范

所有 skill 导出 CSV 时必须使用 `store_db.csv_safe`：

| 函数 | 用途 |
|------|------|
| `csv_safe_cell` / `csv_safe_row` / `csv_safe_rows` | 单格/行/多行转义 |
| `write_csv(path, fieldnames, rows)` | 统一 utf-8-sig + DictWriter 写入 |

**规则：** 单元格以 `=`, `+`, `-`, `@`, tab, CR 开头时前缀 `'`，防止 Excel 公式注入。

**已覆盖：** store-customer export、store-marketing segment-export、store-inventory stock-export、store-suite operation-log-export。

## 9. field-def 规范

自定义字段类型白名单由 [field_defs.py](../store_db/field_defs.py) 统一定义：

- **允许：** `text` | `number` | `enum`
- **CLI add/update：** 非法类型 → `invalid_field_type`（member 与 staff 共用 `validate_field_type`）
- **seed / import 自动登记：** 使用 `normalize_field_type` 降级为 `text`
