# 钉钉消息发送API文档

## 概述

本文档描述了采购订单管理系统中钉钉消息发送功能的REST API接口。

## 基础信息

- **基础URL**: `http://localhost:9095`
- **API版本**: v1.0
- **数据格式**: JSON
- **字符编码**: UTF-8

## 接口列表

### 1. 发送钉钉消息

#### 接口信息

- **接口名称**: 发送钉钉消息
- **请求方法**: POST
- **接口路径**: `/api/dingtalk/sendMessage`
- **功能描述**: 根据检验单号发送不合格检验单的钉钉通知消息

#### 请求参数

**请求头**:

```
Content-Type: application/json
```

**请求体**:

```json
{
  "releaseNo": "IQC202501270001"
}
```

**参数说明**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| releaseNo | String | 是 | 检验单号，用于查询对应的钉钉消息内容 |

#### 响应结果

**成功响应** (HTTP 200):

```json
{
  "code": 200,
  "message": null,
  "successful": 0,
  "data": "接收成功"
}
```

**失败响应** (HTTP 200):

```json
{
  "code": 500,
  "message": "错误信息",
  "successful": 1,
  "data": "接收失败"
}
```

**响应字段说明**:
| 字段名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 响应状态码，200表示成功，500表示失败 |
| message | String | 错误信息，成功时为null |
| successful | Integer | 成功标识，0表示成功，1表示失败 |
| data | String | 响应数据，成功时为"接收成功"，失败时为"接收失败" |

#### 错误码说明

| 错误码 | 说明   |
|-----|------|
| 200 | 请求成功 |
| 500 | 请求失败 |

#### 使用示例

**cURL示例**:

```bash
curl -X POST http://localhost:9095/api/dingtalk/sendMessage \
  -H "Content-Type: application/json" \
  -d '{"releaseNo": "IQC202501270001"}'
```

**JavaScript示例**:

```javascript
fetch('http://localhost:9095/api/dingtalk/sendMessage', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    releaseNo: 'IQC202501270001'
  })
})
.then(response => response.json())
.then(data => {
  if (data.code === 200) {
    console.log('消息发送成功');
  } else {
    console.log('消息发送失败:', data.message);
  }
})
.catch(error => {
  console.error('请求失败:', error);
});
```

**Java示例**:

```java
import com.fasterxml.jackson.databind.ObjectMapper;
import okhttp3.*;

public class DingtalkApiClient {
    private static final String BASE_URL = "http://localhost:9095";
    private static final OkHttpClient client = new OkHttpClient();
    private static final ObjectMapper objectMapper = new ObjectMapper();

    public static void sendMessage(String releaseNo) throws Exception {
        // 构建请求体
        String requestBody = objectMapper.writeValueAsString(
                Map.of("releaseNo", releaseNo)
        );

        // 创建请求
        Request request = new Request.Builder()
                .url(BASE_URL + "/api/dingtalk/sendMessage")
                .post(RequestBody.create(
                        MediaType.parse("application/json"),
                        requestBody
                ))
                .build();

        // 发送请求
        try (Response response = client.newCall(request).execute()) {
            String responseBody = response.body().string();
            System.out.println("响应: " + responseBody);
        }
    }
}
```

#### 常见错误及解决方案

1. **检验单号为空**
    - 错误信息: "检验单号不能为空"
    - 解决方案: 确保传入的releaseNo参数不为null且不为空字符串

2. **数据不存在**
    - 错误信息: "钉钉消息发送失败"
    - 解决方案: 确保检验单号在`DINGTALK_MSG`表中有对应的记录

3. **钉钉API调用失败**
    - 错误信息: "钉钉消息发送失败"
    - 解决方案: 检查钉钉应用配置是否正确，确保有发送权限

4. **系统异常**
    - 错误信息: 具体的异常信息
    - 解决方案: 检查系统日志，联系技术支持

#### 注意事项

1. **数据准备**: 确保检验单号在`DINGTALK_MSG`表中有对应的记录
2. **权限配置**: 确保钉钉应用配置正确且有发送工作通知的权限
3. **调用频率**: 建议接口调用频率不超过每分钟1次，避免触发钉钉API限制
4. **用户配置**: 确保接收消息的用户在`DINGTALK_INFO`表中配置正确
5. **网络环境**: 确保服务器能够正常访问钉钉开放API

#### 消息格式

发送的钉钉消息格式如下：

```
供应商[xxx] 来料日期[yyyy-MM-dd] 项目[xxx] 料号[xxx]的不合格检验单被[xxx]审批为[xxx]，请查收!
```

#### 数据库依赖

该接口依赖以下数据库表：

- `DINGTALK_MSG`: 存储钉钉消息内容
- `DINGTALK_INFO`: 存储钉钉用户信息

#### 版本历史

| 版本   | 日期         | 更新内容               |
|------|------------|--------------------|
| v1.0 | 2025-01-27 | 初始版本，支持基本的钉钉消息发送功能 |

## 联系支持

如有问题或建议，请联系技术支持团队。