471 lines
13 KiB
Markdown
471 lines
13 KiB
Markdown
# 🏗️ Steel Prices Service
|
||
|
||
> 一个专业的钢材价格查询与分析服务平台
|
||
|
||
[](https://nodejs.org/)
|
||
[](https://www.mysql.com/)
|
||
[](LICENSE)
|
||
[](https://github.com)
|
||
|
||
---
|
||
|
||
## 📖 项目简介
|
||
|
||
Steel Prices Service 是一个基于 **Express.js + MySQL** 的钢材价格数据管理与查询服务。项目致力于为钢材行业提供实时、准确的价格数据查询、统计分析和趋势预测功能。
|
||
|
||
### 核心功能
|
||
|
||
- 📊 **数据解析与导入** - 支持 JSON 格式的钢材价格数据批量导入
|
||
- 🔍 **灵活查询** - 按地区、材质、规格、日期范围等多维度查询
|
||
- 📈 **统计分析** - 价格趋势分析、区域对比、均价计算
|
||
- 🚀 **高性能** - 数据库索引优化，查询响应快速
|
||
- 🔄 **定时更新** - 自动采集最新市场价格数据
|
||
- 📱 **RESTful API** - 标准化接口设计，易于集成
|
||
|
||
---
|
||
|
||
## 🏗️ 技术架构
|
||
|
||
### 技术栈
|
||
|
||
| 层级 | 技术选型 | 说明 |
|
||
|------|----------|------|
|
||
| **后端框架** | Express.js | 轻量级 Node.js Web 框架 |
|
||
| **数据库** | MySQL 8.0+ | 关系型数据库，存储价格数据 |
|
||
| **API 文档** | Swagger (OpenAPI 3.0) | 交互式 API 文档 |
|
||
| **ORM** | Sequelize / 原生 SQL | 数据库操作抽象层 |
|
||
| **数据采集** | Axios + Cheerio | 网络爬虫，自动采集价格数据 |
|
||
| **任务调度** | node-cron | 定时任务，自动更新数据 |
|
||
| **测试** | Jest / Mocha | 单元测试与集成测试 |
|
||
| **容器化** | Docker | 应用容器化部署 |
|
||
|
||
### 系统架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 客户端层 (Client) │
|
||
│ Web / Mobile App / Third Party │
|
||
└─────────────────────────┬───────────────────────────────────┘
|
||
│ HTTPS / REST API
|
||
┌─────────────────────────┴───────────────────────────────────┐
|
||
│ 服务接口层 (API Layer) │
|
||
│ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ REST API │ │ WebSocket │ │
|
||
│ └──────────────┘ └──────────────┘ │
|
||
└─────────────────────────┬───────────────────────────────────┘
|
||
│
|
||
┌─────────────────────────┴───────────────────────────────────┐
|
||
│ 业务逻辑层 (Service Layer) │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ 查询服务 │ │ 统计服务 │ │ 采集服务 │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||
└─────────────────────────┬───────────────────────────────────┘
|
||
│
|
||
┌─────────────────────────┴───────────────────────────────────┐
|
||
│ 数据访问层 (Data Layer) │
|
||
│ ┌──────────────┐ │
|
||
│ │ MySQL │ │
|
||
│ │ (主存储) │ │
|
||
│ └──────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 数据资产
|
||
|
||
项目当前包含 **31,098 条**钢材价格数据记录：
|
||
|
||
| 数据源 | 记录数 | 覆盖地区 | 更新日期 | 状态 |
|
||
|--------|--------|----------|----------|------|
|
||
| **我的钢铁网** | 211 条 | 重庆、成都、广州、南宁 | 2026-01-05 | ✅ 新鲜 |
|
||
| **德钢指导价** | 29,987 条 | 云南（玉溪、昭通等） | 2025-09-04 | ⚠️ 陈旧 |
|
||
| **云南钢协** | 900 条 | 昆明、玉溪、楚雄、大理 | 2026-01-05 | ✅ 新鲜 |
|
||
|
||
数据文件位于 [`data/`](data/) 目录，详见 [data/CLAUDE.md](data/CLAUDE.md)。
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- **Node.js**: >= 16.x
|
||
- **MySQL**: >= 8.0
|
||
|
||
### 安装步骤
|
||
|
||
#### 1. 克隆项目
|
||
|
||
```bash
|
||
git clone https://github.com/your-username/steel_prices_service.git
|
||
cd steel_prices_service
|
||
```
|
||
|
||
#### 2. 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
#### 3. 配置环境变量
|
||
|
||
复制 `.env.example` 到 `.env` 并配置：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 `.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
|
||
```
|
||
|
||
#### 4. 初始化数据库
|
||
|
||
```bash
|
||
# 创建数据库
|
||
mysql -u root -p -e "CREATE DATABASE steel_prices CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
|
||
|
||
# 导入表结构（使用 scripts/init-db.sql 或运行初始化脚本）
|
||
npm run db:init
|
||
|
||
# 导入数据（从 data/ 目录的 JSON 文件）
|
||
npm run db:import
|
||
```
|
||
|
||
#### 5. 启动服务
|
||
|
||
```bash
|
||
# 开发模式（热重载）
|
||
npm run dev
|
||
|
||
# 生产模式
|
||
npm start
|
||
```
|
||
|
||
服务将在 `http://localhost:3000` 启动。
|
||
|
||
---
|
||
|
||
## 📚 API 文档
|
||
|
||
### 📖 交互式文档（Swagger UI）
|
||
|
||
启动服务后，访问 **Swagger UI** 查看完整的 API 文档：
|
||
|
||
```
|
||
http://localhost:3000/api-docs
|
||
```
|
||
|
||
**功能特性：**
|
||
- 📖 完整的 API 接口文档
|
||
- 🧪 直接在浏览器中测试 API
|
||
- 📝 详细的请求/响应示例
|
||
- 🔍 参数说明和验证规则
|
||
- 🎨 美观的交互式界面
|
||
|
||
详细使用说明请查看：[API 文档指南](docs/API_DOCUMENTATION.md)
|
||
|
||
### 基础信息
|
||
|
||
- **Base URL**: `http://localhost:3000/api`
|
||
- **数据格式**: JSON
|
||
- **字符编码**: UTF-8
|
||
- **API 规范**: OpenAPI 3.0
|
||
|
||
### 核心接口
|
||
|
||
#### 1. 按地区查询价格
|
||
|
||
```http
|
||
GET /api/prices/region?region=昆明&date=2026-01-05
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"region": "昆明",
|
||
"material": "螺纹钢",
|
||
"specification": "HRB400 Φ16-25mm",
|
||
"price": 4200,
|
||
"unit": "元/吨",
|
||
"date": "2026-01-05",
|
||
"source": "云南钢协"
|
||
}
|
||
],
|
||
"total": 1
|
||
}
|
||
```
|
||
|
||
#### 2. 按材质和规格查询
|
||
|
||
```http
|
||
GET /api/prices/search?material=螺纹钢&specification=HRB400&startDate=2026-01-01&endDate=2026-01-05
|
||
```
|
||
|
||
#### 3. 价格统计分析
|
||
|
||
```http
|
||
GET /api/prices/stats?region=昆明&material=螺纹钢&days=30
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"avgPrice": 4250.5,
|
||
"minPrice": 4100,
|
||
"maxPrice": 4400,
|
||
"trend": "up",
|
||
"changeRate": "+2.5%"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 4. 数据导入
|
||
|
||
```http
|
||
POST /api/import
|
||
Content-Type: multipart/form-data
|
||
|
||
file: prices.json
|
||
```
|
||
|
||
### 完整 API 文档
|
||
|
||
详细的 API 文档请查看：
|
||
- **Swagger UI**: `http://localhost:3000/api-docs` （推荐）
|
||
- **JSON 规范**: `http://localhost:3000/api-docs.json`
|
||
- **使用指南**: [API Documentation](docs/API_DOCUMENTATION.md)
|
||
|
||
---
|
||
|
||
## 🧪 测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
npm test
|
||
|
||
# 运行单元测试
|
||
npm run test:unit
|
||
|
||
# 运行集成测试
|
||
npm run test:integration
|
||
|
||
# 生成测试覆盖率报告
|
||
npm run test:coverage
|
||
```
|
||
|
||
---
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
steel_prices_service/
|
||
├── src/ # 源代码目录
|
||
│ ├── config/ # 配置文件
|
||
│ │ ├── database.js # 数据库配置
|
||
│ │ └── logger.js # 日志配置
|
||
│ ├── controllers/ # 控制器层
|
||
│ │ ├── priceController.js
|
||
│ │ └── importController.js
|
||
│ ├── services/ # 业务逻辑层
|
||
│ │ ├── priceService.js
|
||
│ │ ├── statsService.js
|
||
│ │ └── crawlService.js
|
||
│ ├── models/ # 数据模型
|
||
│ │ ├── Price.js
|
||
│ │ └── index.js
|
||
│ ├── routes/ # 路由定义
|
||
│ │ ├── api.js
|
||
│ │ └── index.js
|
||
│ ├── middlewares/ # 中间件
|
||
│ │ ├── errorHandler.js
|
||
│ │ └── validator.js
|
||
│ ├── utils/ # 工具函数
|
||
│ │ ├── csvParser.js
|
||
│ │ └── dateHelper.js
|
||
│ ├── tasks/ # 定时任务
|
||
│ │ └── priceCrawler.js
|
||
│ └── app.js # Express 应用入口
|
||
├── data/ # 数据文件目录
|
||
│ ├── 钢材网架.json
|
||
│ ├── 钢厂指导价.json
|
||
│ ├── 刚协指导价.json
|
||
│ └── CLAUDE.md # 数据模块文档
|
||
├── scripts/ # 脚本目录
|
||
│ ├── init-db.sql # 数据库初始化脚本
|
||
│ └── import-data.js # 数据导入脚本
|
||
├── tests/ # 测试目录
|
||
│ ├── unit/
|
||
│ └── integration/
|
||
├── docs/ # 文档目录
|
||
│ ├── api.md # API 文档
|
||
│ └── architecture.md # 架构设计文档
|
||
├── .env.example # 环境变量示例
|
||
├── .gitignore # Git 忽略文件
|
||
├── docker-compose.yml # Docker 编排文件
|
||
├── Dockerfile # Docker 镜像构建文件
|
||
├── package.json # 项目配置
|
||
├── CLAUDE.md # 项目 AI 上下文文档
|
||
└── README.md # 项目说明文档
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 开发指南
|
||
|
||
### 编码规范
|
||
|
||
项目遵循以下编码规范（详见 [CLAUDE.md](CLAUDE.md)）：
|
||
|
||
- **SOLID 原则** - 单一职责、开闭原则、里氏替换、接口隔离、依赖倒置
|
||
- **KISS 原则** - 保持代码简单直接
|
||
- **DRY 原则** - 避免代码重复
|
||
- **YAGNI 原则** - 只实现必要功能
|
||
|
||
### 提交规范
|
||
|
||
使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
|
||
|
||
```bash
|
||
feat: 新功能
|
||
fix: 修复 Bug
|
||
docs: 文档更新
|
||
style: 代码格式调整
|
||
refactor: 重构
|
||
test: 测试相关
|
||
chore: 构建/工具链更新
|
||
```
|
||
|
||
### 开发路线图
|
||
|
||
详见 [CLAUDE.md - 开发路线图](CLAUDE.md#开发路线图)。
|
||
|
||
#### 当前阶段：🌱 阶段 1 - 数据准备与验证（进行中）
|
||
|
||
- [x] 数据收集（31,098 条记录）
|
||
- [ ] 数据库设计与建表
|
||
- [ ] 数据导入脚本开发
|
||
- [ ] 数据验证与清洗
|
||
|
||
#### 后续阶段
|
||
|
||
- **阶段 2**: 核心服务开发（API 开发）
|
||
- **阶段 3**: 数据采集自动化（定时任务）
|
||
- **阶段 4**: 智能分析与预测（AI 集成）
|
||
|
||
---
|
||
|
||
## 🐳 Docker 部署
|
||
|
||
### 使用 Docker Compose（推荐）
|
||
|
||
```bash
|
||
# 启动所有服务（MySQL + App）
|
||
docker-compose up -d
|
||
|
||
# 查看日志
|
||
docker-compose logs -f
|
||
|
||
# 停止服务
|
||
docker-compose down
|
||
```
|
||
|
||
### 单独构建
|
||
|
||
```bash
|
||
# 构建镜像
|
||
docker build -t steel-prices-service .
|
||
|
||
# 运行容器
|
||
docker run -p 3000:3000 --env-file .env steel-prices-service
|
||
```
|
||
|
||
---
|
||
|
||
## 🤝 贡献指南
|
||
|
||
欢迎贡献代码、报告 Bug 或提出新功能建议！
|
||
|
||
### 贡献流程
|
||
|
||
1. Fork 本仓库
|
||
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
|
||
3. 提交更改 (`git commit -m 'feat: Add some AmazingFeature'`)
|
||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||
5. 提交 Pull Request
|
||
|
||
### 代码审查
|
||
|
||
- 确保代码通过所有测试 (`npm test`)
|
||
- 遵循项目编码规范
|
||
- 添加必要的注释和文档
|
||
- 更新相关文档
|
||
|
||
详见 [贡献指南](CONTRIBUTING.md)。
|
||
|
||
---
|
||
|
||
## 📄 许可证
|
||
|
||
本项目采用 [MIT 许可证](LICENSE)。
|
||
|
||
---
|
||
|
||
## 📞 联系方式
|
||
|
||
- **作者**: Your Name
|
||
- **邮箱**: your.email@example.com
|
||
- **项目主页**: [https://github.com/your-username/steel_prices_service](https://github.com/your-username/steel_prices_service)
|
||
- **问题反馈**: [GitHub Issues](https://github.com/your-username/steel_prices_service/issues)
|
||
|
||
---
|
||
|
||
## 🙏 致谢
|
||
|
||
- 数据来源：我的钢铁网、德钢、云南钢协
|
||
- 技术栈：Express.js、MySQL
|
||
- 社区贡献者
|
||
|
||
---
|
||
|
||
## 📊 项目状态
|
||
|
||
|
||
|
||
|
||
**当前版本**: v0.1.0 (Alpha)
|
||
|
||
**最近更新**: 2026-01-05
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
**如果这个项目对您有帮助，请给一个 ⭐️ Star 支持一下！**
|
||
|
||
[⬆ 返回顶部](#-steel-prices-service)
|
||
|
||
</div> |