# API 接口文档

> **版本**：v2.0  
> **日期**：2026-05-08  
> **适用范围**：云端 REST API 服务（PHP + MySQL）

---

## 一、接口列表

### 1.1 现有 API（api/ 目录）

| 接口 | 路径 | 说明 |
|------|------|------|
| 配方管理 | `/api/recipe.php` | 配方的增删改查 |
| 计划管理 | `/api/plan.php` | 生产计划管理 |

### 1.2 小程序展会版专用 API（api/exhibition/ 目录）

| 接口 | 路径 | 方法 | 说明 | 状态 |
|------|------|------|------|------|
| 配方列表 | `/api/exhibition/recipe.php?action=list` | GET | 获取配方列表（用于发送配方下拉选择） | 已完成 |
| 发送配方 | `/api/exhibition/recipe.php?action=send` | POST | 发送配方到设备（写 M_TRANSFER，由一体机执行） | 已完成 |
| 发送记录 | `/api/exhibition/send-record.php` | GET | 获取配方发送历史记录 | 已完成 |
| 生产报表 | `/api/exhibition/report.php` | GET | 获取生产报表数据 | 已完成 |
| 监控数据 | `/api/exhibition/monitor.php` | GET | 获取实时监控数据（读 M_MONITOR_REALTIME） | 已完成 |
| 历史曲线 | `/api/exhibition/chart.php?action=history` | GET/POST | 按时间范围获取历史曲线数据 | 已完成 |
| 实时曲线 | `/api/exhibition/chart.php?action=realtime` | GET | 获取最新实时数据点 | 已完成 |
| Canvas曲线 | `/api/exhibition/curve.php` | GET | 获取曲线数据（Canvas渲染用） | 已完成 |

---

## 二、通用规范

### 2.1 请求格式

- Content-Type: `application/json`
- 字符编码: UTF-8

### 2.2 响应格式

```json
{
  "code": 0,
  "message": "操作成功",
  "data": {}
}
```

### 2.3 状态码

| Code | 说明 |
|------|------|
| 0 | 成功 |
| 400 | 请求参数错误 |
| 404 | 资源不存在 |
| 405 | 请求方法不支持 |
| 409 | 资源冲突（如名称重复） |
| 500 | 服务器内部错误 |

---

## 三、详细接口

### 3.1 配方相关

#### 3.1.1 获取配方列表

| 属性 | 值 |
|------|-----|
| 路径 | `/api/exhibition/recipe.php?action=list` |
| 方法 | GET |
| 说明 | 返回 M_RECIPE 全部配方，用于下拉选择 |

**响应示例**：
```json
{
  "code": 0,
  "message": "操作成功",
  "data": [
    { "id": 1, "name": "配方A", "weight1": 4.5, "tolerance1": 1.0, ... }
  ]
}
```

#### 3.1.2 发送配方

| 属性 | 值 |
|------|-----|
| 路径 | `/api/exhibition/recipe.php?action=send` |
| 方法 | POST |
| 说明 | 接收配方参数，写入 M_PLAN 和 M_TRANSFER |

**请求体**：
```json
{
  "recipeName": "444",
  "batch": 10,
  "weight1": 4.4,
  "tolerance1": 1.0,
  "weight2": 3.3,
  "tolerance2": 2.0,
  "weight3": 5.5,
  "tolerance3": 3.1
}
```

**后端逻辑**：
1. 校验配方参数合法性
2. 生成 `LOT_ID`（格式：YYYYMMDDHHMMSS + 4位随机数）
3. 插入 `M_PLAN`（STATE=1，计划状态跟踪）
4. 插入 `M_TRANSFER`（LOCAL_FLAG=1，待一体机读取执行）
5. 返回 `{ code: 0, message: "已下发", data: { lotId: "..." } }`

**响应示例**：
```json
{
  "code": 0,
  "message": "已下发",
  "data": {
    "lotId": "202604281441072707"
  }
}
```

---

### 3.2 发送记录

| 属性 | 值 |
|------|-----|
| 路径 | `/api/exhibition/send-record.php` |
| 方法 | GET |
| 说明 | 查询 R_TRANSFER |

**查询参数**：
- `page` / `pageSize`：分页
- `startDate` / `endDate`：时间范围（格式 YmdHis）

---

### 3.3 生产报表

