steel_prices_service/scripts/README-IMPORT.md

数据导入脚本使用说明

概述

scripts/import-data.js 已升级，现在支持两种数据导入模式：

1. 本地文件模式 (local): 从 data/ 目录的 JSON 文件导入
2. API 接口模式 (api): 从 commonApi.js 定义的接口实时获取数据

接口映射关系

接口端点	数据来源	对应文件	数据来源标识
DEFAULT	云南钢协	刚协指导价.json	云南钢协
BACKUP	我的钢铁	钢材网架.json	我的钢铁
EXTENDED	德钢指导价	钢厂指导价.json	德钢指导价

使用方法

1. 本地文件导入（默认模式）

# 方式 1: 显式指定模式
node scripts/import-data.js local

# 方式 2: 使用默认模式（省略参数）
npm run db:import
# 或
node scripts/import-data.js

功能说明：

• 从 data/ 目录读取所有 JSON 文件
• 依次导入：刚协指导价.json、钢材网架.json、钢厂指导价.json
• 跳过不存在的文件

2. API 接口导入

2.1 从所有 API 接口导入

# 使用默认参数（今天到一年后，每页 10 万条）
node scripts/import-data.js api

# 指定日期范围
node scripts/import-data.js api --startDate 2025-01-01 --endDate 2025-12-31

# 指定每页数量
node scripts/import-data.js api --pageSize 50000

# 组合参数
node scripts/import-data.js api --startDate 2025-01-01 --endDate 2025-12-31 --pageSize 100000

执行流程：

1. 依次调用 DEFAULT、BACKUP、EXTENDED 三个接口
2. 自动获取 Token
3. 批量导入数据（每批 1000 条）
4. 显示导入进度和统计信息

2.2 从单个 API 接口导入

# 仅导入云南钢协数据（DEFAULT 接口）
node scripts/import-data.js single-api DEFAULT

# 仅导入我的钢铁数据（BACKUP 接口）
node scripts/import-data.js single-api BACKUP

# 仅导入德钢指导价数据（EXTENDED 接口）
node scripts/import-data.js single-api EXTENDED

# 带参数的单接口导入
node scripts/import-data.js single-api DEFAULT --startDate 2025-01-01 --endDate 2025-12-31

命令行参数

参数	说明	示例	默认值
--startDate	查询开始日期（YYYY-MM-DD）	--startDate 2025-01-01	今天
--endDate	查询结束日期（YYYY-MM-DD）	--endDate 2026-01-01	一年后
--pageSize	每页数据条数	--pageSize 100000	100000

输出示例

本地文件导入

🚀 开始从本地文件导入钢材价格数据...

📄 正在读取本地文件: 刚协指导价.json
✅ 解析到 900 条有效数据
  进度: 900/900 条
✅ 成功导入 900 条数据

📄 正在读取本地文件: 钢材网架.json
✅ 解析到 211 条有效数据
  进度: 211/211 条
✅ 成功导入 211 条数据

📄 正在读取本地文件: 钢厂指导价.json
✅ 解析到 29987 条有效数据
  进度: 1000/29987 条
  进度: 2000/29987 条
  ...
  进度: 29987/29987 条
✅ 成功导入 29987 条数据

==================================================
🎉 本地文件导入完成！总计导入 31098 条数据
==================================================

📊 数据库统计信息:
  总记录数: 31098
  平均价格: 4500.25 元/吨
  最低价格: 3200 元/吨
  最高价格: 5800 元/吨

✅ 脚本执行完成

API 接口导入

🚀 开始从 API 接口导入钢材价格数据...

🌐 正在从 API 接口获取数据: DEFAULT (云南钢协)
   查询参数: {
  "startDate": "2025-01-06",
  "endDate": "2026-01-06",
  "page": 1,
  "pageSize": 100000
}
🔐 正在获取 Token...
✅ Token 获取成功: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
🔄 切换到接口: 默认钢材价格查询
   Page ID: PG-D615-D8E2-2FD84B8D
   Menu ID: MK-A8B8-109E-13D34116
✅ 解析到 1250 条有效数据
  进度: 1000/1250 条
  进度: 1250/1250 条
✅ 成功导入 1250 条数据

