# stock-mcp-server

库存查询 MCP 后端服务，定位为 `paxaq/baojia_src` 的延伸项目。

本项目把吉客云库存、苏泊尔工厂库存、微信群供应商 Excel、供应商人工/RPA 询问统一到一套 REST API 与 MCP 工具中。上游 AI 或业务系统只需要调用统一库存入口，不直接理解每个数据源的差异。

当前主线版本：**v0.6.0**

## 文档入口

| 文档 | 说明 |
|------|------|
| [docs/development.md](docs/development.md) | 开发文档：架构、模块边界、baojia_src 依赖、环境变量、开发流程 |
| [docs/progress.md](docs/progress.md) | 当前进度：已完成、进行中、待接入、风险点 |
| [docs/integration-checklist.md](docs/integration-checklist.md) | 与 baojia_src 联调清单：环境、表结构、风险点、业务确认项 |
| [docs/api.md](docs/api.md) | REST API 与 MCP 工具契约 |
| [CHANGELOG.md](CHANGELOG.md) | 版本变更记录 |

## 快速开始

```bash
# 1. 准备环境变量
cp .env.example .env

# 2. 准备 PostgreSQL / Redis
# 推荐复用 baojia_src 的实例，但使用独立 PG_SCHEMA 与 Redis DB。

# 3. 安装依赖
pnpm install

# 4. 执行数据库迁移
pnpm db:migrate

# 5. 启动 API + SSE MCP
pnpm start:dev

# 6. 单独启动 stdio MCP（Claude Desktop 等本地客户端）
pnpm mcp:stdio
```

默认服务地址：

- REST API：`http://localhost:7300/api/v1`
- Swagger：`http://localhost:7300/api/docs`
- MCP SSE：由 `MCP_SSE_PATH` 控制，默认 `/mcp/sse`

## 容器部署

```bash
podman build -t stock-mcp:latest .
podman run -d --name stock-mcp --env-file stock-mcp.env -p 7300:7300 stock-mcp:latest
```

当前生产容器启用健康检查、供应商库存文件监听、每天 9:30 供应商群提醒、DeepSeek 表头映射兜底、库存查询 REST API 和 MCP 查询工具。管理端、RPA 问供应商闭环、苏泊尔/吉客云实时库存仍未进入生产主链路。

## 核心能力

| 能力 | 状态 | 说明 |
|------|------|------|
| 吉客云库存查询 | 未进生产 | 代码存在，但当前生产查询先只查供应商库存表 |
| 苏泊尔工厂库存 | 暂停 | 昨日开发失败后暂停；当前代码只能视为草稿/实验实现，不能按可用能力计算 |
| 微信群供应商 Excel | 生产可用 | 已按 `group_role=2` 供应商群监听文件、解析入库，并写入 `stock_mcp.public.supplier_inventory` |
| DeepSeek 表头兜底 | 生产可用 | 确定性解析为空时调用 DeepSeek，采用后沉淀到 `supplier_excel_template` |
| 文件处理日志 | 生产可用 | `supplier_inventory_file_process_log` 记录每个 `msgid` 的处理状态、失败原因、AI 建议和入库行数 |
| 按 SKU/品牌查询 | 已恢复 | REST/MCP 当前查询 `stock_mcp.public.supplier_inventory` |
| MCP 工具 | 已恢复查询工具 | `inventory.query`、`inventory.list_suppliers`、`inventory.query_by_brand` |
| 管理端 | 未进生产 | Vue3/NestJS 草稿存在，但未装载到当前生产容器 |
| 人工/RPA 询问供应商 | 待做 | ask/status 工具暂未启用，后续再打通完整闭环 |

## 重要设计约束

- 库存是结构化精确匹配，不引入向量检索。
- API 与 MCP 必须同源，统一走库存服务，避免同一问题在不同入口语义不一致。
- 所有客户可见库存回复必须带 `asOf` 或 `customerReply` 中的“数据截至”信息。
- 供应商库存按供应商/仓库展示，不跨供应商简单求和。
- 陈旧库存默认阈值 30 分钟，超阈值标记 `stale=true`。
- 与 `baojia_src` 共用基础设施时，要用独立 schema、Redis DB 和 key prefix 隔离。

## 测试

```bash
pnpm test
pnpm test:cov
```

## 只读联调诊断

验证 `baojia_src` 供应商群 Excel 文件链路时，先运行只读诊断脚本：

```bash
pnpm diagnose:wechat-files
```

该脚本只查询 `baojia_src` 的微信消息和媒体文件，检查文件路径可读性并 dry-run 解析 Excel，不写任何业务表。

当前测试主要覆盖：

- 吉客云签名
- 苏泊尔适配器 mock 模式，不能代表真实苏泊尔库存链路已打通
- 微信 Excel 解析基础逻辑，不能代表真实微信群文件环境已验收
- 库存聚合基础逻辑