guest/steel_prices_service

Fork 0

Files

bai ba478d70cc init：代码初始化

2026-01-06 09:19:12 +08:00

15 KiB

Raw Blame History

steel_prices_service - 钢材价格服务

项目状态: 🌱 初始阶段（数据准备完成，待开发服务层）

最后更新: 2026-01-05 16:13:47

变更记录 (Changelog)

2026-01-05 16:13:47

初始化根级文档
完成项目结构分析
识别数据模块并生成模块文档
创建 Mermaid 架构图
定义开发路线图

项目愿景

steel_prices_service 是一个钢材价格数据解析与查询服务，旨在：

数据整合: 从多个来源（我的钢铁网、钢厂官方、行业协会）采集钢材价格数据
标准化存储: 使用 MySQL 数据库统一存储和管理价格数据
高效查询: 提供快速、灵活的价格查询 API
实时更新: 支持定时任务自动采集和更新价格数据

核心价值

为钢材采购决策提供实时市场价格参考
支持历史价格趋势分析
多地区、多钢厂价格对比
自动化数据采集减少人工成本

架构总览

技术栈（规划中）

根据项目 README 和数据结构，预计技术栈为：

后端框架: Express.js (Node.js)
数据库: MySQL
数据格式: JSON（导入格式）
API 设计: RESTful

注意：项目目前处于数据准备阶段，尚未实现服务代码。

系统架构

┌─────────────────────────────────────────────────────────────┐
│                      数据采集层                              │
│  我的钢铁网  │  钢厂官方  │  行业协会  │  手动导入           │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                      数据处理层                              │
│  JSON 解析  │  数据清洗  │  验证  │  转换                   │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                      数据存储层                              │
│                    MySQL 数据库                             │
│  价格表  │  索引优化  │  定时归档                          │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                      服务接口层                              │
│              Express.js REST API                           │
│  价格查询  │  趋势分析  │  数据导出                        │
└─────────────────────────────────────────────────────────────┘

模块结构图

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 格式）	✅ 已完成	查看文档
服务模块	（待创建）	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

运行与开发

当前状态

项目目前只有数据文件，尚未搭建服务层代码。

建议的开发环境

Node.js: v18+ (推荐使用 LTS 版本)
MySQL: 8.0+
包管理器: npm 或 yarn

初始化步骤

初始化 Node.js 项目
```
npm init -y
```

安装依赖

npm install express mysql2 dotenv cors
npm install --save-dev nodemon jest

创建数据库表

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='钢材价格表';

配置环境变量 (.env)

DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=steel_prices
PORT=3000
NODE_ENV=development

导入数据
```
node scripts/import-data.js
```
启动服务
```
npm start
```

测试策略

测试金字塔（建议）

        ┌──────────────┐
       /   E2E 测试    \  (端到端测试)
      /__________________\
     /   集成测试 (API)   \  (API 接口测试)
    /______________________\
   /    单元测试 (业务逻辑)   \  (函数/类测试)
  /____________________________\

测试工具推荐

单元测试: Jest + Supertest
集成测试: Jest + Test Database
E2E 测试: Cypress 或 Playwright
API 测试: Postman + Newman

关键测试场景

数据导入测试
- JSON 文件解析正确性
- 数据验证与清洗
- 重复数据处理
- 批量插入性能
API 接口测试
- 价格查询接口（按地区、材质、日期）
- 数据统计接口（平均价、涨跌幅）
- 错误处理（无效参数、数据不存在）
性能测试
- 大数据量查询响应时间
- 并发请求处理能力
- 数据库索引效果验证

编码规范

JavaScript/Node.js 规范（建议）

代码风格
- 使用 ESLint + Prettier
- 采用 Airbnb Style Guide
- 强制使用分号
命名约定
- 变量和函数：camelCase
- 类和构造函数：PascalCase
- 常量：UPPER_SNAKE_CASE
- 文件名：kebab-case
注释规范
- JSDoc 格式文档注释
- 关键业务逻辑必须注释
- API 接口使用 OpenAPI/Swagger 文档
错误处理
- 使用 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: 建议采用以下策略：

使用 PRICE_ID 作为唯一标识，避免重复导入
使用 UPSERT 语句（INSERT ... ON DUPLICATE KEY UPDATE）
添加数据校验和（checksum）
记录数据导入日志

Q: 如何处理大量历史数据？