🌐 正在从 API 接口获取数据: BACKUP (我的钢铁)
...

🌐 正在从 API 接口获取数据: EXTENDED (德钢指导价)
...

==================================================
🎉 API 接口导入完成！总计导入 15234 条数据
==================================================

📊 数据库统计信息:
  总记录数: 46332
  平均价格: 4450.80 元/吨
  最低价格: 3100 元/吨
  最高价格: 5900 元/吨

✅ 脚本执行完成

编程式调用

除了命令行调用，也可以在代码中直接使用：

const { importFromAPI, importAllFromAPI, importAllLocalFiles } = require('./scripts/import-data');

// 方式 1: 从单个 API 接口导入
await importFromAPI('DEFAULT', {
  startDate: '2025-01-01',
  endDate: '2025-12-31',
  pageSize: 100000
});

// 方式 2: 从所有 API 接口导入
await importAllFromAPI({
  startDate: '2025-01-01',
  endDate: '2025-12-31'
});

// 方式 3: 从本地文件导入
await importAllLocalFiles();

错误处理

脚本包含完善的错误处理机制：

1. 文件不存在: 自动跳过，继续处理其他文件
2. API 请求失败: 显示错误信息，继续处理下一个接口
3. 数据解析失败: 显示详细错误，不会中断整个流程
4. 数据库插入失败: 记录错误日志，支持批量插入失败重试

注意事项

1. 环境变量: 确保 .env 文件配置正确，包含数据库连接信息
2. Token 管理: API 模式会自动从 loginApi.js 获取 Token，确保登录凭证有效
3. 网络连接: API 模式需要稳定的网络连接
4. 数据库性能: 批量插入每批 1000 条，大数据量导入可能需要较长时间
5. 重复数据: 使用 ON DUPLICATE KEY UPDATE 策略，避免重复导入

故障排查

问题 1: Token 获取失败

❌ Token 获取失败: Invalid credentials

解决方案：

• 检查 .env 中的登录凭证
• 确认 loginApi.js 中的 Token 存储路径正确
• 手动运行 node commonApi.js 测试登录

问题 2: 数据库连接失败

❌ 价格表创建失败: Access denied for user 'root'@'localhost'

解决方案：

• 检查 .env 中的数据库配置
• 确认 MySQL 服务已启动
• 验证用户权限

问题 3: API 返回空数据

⚠️  没有有效数据可导入

解决方案：

• 检查日期范围是否合理
• 确认 API 接口地址正确
• 尝试增加 pageSize 参数

最佳实践

1. 定期导入: 使用 node-cron 或系统定时任务定期执行 API 导入
2. 增量更新: 使用日期参数仅导入最新数据
3. 数据备份: 导入前备份现有数据
4. 监控日志: 保存导入日志用于审计和问题排查

示例：定时任务

使用 node-cron 设置每天凌晨 2 点自动导入：

// scripts/schedule-import.js
const cron = require('node-cron');
const { exec } = require('child_process');

cron.schedule('0 2 * * *', () => {
  console.log('🕰️ 开始定时导入任务...');

  exec('node scripts/import-data.js api --startDate 2025-01-01 --pageSize 100000',
    (error, stdout, stderr) => {
      if (error) {
        console.error(`执行出错: ${error}`);
        return;
      }
      console.log(stdout);
    }
  );
});

console.log('✅ 定时任务已启动：每天 02:00 执行数据导入');

运行定时任务：

node scripts/schedule-import.js

技术细节

数据转换

• 原始数据格式: rawData.data.page.result[]
• 过滤条件: price_date 存在且 hang_price > 0
• 字段映射: 自动映射 API 字段到数据库字段

批量插入策略

• 批次大小: 1000 条/批
• 重复处理: 使用 ON DUPLICATE KEY UPDATE
• 事务支持: 每批独立事务

性能优化

• 批量插入优于单条插入
• 数据库索引优化 (idx_price_date, idx_region_material)
• 自动过滤无效数据，减少不必要的数据库操作

---

更新日志

2026-01-06

• ✅ 新增 API 接口导入功能
• ✅ 支持命令行参数配置
• ✅ 改进错误处理和进度显示
• ✅ 保持向后兼容性