481 lines
15 KiB
Markdown
481 lines
15 KiB
Markdown
# 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<br/>(根目录)"]
|
||
Root --> Data["data/<br/>📦 数据模块"]
|
||
|
||
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 文档](#) (待开发)
|