300 lines
7.9 KiB
Markdown
300 lines
7.9 KiB
Markdown
# 数据导入 API 文档
|
||
|
||
## POST /api/prices/import
|
||
|
||
批量导入钢材价格数据到数据库。
|
||
|
||
### 请求格式
|
||
|
||
**Content-Type:** `application/json`
|
||
|
||
**请求体：**
|
||
|
||
```json
|
||
{
|
||
"prices": [
|
||
{
|
||
"price_id": "2008067775216672769",
|
||
"goods_material": "HPB300",
|
||
"goods_spec": "Φ8",
|
||
"partsname_name": "螺纹钢",
|
||
"productarea_name": "昆钢",
|
||
"price_source": "我的钢铁",
|
||
"price_region": "昆明",
|
||
"pntree_name": "钢筋",
|
||
"price_date": "2026-01-05T10:30:00.000Z",
|
||
"make_price": 3800,
|
||
"hang_price": 3850,
|
||
"last_make_price": 3750,
|
||
"last_hang_price": 3800,
|
||
"make_price_updw": "↑50",
|
||
"hang_price_updw": "↑50",
|
||
"operator_code": "OP001",
|
||
"operator_name": "张三"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 字段说明
|
||
|
||
#### 必填字段
|
||
|
||
| 字段名 | 类型 | 说明 | 示例 |
|
||
|--------|------|------|------|
|
||
| `goods_material` | string | 材质牌号 | `"HPB300"` |
|
||
| `goods_spec` | string | 规格型号 | `"Φ8"` |
|
||
| `partsname_name` | string | 品名 | `"螺纹钢"` |
|
||
| `productarea_name` | string | 产地/钢厂 | `"昆钢"` |
|
||
| `price_source` | string | 价格来源 | `"我的钢铁"` |
|
||
| `price_region` | string | 价格地区 | `"昆明"` |
|
||
| `price_date` | string | 价格日期（ISO 8601） | `"2026-01-05T10:30:00.000Z"` |
|
||
| `hang_price` | number | 挂牌价（元/吨） | `3850` |
|
||
|
||
#### 可选字段
|
||
|
||
| 字段名 | 类型 | 说明 | 默认值 | 示例 |
|
||
|--------|------|------|--------|------|
|
||
| `price_id` | string | 价格唯一ID（为空时自动生成） | `null` | `"2008067775216672769"` |
|
||
| `pntree_name` | string | 分类名称 | `"钢筋"` | `"钢筋"` |
|
||
| `make_price` | number | 钢厂价（元/吨） | `null` | `3800` |
|
||
| `last_make_price` | number | 上次钢厂价 | `null` | `3750` |
|
||
| `last_hang_price` | number | 上次挂牌价 | `null` | `3800` |
|
||
| `make_price_updw` | string | 钢厂价涨跌 | `null` | `"↑50"` |
|
||
| `hang_price_updw` | string | 挂牌价涨跌 | `null` | `"↑50"` |
|
||
| `operator_code` | string | 操作员代码 | `null` | `"OP001"` |
|
||
| `operator_name` | string | 操作员名称 | `null` | `"张三"` |
|
||
|
||
#### 自动生成字段
|
||
|
||
以下字段由系统自动生成，无需传入：
|
||
|
||
- `id` - 自增主键
|
||
- `created_at` - 创建时间
|
||
- `updated_at` - 更新时间
|
||
|
||
### price_id 自动生成规则
|
||
|
||
如果传入的数据中 `price_id` 为空或不存在，系统会基于以下字段生成 MD5 哈希值：
|
||
|
||
```
|
||
{goods_material}-{goods_spec}-{price_region}-{price_source}-{price_date}
|
||
```
|
||
|
||
**示例：**
|
||
```
|
||
HPB300-Φ8-昆明-我的钢铁-2026-01-05T10:30:00.000Z
|
||
↓ MD5 哈希
|
||
a1b2c3d4e5f6...（32 位十六进制字符串）
|
||
```
|
||
|
||
这样可以确保相同业务数据不会重复插入。
|
||
|
||
### 响应格式
|
||
|
||
#### 成功响应
|
||
|
||
**HTTP Status:** `200 OK`
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "成功导入 100 条数据",
|
||
"data": {
|
||
"imported": 100,
|
||
"total": 105,
|
||
"validCount": 100,
|
||
"errorCount": 5,
|
||
"errors": [
|
||
{
|
||
"index": 3,
|
||
"data": { ... },
|
||
"reasons": {
|
||
"missing": ["hang_price"],
|
||
"invalid": [
|
||
{ "field": "price_date", "expected": "valid Date", "received": "invalid-date" }
|
||
]
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 失败响应
|
||
|
||
**HTTP Status:** `200 OK` （业务失败）
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "没有有效的数据可以导入",
|
||
"data": {
|
||
"total": 10,
|
||
"imported": 0,
|
||
"errors": [
|
||
{
|
||
"index": 0,
|
||
"data": { ... },
|
||
"reasons": {
|
||
"missing": ["goods_material", "hang_price"],
|
||
"invalid": []
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 服务器错误
|
||
|
||
**HTTP Status:** `500 Internal Server Error`
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "数据库连接失败"
|
||
}
|
||
```
|
||
|
||
### 数据验证规则
|
||
|
||
#### 必填字段验证
|
||
|
||
- 所有必填字段不能为空、null 或 undefined
|
||
- 字符串字段长度不能为 0
|
||
|
||
#### 数据类型验证
|
||
|
||
| 字段 | 允许的类型 | 验证规则 |
|
||
|------|-----------|----------|
|
||
| `hang_price` | `number` | 必须是有效数字，不能为 NaN |
|
||
| `make_price` | `number` \| `null` | 如果存在，必须是有效数字 |
|
||
| `last_make_price` | `number` \| `null` | 如果存在，必须是有效数字 |
|
||
| `last_hang_price` | `number` \| `null` | 如果存在，必须是有效数字 |
|
||
| `price_date` | `string` \| `Date` | 必须是有效的日期格式 |
|
||
|
||
### 错误处理
|
||
|
||
#### 数据格式错误
|
||
|
||
如果传入的数据不符合格式要求：
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "无效的数据格式",
|
||
"error": "数据必须是数组格式"
|
||
}
|
||
```
|
||
|
||
#### 缺少必填字段
|
||
|
||
如果某条记录缺少必填字段，该记录会被跳过，错误信息会返回在响应中：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "成功导入 95 条数据，5 条数据因格式错误被跳过",
|
||
"data": {
|
||
"imported": 95,
|
||
"total": 100,
|
||
"validCount": 95,
|
||
"errorCount": 5,
|
||
"errors": [
|
||
{
|
||
"index": 10,
|
||
"data": { "goods_material": "HPB300" },
|
||
"reasons": {
|
||
"missing": ["goods_spec", "hang_price", "price_date"],
|
||
"invalid": []
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 使用示例
|
||
|
||
#### JavaScript (Fetch API)
|
||
|
||
```javascript
|
||
const response = await fetch('http://localhost:3000/api/prices/import', {
|
||
method: 'POST',
|
||
headers: {
|
||
'Content-Type': 'application/json'
|
||
},
|
||
body: JSON.stringify({
|
||
prices: [
|
||
{
|
||
goods_material: 'HPB300',
|
||
goods_spec: 'Φ8',
|
||
partsname_name: '螺纹钢',
|
||
productarea_name: '昆钢',
|
||
price_source: '我的钢铁',
|
||
price_region: '昆明',
|
||
price_date: '2026-01-05T10:30:00.000Z',
|
||
hang_price: 3850
|
||
}
|
||
]
|
||
})
|
||
});
|
||
|
||
const result = await response.json();
|
||
console.log(result);
|
||
```
|
||
|
||
#### cURL
|
||
|
||
```bash
|
||
curl -X POST http://localhost:3000/api/prices/import \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"prices": [
|
||
{
|
||
"goods_material": "HPB300",
|
||
"goods_spec": "Φ8",
|
||
"partsname_name": "螺纹钢",
|
||
"productarea_name": "昆钢",
|
||
"price_source": "我的钢铁",
|
||
"price_region": "昆明",
|
||
"price_date": "2026-01-05T10:30:00.000Z",
|
||
"hang_price": 3850
|
||
}
|
||
]
|
||
}'
|
||
```
|
||
|
||
### 注意事项
|
||
|
||
1. **批量限制**：建议单次导入不超过 1000 条记录
|
||
2. **重复数据处理**：使用 `ON DUPLICATE KEY UPDATE` 机制自动更新已存在的记录
|
||
3. **事务处理**：每次批量插入是一个事务，失败会回滚
|
||
4. **错误详情**：响应中最多返回前 10 个错误详情
|
||
5. **price_id 唯一性**：系统会自动确保 price_id 的唯一性，无需手动处理
|
||
|
||
### 完整字段对照表
|
||
|
||
| 数据库字段 | JSON 字段 | 必填 | 类型 | 说明 |
|
||
|-----------|-----------|------|------|------|
|
||
| `price_id` | `price_id` | ❌ | string | 价格唯一ID |
|
||
| `goods_material` | `goods_material` | ✅ | string | 材质牌号 |
|
||
| `goods_spec` | `goods_spec` | ✅ | string | 规格型号 |
|
||
| `partsname_name` | `partsname_name` | ✅ | string | 品名 |
|
||
| `productarea_name` | `productarea_name` | ✅ | string | 产地/钢厂 |
|
||
| `price_source` | `price_source` | ✅ | string | 价格来源 |
|
||
| `price_region` | `price_region` | ✅ | string | 价格地区 |
|
||
| `pntree_name` | `pntree_name` | ❌ | string | 分类名称 |
|
||
| `price_date` | `price_date` | ✅ | string | 价格日期 |
|
||
| `make_price` | `make_price` | ❌ | number | 钢厂价 |
|
||
| `hang_price` | `hang_price` | ✅ | number | 挂牌价 |
|
||
| `last_make_price` | `last_make_price` | ❌ | number | 上次钢厂价 |
|
||
| `last_hang_price` | `last_hang_price` | ❌ | number | 上次挂牌价 |
|
||
| `make_price_updw` | `make_price_updw` | ❌ | string | 钢厂价涨跌 |
|
||
| `hang_price_updw` | `hang_price_updw` | ❌ | string | 挂牌价涨跌 |
|
||
| `operator_code` | `operator_code` | ❌ | string | 操作员代码 |
|
||
| `operator_name` | `operator_name` | ❌ | string | 操作员名称 |
|
||
| `created_at` | - | - | - | 自动生成 |
|
||
| `updated_at` | - | - | - | 自动生成 |
|