steel_prices_service/docs/QUICK_START.md

快速开始指南

🚀 快速启动

1. 配置环境变量

复制 .env.example 到 .env 并配置数据库连接：

cp .env.example .env

编辑 .env 文件，填入你的数据库信息：

# 服务器配置
NODE_ENV=development
PORT=3000

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_NAME=steel_prices
DB_USER=root
DB_PASSWORD=your_password

# 日志配置
LOG_LEVEL=info

2. 创建数据库

确保 MySQL 已安装并运行，然后执行：

# 方式 1: 使用 npm 脚本（推荐）
npm run db:init

# 方式 2: 手动创建
mysql -u root -p -e "CREATE DATABASE steel_prices CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

3. 导入数据

导入钢材价格数据：

npm run db:import

这将导入 data/ 目录下的所有 JSON 数据文件（约 31,098 条记录）。

4. 启动服务

# 开发模式
npm run dev

# 或生产模式
npm start

服务将在 http://localhost:3000 启动。

5. 测试 API

打开浏览器或使用 curl 测试：

# 健康检查
curl http://localhost:3000/api/health

# 按地区查询价格
curl "http://localhost:3000/api/prices/region?region=昆明"

# 搜索价格数据
curl "http://localhost:3000/api/prices/search?material=HPB300&startDate=2026-01-01&endDate=2026-01-05"

# 获取价格统计
curl "http://localhost:3000/api/prices/stats?region=昆明&days=30"

# 获取价格趋势
curl "http://localhost:3000/api/prices/trend?material=HPB300&days=30"

📚 API 端点

方法	端点	描述
GET	/api/health	健康检查
GET	/	API 信息
GET	/api/prices/region	按地区查询价格
GET	/api/prices/search	搜索价格数据
GET	/api/prices/stats	获取价格统计
GET	/api/prices/trend	获取价格趋势
POST	/api/prices/import	导入价格数据

🔧 常见问题

数据库连接失败

1. 检查 MySQL 服务是否运行
2. 确认 .env 中的数据库配置正确
3. 确保数据库用户有足够的权限

端口被占用

如果 3000 端口被占用，可以修改 .env 中的 PORT 配置：

PORT=3001

数据导入失败

1. 确保 data/ 目录下的 JSON 文件存在
2. 检查数据库表是否已创建
3. 查看控制台错误日志

📊 数据统计

导入完成后，可以查看数据库统计信息：

npm run db:import

脚本会自动显示：

• 总记录数
• 平均价格
• 最低/最高价格

🎯 下一步

• 查看 README.md 了解项目详情
• 查看 API 文档 了解完整的 API 使用方法
• 查看项目 CLAUDE.md 了解项目架构

---

有问题？查看 GitHub Issues