# 计算看板、搜索 API 与 MCP 交付记录

时间：2026-06-12
执行 profile：IT
云端服务：`goods-ledger-api` / `127.0.0.1:8791`
云端路径：`/srv/goods-ledger/backend`

## 本次新增后端能力

### 看板 API

新增只读接口：

```text
GET /api/dashboard/overview
GET /api/dashboard/inventory
GET /api/dashboard/orders
GET /api/dashboard/channels
GET /api/dashboard/shipments
GET /api/dashboard/reconciliation
```

覆盖板块：

- 总览：核心计数、开放问题、最近来源文件、最近校验问题；
- 库存：当前库存、出入库方向/类型汇总、最近库存流水；
- 订单：上下游/订单类型/状态分组、订单明细汇总、渠道分配差异；
- 渠道：按渠道汇总计划/确认/发货/签收数量、分配差异；
- 发货签收：签收单状态、发货/签收/拒收数量、异常签收明细；
- 对账补货：实时供应商采购 vs 上游需求差异、最新快照、开放问题。

### 统一搜索 API

新增：

```text
GET /api/search?q=<关键词>&scope=all&limit=10
```

返回分组：

```text
products
orders
files
stock_movements
shipments
issues
```

当前搜索字段包括商品名、SKU、69码、国博编码、规格、订单号、合同号、买卖方、物流单号、文件名、来源平台、收货/签收人、校验问题等。

### 对账快照 API

新增：

```text
POST /api/reconciliation/run
```

作用：从 `v_supplier_vs_upstream_reconciliation_live` 生成一次可审计快照，写入：

```text
reconciliation_runs
reconciliation_lines
api_write_requests
agent_write_audit
```

接口需要 `X-Ledger-API-Key`，支持 `Idempotency-Key`。

## 本次新增 MCP 工具

已部署到云端 `/srv/goods-ledger/backend/app/mcp_server.py` 并加入 `goods-ledger-manager` profile 的 MCP allowlist：

```text
ledger_dashboard_overview
ledger_search
ledger_reconciliation_dashboard
ledger_run_reconciliation
```

同时保留原有工具：

```text
ledger_health
ledger_summary
ledger_current_stock
ledger_recent_stock_movements
ledger_open_validation_issues
ledger_create_party
ledger_create_product
ledger_register_source_file
ledger_create_purchase_order
ledger_add_stock_movement
ledger_create_shipment_signoff
ledger_create_validation_issue
```

## 验证记录

云端代码编译：通过。

PM2 服务：`goods-ledger-api` online。

接口烟测：

```text
/health => ok=True, database=goods_ledger
/api/dashboard/overview => keys: counts/extras/recent_files/recent_issues, open_issue_count=15
/api/dashboard/inventory?limit=3 => item_count=13, rows=3
/api/dashboard/orders?limit=3 => by_side=2, recent_orders=3
/api/dashboard/channels?limit=3 => by_channel=5, recent_allocations=3
/api/dashboard/shipments?limit=3 => by_status=1, recent_shipments=1
/api/dashboard/reconciliation?limit=3 => product_count=19, live_rows=3
/api/search?q=国博&limit=2 => groups: files/issues/orders/products/shipments/stock_movements
```

对账快照烟测：

```text
POST /api/reconciliation/run
idempotency_key: smoke-reconciliation-20260612-dashboard-api
line_count: 19
audit rows: 1
audited_lines: 19
```

MCP 验证：

```text
hermes -p goods-ledger-manager mcp test goods_ledger_write
Connected
Tools discovered: 16

hermes -p goods-ledger-manager chat -q '请只调用 goods_ledger_write 的 ledger_dashboard_overview 工具...'
extras.open_issue_count: 15
extras.api_write_request_count: 2
```

## 维护动作

- 已同步更新 `goods-ledger-manager` Skill 工具清单；
- 已同步更新 `goods-ledger-manager/config.yaml` MCP tool include；
- 已重新锁定执行 profile 的 `config.yaml` 与 Skill 文件为只读/immutable。

## 后续建议

下一步可以基于这些 API 做只读前端看板。优先顺序建议：

1. 总览 + 搜索；
2. 库存/进出库；
3. 订单/合同；
4. 渠道分配；
5. 发货签收；
6. 对账补货/问题中心。