my-mom-system/.openclaw/workspace-data-analyst/TOOLS.md

# 工具使用规范

## MOM 系统 API

### 后端基础信息
- **Base URL**: `${MOM_API_BASE_URL}`（默认 http://localhost:8080）
- **认证**: JWT Token，通过 Authorization: Bearer 头传递

### 数据分析可访问的全部 API（只读）

#### 生产模块
| 功能 | 端点 | 方法 |
|------|------|------|
| 生产计划列表 | `/erp/productionPlan/list` | GET |
| 工单列表 | `/erp/workOrder/list` | GET |
| 报工反馈 | `/mes/pro/feedback/list` | GET |
| 工序任务 | `/mes/pro/task/list` | GET |
| 生产零件 | `/erp/parts/list` | GET |
| MBOM清单 | `/erp/mbom/list` | GET |

#### 销售模块
| 功能 | 端点 | 方法 |
|------|------|------|
| 销售订单 | `/erp/salesOrder/list` | GET |
| 合同列表 | `/erp/contract/list` | GET |
| 出货单 | `/erp/deliver/list` | GET |
| 销售发票 | `/erp/invoice/list` | GET |

#### 采购模块
| 功能 | 端点 | 方法 |
|------|------|------|
| 采购订单 | `/erp/purchaseOrder/list` | GET |
| 到货单 | `/erp/checkin/list` | GET |
| 退货单 | `/erp/reject/list` | GET |
| 采购计划 | `/erp/purchasePlan/list` | GET |

#### 质量模块
| 功能 | 端点 | 方法 |
|------|------|------|
| IQC检验 | `/mes/qc/iqc/list` | GET |
| IPQC检验 | `/mes/qc/ipqc/list` | GET |
| OQC检验 | `/mes/qc/oqc/list` | GET |
| 检验结果 | `/mes/qc/result/list` | GET |

#### 仓储模块
| 功能 | 端点 | 方法 |
|------|------|------|
| 库存查询 | `/mes/wm/materialstock/list` | GET |
| 出入库事务 | `/mes/wm/transaction/list` | GET |
| 领料单 | `/erp/warehouse/issue/list` | GET |

#### 设备模块
| 功能 | 端点 | 方法 |
|------|------|------|
| 设备列表 | `/mes/dv/machinery/list` | GET |
| 维修记录 | `/mes/dv/repair/list` | GET |
| 点检计划 | `/mes/dv/checkplan/list` | GET |

#### 主数据
| 功能 | 端点 | 方法 |
|------|------|------|
| 物料主数据 | `/erp/masterdata/item/list` | GET |
| BOM结构 | `/erp/masterdata/bom/list` | GET |
| 车间列表 | `/erp/masterdata/workshop/list` | GET |
| 工位列表 | `/erp/masterdata/workstation/list` | GET |

## 数据库查询（只读）

数据分析Agent有更广泛的SQL查询权限，但严格只读：

### 连接信息
- Host: `${MOM_DB_HOST}` / Port: `${MOM_DB_PORT}`
- Database: `${MOM_DB_NAME}`
- User: `${MOM_DB_USER}`（只读账号）

### 常用分析查询模板

#### 日产量统计
```sql
SELECT DATE(create_time) AS prod_date,
       COUNT(*) AS total_orders,
       SUM(quantity_produced) AS total_produced,
       SUM(quantity_qualified) AS total_qualified,
       ROUND(SUM(quantity_qualified)/SUM(quantity_produced)*100, 2) AS yield_rate
FROM pro_feedback
WHERE create_time >= CURDATE() - INTERVAL 7 DAY
GROUP BY DATE(create_time)
ORDER BY prod_date;
```

#### 设备OEE数据
```sql
SELECT m.machinery_code, m.machinery_name,
       COUNT(DISTINCT DATE(f.create_time)) AS work_days,
       SUM(f.quantity_produced) AS total_output,
       SUM(f.quantity_qualified) AS good_output
FROM dv_machinery m
LEFT JOIN pro_task t ON t.machinery_id = m.machinery_id
LEFT JOIN pro_feedback f ON f.task_id = t.task_id
WHERE f.create_time >= CURDATE() - INTERVAL 30 DAY
GROUP BY m.machinery_id
ORDER BY total_output DESC;
```

#### 库存周转分析
```sql
SELECT i.item_code, i.item_name,
       s.quantity_onhand,
       COALESCE(consumed.qty, 0) AS monthly_consumption,
       CASE WHEN COALESCE(consumed.qty, 0) > 0
            THEN ROUND(s.quantity_onhand / (consumed.qty / 30), 1)
            ELSE 999 END AS days_of_supply
FROM erp_md_item i
JOIN erp_wm_stock s ON s.item_id = i.item_id
LEFT JOIN (
    SELECT item_id, SUM(quantity) AS qty
    FROM wm_transaction
    WHERE transaction_type = 'OUT'
      AND create_time >= CURDATE() - INTERVAL 30 DAY
    GROUP BY item_id
) consumed ON consumed.item_id = i.item_id
ORDER BY days_of_supply DESC
LIMIT 50;
```

## 工具使用原则

1. **严格只读**: 所有数据库操作仅限 SELECT，禁止任何写操作
2. **性能意识**: 复杂查询必须带 LIMIT，大表关联走索引
3. **数据校验**: 分析结果与多个数据源交叉验证
4. **时间范围**: 默认查询最近 30 天数据，长周期分析明确时间窗口
5. **数据脱敏**: 涉及价格、成本等敏感数据时确认用户权限