# steel_prices_service - 钢材价格服务
> **项目状态**: 🌱 初始阶段（数据准备完成，待开发服务层）
>
> **最后更新**: 2026-01-05 16:13:47
---
## 变更记录 (Changelog)
### 2026-01-05 16:13:47
- 初始化根级文档
- 完成项目结构分析
- 识别数据模块并生成模块文档
- 创建 Mermaid 架构图
- 定义开发路线图
---
## 项目愿景
**steel_prices_service** 是一个钢材价格数据解析与查询服务，旨在：
1. **数据整合**: 从多个来源（我的钢铁网、钢厂官方、行业协会）采集钢材价格数据
2. **标准化存储**: 使用 MySQL 数据库统一存储和管理价格数据
3. **高效查询**: 提供快速、灵活的价格查询 API
4. **实时更新**: 支持定时任务自动采集和更新价格数据
### 核心价值
- 为钢材采购决策提供实时市场价格参考
- 支持历史价格趋势分析
- 多地区、多钢厂价格对比
- 自动化数据采集减少人工成本
---
## 架构总览
### 技术栈（规划中）
根据项目 README 和数据结构，预计技术栈为：
- **后端框架**: Express.js (Node.js)
- **数据库**: MySQL
- **数据格式**: JSON（导入格式）
- **API 设计**: RESTful
> 注意：项目目前处于数据准备阶段，尚未实现服务代码。
### 系统架构
```
┌─────────────────────────────────────────────────────────────┐
│ 数据采集层 │
│ 我的钢铁网 │ 钢厂官方 │ 行业协会 │ 手动导入 │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 数据处理层 │
│ JSON 解析 │ 数据清洗 │ 验证 │ 转换 │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 数据存储层 │
│ MySQL 数据库 │
│ 价格表 │ 索引优化 │ 定时归档 │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 服务接口层 │
│ Express.js REST API │
│ 价格查询 │ 趋势分析 │ 数据导出 │
└─────────────────────────────────────────────────────────────┘
```
---
## 模块结构图
```mermaid
graph TD
Root["steel_prices_service
(根目录)"]
Root --> Data["data/
📦 数据模块"]
click Data "d:/Code/steel_prices_service/data/CLAUDE.md" "查看 data 模块文档"
style Root fill:#e1f5ff,stroke:#01579b,stroke-width:3px
style Data fill:#fff9c4,stroke:#f57f17,stroke-width:2px
```
---
## 模块索引
| 模块名 | 路径 | 职责 | 状态 | 文档 |
|--------|------|------|------|------|
| **数据模块** | `data/` | 存储和管理钢材价格原始数据（JSON 格式） | ✅ 已完成 | [查看文档](./data/CLAUDE.md) |
| **服务模块** | （待创建） | Express.js 服务、API 接口 | ⏳ 待开发 | - |
| **数据导入** | （待创建） | JSON 解析、数据清洗、数据库导入 | ⏳ 待开发 | - |
| **测试模块** | （待创建） | 单元测试、集成测试 | ⏳ 待开发 | - |
---
## 数据资产
### 当前数据
| 数据源 | 文件 | 记录数 | 地区覆盖 | 更新日期 |
|--------|------|--------|----------|----------|
| **我的钢铁网** | `data/钢材网架.json` | 211+ 条 | 重庆、成都、广州、南宁 | 2026-01-05 |
| **德钢指导价** | `data/钢厂指导价.json` | 29,987 条 | 云南省内（玉溪、昭通等） | 2025-09-04 |
| **云南钢协** | `data/刚协指导价.json` | 900 条 | 昆明、玉溪、楚雄、大理 | 2026-01-05 |
### 数据模型
所有价格数据遵循统一的结构，包含以下关键字段：
- **商品信息**: 材质 (GOODS_MATERIAL)、规格 (GOODS_SPEC)、品名 (PARTSNAME_NAME)
- **价格信息**: 挂牌价、钢厂价、涨跌幅
- **来源信息**: 钢厂 (PRODUCTAREA_NAME)、地区 (PR_PRICE_REGION)、来源 (PR_PRICE_SOURCE)
- **时间信息**: 价格日期 (PIRCE_DATE)
- **唯一标识**: PRICE_ID
详细数据结构请参考 [data/CLAUDE.md](./data/CLAUDE.md)
---
## 运行与开发
### 当前状态
项目目前只有数据文件，尚未搭建服务层代码。
### 建议的开发环境
- **Node.js**: v18+ (推荐使用 LTS 版本)
- **MySQL**: 8.0+
- **包管理器**: npm 或 yarn
### 推荐的项目结构
```
steel_prices_service/
├── data/ # 数据文件目录（已存在）
│ ├── 钢材网架.json
│ ├── 钢厂指导价.json
│ └── 刚协指导价.json
├── src/ # 源代码目录（待创建）
│ ├── app.js # Express 应用入口
│ ├── config/ # 配置文件
│ │ └── database.js # 数据库连接配置
│ ├── routes/ # API 路由
│ │ └── prices.js # 价格查询接口
│ ├── models/ # 数据模型
│ │ └── Price.js # 价格数据模型
│ ├── services/ # 业务逻辑
│ │ ├── parser.js # JSON 解析服务
│ │ ├── importer.js # 数据导入服务
│ │ └── query.js # 查询服务
│ └── utils/ # 工具函数
│ └── validator.js # 数据验证
├── scripts/ # 脚本目录（待创建）
│ └── import-data.js # 数据导入脚本
├── tests/ # 测试目录（待创建）
│ ├── unit/ # 单元测试
│ └── integration/ # 集成测试
├── .env.example # 环境变量示例（待创建）
├── .gitignore # Git 忽略规则（待创建）
├── package.json # 项目配置（待创建）
├── README.md # 项目说明（已存在）
└── CLAUDE.md # AI 文档（本文件）
```
### 初始化步骤
1. **初始化 Node.js 项目**
```bash
npm init -y
```
2. **安装依赖**
```bash
npm install express mysql2 dotenv cors
npm install --save-dev nodemon jest
```
3. **创建数据库表**
```sql
CREATE TABLE steel_prices (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
price_id VARCHAR(64) UNIQUE NOT NULL COMMENT '价格唯一ID',
goods_material VARCHAR(32) NOT NULL COMMENT '材质牌号',
goods_spec VARCHAR(16) NOT NULL COMMENT '规格型号',
partsname_name VARCHAR(32) NOT NULL COMMENT '品名',
productarea_name VARCHAR(64) NOT NULL COMMENT '产地/钢厂',
price_source VARCHAR(32) NOT NULL COMMENT '价格来源',
price_region VARCHAR(32) NOT NULL COMMENT '价格地区',
pntree_name VARCHAR(32) NOT NULL COMMENT '分类名称',
price_date DATETIME NOT NULL COMMENT '价格日期',
make_price INT COMMENT '钢厂价（元/吨）',
hang_price INT COMMENT '挂牌价（元/吨）',
last_make_price INT COMMENT '上次钢厂价',
last_hang_price INT COMMENT '上次挂牌价',
make_price_updw VARCHAR(8) COMMENT '钢厂价涨跌',
hang_price_updw VARCHAR(8) COMMENT '挂牌价涨跌',
operator_code VARCHAR(16) COMMENT '操作员代码',
operator_name VARCHAR(32) COMMENT '操作员名称',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_price_date (price_date),
INDEX idx_region_material (price_region, goods_material),
INDEX idx_source_date (price_source, price_date)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='钢材价格表';
```
4. **配置环境变量** (.env)
```env
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=steel_prices
PORT=3000
NODE_ENV=development
```
5. **导入数据**
```bash
node scripts/import-data.js
```
6. **启动服务**
```bash
npm start
```
---
## 测试策略
### 测试金字塔（建议）
```
┌──────────────┐
/ E2E 测试 \ (端到端测试)
/__________________\
/ 集成测试 (API) \ (API 接口测试)
/______________________\
/ 单元测试 (业务逻辑) \ (函数/类测试)
/____________________________\
```
### 测试工具推荐
- **单元测试**: Jest + Supertest
- **集成测试**: Jest + Test Database
- **E2E 测试**: Cypress 或 Playwright
- **API 测试**: Postman + Newman
### 关键测试场景
1. **数据导入测试**
- JSON 文件解析正确性
- 数据验证与清洗
- 重复数据处理
- 批量插入性能
2. **API 接口测试**
- 价格查询接口（按地区、材质、日期）
- 数据统计接口（平均价、涨跌幅）
- 错误处理（无效参数、数据不存在）
3. **性能测试**
- 大数据量查询响应时间
- 并发请求处理能力
- 数据库索引效果验证
---
## 编码规范
### JavaScript/Node.js 规范（建议）
1. **代码风格**
- 使用 ESLint + Prettier
- 采用 Airbnb Style Guide
- 强制使用分号
2. **命名约定**
- 变量和函数：camelCase
- 类和构造函数：PascalCase
- 常量：UPPER_SNAKE_CASE
- 文件名：kebab-case
3. **注释规范**
- JSDoc 格式文档注释
- 关键业务逻辑必须注释
- API 接口使用 OpenAPI/Swagger 文档
4. **错误处理**
- 使用 async/await + try-catch
- 统一错误中间件
- 详细的错误日志
### SQL 规范
- 表名：snake_case
- 字段名：snake_case
- 索引名：idx_表名_字段名
- 必须添加字段注释
---
## AI 使用指引
### 给 AI 的提示词模板
#### 1. 数据库相关
```
"请根据 data/CLAUDE.md 中的数据结构，设计 MySQL 建表语句"
```
#### 2. API 开发
```
"请创建 Express.js 路由，实现按地区和材质查询价格的功能"
```
#### 3. 数据导入
```
"请编写 Node.js 脚本，将 data/*.json 文件导入到 MySQL 数据库"
```
#### 4. 性能优化
```
"请优化价格查询接口，支持快速查询最近30天的平均价格"
```
### 项目上下文快速加载
在与 AI 对话时，可以这样说：
> "我正在开发 steel_prices_service 项目，这是一个钢材价格查询服务。项目使用 Express.js + MySQL，数据文件在 data/ 目录下。请参考根目录的 CLAUDE.md 了解项目结构。"
---
## 开发路线图
### 第一阶段：基础搭建（预计 1-2 周）
- [ ] 初始化 Node.js 项目
- [ ] 创建数据库表结构
- [ ] 实现 JSON 数据解析模块
- [ ] 实现数据导入脚本
- [ ] 基础 API 框架搭建
### 第二阶段：核心功能（预计 2-3 周）
- [ ] 价格查询 API（按地区、材质、日期）
- [ ] 价格统计 API（平均价、最高价、最低价）
- [ ] 趋势分析 API（涨跌幅、历史曲线）
- [ ] 数据验证与清洗逻辑
- [ ] 错误处理与日志记录
### 第三阶段：增强功能（预计 1-2 周）
- [ ] 定时任务自动采集数据
- [ ] 数据变更通知
- [ ] 数据导出功能（Excel、CSV）
- [ ] API 文档（Swagger）
- [ ] 性能优化与缓存
### 第四阶段：测试与部署（预计 1 周）
- [ ] 单元测试覆盖
- [ ] 集成测试
- [ ] Docker 容器化
- [ ] CI/CD 流程
- [ ] 生产环境部署
---
## 常见问题 (FAQ)
### Q: 为什么选择 Express.js 而不是其他框架？
A: Express.js 是成熟稳定的 Node.js 框架，具有以下优势：
- 轻量级，灵活性高
- 中间件生态丰富
- 社区活跃，文档完善
- 适合构建 RESTful API
如果需要更完整的解决方案，也可以考虑 NestJS 或 Fastify。
### Q: 数据库如何选择？
A: 根据项目特点，MySQL 是合适的选择：
- 结构化数据，关系清晰
- 事务支持强
- 索引优化成熟
- 运维成本低
未来如果数据量激增，可考虑：
- 分库分表（Sharding）
- 时序数据库（InfluxDB）
- 数据仓库（ClickHouse）
### Q: 如何保证数据一致性？
A: 建议采用以下策略：
1. 使用 PRICE_ID 作为唯一标识，避免重复导入
2. 使用 UPSERT 语句（INSERT ... ON DUPLICATE KEY UPDATE）
3. 添加数据校验和（checksum）
4. 记录数据导入日志
### Q: 如何处理大量历史数据？
A: 建议采用以下策略：
1. 按日期分表（如 `steel_prices_2025_01`）
2. 定期归档历史数据（如 2 年前的数据）
3. 使用冷热数据分离（热数据在 SSD，冷数据在 HDD）
4. 考虑使用时序数据库或数据仓库
---
## 相关资源
### 技术文档
- [Express.js 官方文档](https://expressjs.com/)
- [MySQL 文档](https://dev.mysql.com/doc/)
- [Node.js 最佳实践](https://github.com/goldbergyoni/nodebestpractices)
### 相关工具
- **API 测试**: Postman, Insomnia
- **数据库管理**: MySQL Workbench, DBeaver
- **代码质量**: ESLint, Prettier
- **版本控制**: Git + GitHub
---
## 贡献指南
### 开发流程
1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request
### Commit 规范
遵循 Conventional Commits 规范：
```
feat: 添加价格查询接口
fix: 修复数据导入时的编码问题
docs: 更新 API 文档
style: 代码格式化
refactor: 重构数据验证逻辑
test: 添加单元测试
chore: 更新依赖包
```
---
## 联系方式
- **项目位置**: `d:\Code\steel_prices_service`
- **文档维护**: AI Context Architect
- **最后更新**: 2026-01-05 16:13:47
---
**导航**: [data/ 模块文档](./data/CLAUDE.md) | [GitHub](https://github.com) | [API 文档](#) (待开发)