---
name: store-suite
description: 门店单库初始化与审计。触发：首次安装建库、seed 样例数据、查询/导出操作日志。
---

# 门店套件内核

提供共享 SQLite 数据库 `store.sqlite3` 的连接、建表、seed 与操作审计。

## 用法

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

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

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

## 输出格式

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

## 主要子命令

| 子命令 | 用途 |
|--------|------|
| db-path | 打印当前库路径 |
| seed | 幂等补充默认 starter 样例（INSERT OR IGNORE，不删已有数据；通常不必手动执行） |
| verify-seed | 校验 seed 后表与样例数据 |
| operation-log-query | 查询操作审计 |
| operation-log-export | 导出审计 CSV |
| store-meta set --key --value | 设置 store_meta 白名单键 |
| migrate | 可选；显式确认 schema（日常由 connect 自动完成） |

## 示例

```bash
uv run {baseDir}/scripts/cli.py db-path
uv run {baseDir}/scripts/cli.py verify-seed
uv run {baseDir}/scripts/cli.py operation-log-query --limit 20
```

## 注意事项

- 数据库在用户配置目录，重装 skill 不删库。
- 仅测试时设置 `STORE_DB_PATH` 指向临时文件。
- `seed` 使用 `INSERT OR IGNORE`，**不会**清空或覆盖已有业务数据；若需真重置，删除库文件或指向新的 `STORE_DB_PATH`。
- **auto-seed 边界**：仅当 `starter_applied` 未标记且 `members==0` 且 `services==0` 时自动 seed。若手动删光会员但 catalog 仍在（或反之），且已有 `starter_applied`，不会再次 auto-seed，库可能处于半空状态；此时可手动 `seed` 补充缺失样例，或换库重建。
- 手动 `seed` 默认写入 `field_defs_seed.json`（与 auto-seed 一致）；若跳过字段定义，加 `--no-field-defs`。
- `store-meta set` 的 key 须在白名单内（segment_preset、balance_low_threshold 等）。
- 表结构见 [references/schema.md](references/schema.md)。
- 错误码见 [references/errors.md](references/errors.md)。
