---
title: 进销存数据分析接口（inv-analytics）
type: 项目文档
project: 进销存系统
category: 技术接入
version: 1.0
date: 2026-08-26
tags: [进销存, 数据分析, Agent, CLI, 数据闭环]
status: 已发布
---

# 进销存数据分析接口（inv-analytics）

> 让驾驶舱 / 运营 Agent 读取进销存**真实经营数据**的命令行工具。
> 只读本地 SQLite（`%APPDATA%\fishing-inventory\data.db`），绝不写数据。

## 一、命令全集

| 命令 | 输出 | 用途 |
|------|------|------|
| `overview` | 今天/本月/累计销售、库存总值、商品数 | 经营总览 |
| `sales --days N` | 近 N 天销售趋势（日期/销售额/毛利） | 销售趋势 |
| `stock` | 低库存 / 临期 / 滞销清单 | 库存健康 |
| `first-sale` | 首单状态（hasFirstSale/时间/单数） | **首单任务完成依据** |
| `customers` | 客户欠款排行 | 应收管理 |
| `dormant` | 沉睡资金榜（90/180天无出库×占用资金，倒序） | **滞销清仓决策** |
| `top --n N` | 畅销品 Top N | 爆品分析 |
| `raw --sql "SELECT..."` | 任意只读 SQL 查询 | Agent 自由分析 |

## 二、用法示例

```bash
cd "C:\Users\你的用户名\Desktop\库存管理\AI智能管理进销存系统"

# 经营总览（JSON）
node scripts/inv-analytics.mjs overview

# 首单状态（任务完成判定）
node scripts/inv-analytics.mjs first-sale

# 近 7 天销售
node scripts/inv-analytics.mjs sales --days 7

# 低库存/临期/滞销
node scripts/inv-analytics.mjs stock

# 客户欠款
node scripts/inv-analytics.mjs customers

# 畅销 Top 10
node scripts/inv-analytics.mjs top --n 10

# 原始查询（只读 SELECT）
node scripts/inv-analytics.mjs raw --sql "SELECT category, COUNT(*) FROM products GROUP BY category"

# 人类可读输出
node scripts/inv-analytics.mjs stock --pretty
```

## 三、数据口径（与进销存命令层一致）

| 指标 | 口径 |
|------|------|
| 销售额 | transactions 表 type='out' 的 quantity × selling_price |
| 毛利 | type='out' 的 quantity × (selling_price − unit_price) |
| 库存总值 | inventory_batches 的 quantity × cost_price（批次进价） |
| 首单 | 是否存在 type='out' 的销售记录（first-sale） |
| 低库存 | 库存 < min_stock（未设置按 5） |
| 临期 | 批次 expiry_date ≤ 30 天内 |
| 滞销 | 有库存但 90 天无出库 |

## 四、安全约束

- **只读**：数据库以 readOnly 模式打开；raw 命令拒绝非 SELECT
- 金额单位：内部为分，输出已转元（2 位小数）
- 不修改任何数据，可与桌面端并发运行

## 五、Agent 接入

运营 Agent / 驾驶舱可通过系统命令调用本工具获取真实数据：

1. 判断首单任务：`inv-analytics first-sale` → hasFirstSale
2. 经营周报：`inv-analytics overview` + `sales --days 7`
3. 补货建议：`inv-analytics stock` → lowStock
4. 应收管理：`inv-analytics customers`
5. 深度分析：`raw --sql "..."`（只读）

## 六、驾驶舱实时联动（inv-cockpit-sync）

同步器把进销存实时数据自动写入驾驶舱数据源，实现闭环：

```bash
# 手动同步一次
node scripts/inv-cockpit-sync.mjs

# 已注册 Windows 计划任务「inventory-cockpit-sync」：每小时自动同步
```

**同步内容**：
1. `（内部目录）` —— 驾驶舱库存数据源（经营总览/库存健康/客户欠款）
2. `（内部目录）` —— 首单状态自动判定（数据库存在 type=out 销售记录 → ✅ 完成）

**数据链路**：进销存数据库 → inv-analytics → inv-cockpit-sync（每小时）→ 驾驶舱数据源 + 业务真实进度 → 驾驶舱首单/库存卡片

**驾驶舱实时卡片**（plugin-host.js 已加，需重启 DSH 生效）：
- 「线下库存」：库存总件数 + 成本金额（如 7609件 · 58401.00元）
- 「今日销售」：今日销售额（0 时显示 0）
- 「首单」：数据库实时判定（已有）

**首单任务完成依据**：进销存数据库 transactions 表存在 type=out 记录（实测：插入销售 → 首单自动✅；清理 → 恢复❌）