| 属性 | 值 |
|------|-----|
| 路径 | `/api/exhibition/report.php` |
| 方法 | GET |
| 说明 | 查询 R_TRANSFER / M_PRODUCTION |

**查询参数**：
- `period`：`today` / `week` / `month`
- `startDate` / `endDate`

---

### 3.4 监控实时数据

#### 3.4.1 获取监控数据

| 属性 | 值 |
|------|-----|
| 路径 | `/api/exhibition/monitor.php` |
| 方法 | GET |
| 说明 | 查询 M_MONITOR_REALTIME 单条记录 |

**响应示例**：
```json
{
  "code": 0,
  "data": {
    "lotId": "202604281441072707",
    "recipeName": "444",
    "batchSet": 13,
    "batch1Finish": 5,
    "batch2Finish": 5,
    "batch3Finish": 3,
    "weight1Act": 3.412,
    "weight2Act": 2.856,
    "weight3Act": 4.102,
    "status": 1,
    "alarmCode": null,
    "updateTime": "20260429130815"
  }
}
```

#### 3.4.2 获取最近称重

| 属性 | 值 |
|------|-----|
| 路径 | `/api/exhibition/monitor.php?action=recentWeigh` |
| 方法 | GET |
| 说明 | 查询 R_WEIGH 最近 N 条 |

---

### 3.5 曲线数据

#### 3.5.1 历史曲线

| 属性 | 值 |
|------|-----|
| 路径 | `/api/exhibition/chart.php?action=history` |
| 方法 | GET/POST |
| 说明 | 按时间范围查询 R_CURVE |

**参数**：
- `lotId`：计划号（可选）
- `sysNo`：系统号 1/2/3（可选）
- `startTime` / `endTime`：起止时间（YmdHis）
- `limit`：最大返回条数，默认 2000

#### 3.5.2 实时数据点

| 属性 | 值 |
|------|-----|
| 路径 | `/api/exhibition/chart.php?action=realtime` |
| 方法 | GET |
| 说明 | 返回最近 N 条 R_CURVE 记录 |

**参数**：
- `lastId`：上次查询的最大 ID，用于增量拉取
- `limit`：默认 100

#### 3.5.3 Canvas 曲线

| 属性 | 值 |
|------|-----|
| 路径 | `/api/exhibition/curve.php` |
| 方法 | GET |
| 说明 | 获取曲线数据（供 Canvas 渲染使用） |

---

### 3.6 配方管理 API（现有）

| 属性 | 值 |
|------|-----|
| 路径 | `/api/recipe.php` |
| 方法 | GET/POST/PUT/DELETE |
| 说明 | 配方的增删改查 |

> 详见 [配方管理模块文档](modules/recipe/README.md#四接口文档)

### 3.7 计划管理 API（现有）

| 属性 | 值 |
|------|-----|
| 路径 | `/api/plan.php` |
| 方法 | GET/POST/PUT/DELETE |
| 说明 | 生产计划的增删改查 |

---

## 四、通信协议

### 4.1 连接参数

| 连接类型 | 协议 | 地址 | 说明 |
|----------|------|------|------|
| 现场→云端MySQL | TCP | `cloud.com:3306` | 数据库操作 |
| 微信端→云端API | HTTPS | `https://cloud.com/api/exhibition/...` | REST API调用 |
| 现场→Kepware | OPC | `localhost:49320` | PLC通信 |
| 本地Web服务 | HTTP | `http://localhost:8080` | 操作界面 |

### 4.2 微信端跳转

子页面通过微信 JSSDK 打开新 WebView：

```javascript
wx.miniProgram.navigateTo({
  url: '/pages/webview/webview?url=' + encodeURIComponent('https://test.mini-tiger.com/mobile/exhibition/send-record/index.html')
});
```

---

## 五、H5 页面路径

| 页面 | 路径 | 说明 |
|------|------|------|
| 监控主页 | `/mobile/exhibition/monitor/index.html` | 带底部导航，可发送配方 |
| 发送记录 | `/mobile/exhibition/send-record/index.html` | 配方发送历史 |
| 生产报表 | `/mobile/exhibition/report/index.html` | 生产数据统计 |
| 生产曲线 | `/mobile/exhibition/chart/index.html` | ECharts 历史/实时曲线 |
| Canvas曲线 | `/mobile/exhibition/curve/index.html` | Canvas 实时曲线 |
| 关于我们 | `/mobile/exhibition/about/index.html` | 系统信息、公司简介、联系方式 |