guest/steel_prices_service

Fork 0

Files

ECRZ 60b5aba7f8 modify：优化

2026-01-07 10:13:21 +08:00

16 KiB

Raw Blame History

SaleInfo - 钢材价格查询小程序

项目状态: 🚀 已完成（功能完整，可投入使用）

最后更新: 2026-01-07 09:16:32

变更记录 (Changelog)

2026-01-07 09:16:32

重新生成完整的 AI 上下文文档
补充项目架构分析
更新模块索引与依赖关系
添加 Mermaid 结构图
补充测试策略与编码规范

2026-01-06

完成价格查询功能开发
新增价格趋势图表页面
集成 TDesign 组件库
集成 ECharts 图表库
实现 TabBar 导航
添加品名筛选功能

项目愿景

SaleInfo 是一个专注于钢材价格查询的微信小程序，为用户提供简洁、快速、专业的钢材价格查询与趋势分析服务。

核心价值

实时价格查询：支持多维度查询（地区、材质、规格、日期）
趋势可视化：折线图展示价格走势，直观了解市场动态
数据统计分析：自动计算均价、最高价、最低价、涨跌幅
简洁专业界面：基于 TDesign 的现代化 UI 设计
快速响应：优化的 API 调用与数据处理

目标用户

钢材采购人员
建筑行业从业者
钢材经销商
市场分析师

架构总览

技术栈

前端技术

小程序框架：微信小程序原生框架（基础库 2.10.4+）
组件框架：glass-easel（微信小程序组件框架）
UI 组件库：TDesign 小程序版 v1.12.1
图表库：ECharts for 微信小程序
开发语言：JavaScript (ES6+)
样式语言：WXSS（类似 CSS）
标记语言：WXML（类似 HTML）

后端服务

API 协议：HTTP/HTTPS RESTful API
数据格式：JSON
文档规范：OpenAPI 3.0（swagger.json）
后端技术：Node.js + Express（独立部署）
API 地址：http://makepower.top:9333

开发工具

IDE：微信开发者工具
版本控制：Git
包管理：npm

系统架构

┌─────────────────────────────────────────────────────────────┐
│                   微信小程序前端                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ 价格查询页   │  │ 价格趋势页   │  │  TDesign组件 │      │
│  │  (index)     │  │   (trend)    │  │   UI Library │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│         │                  │                  │              │
│         └──────────────────┼──────────────────┘              │
│                            │                                 │
│                    ┌───────▼────────┐                        │
│                    │ API 请求封装   │                        │
│                    │ (request.js)   │                        │
│                    └───────┬────────┘                        │
└────────────────────────────┼────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                      后端 API 服务                            │
│                    (Node.js + Express)                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ 价格查询接口 │  │ 统计分析接口 │  │ 趋势分析接口 │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└────────────────────────────┬────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                    MySQL 数据库                              │
│              (steel_prices 数据库)                          │
└─────────────────────────────────────────────────────────────┘

模块结构图

graph TD
    Root["SaleInfo<br/>(钢材价格查询小程序)"]
    Root --> Pages["pages/<br/>📱 页面模块"]
    Root --> Utils["utils/<br/>🔧 工具模块"]
    Root --> Components["components/<br/>🎨 组件模块"]
    Root --> Config["⚙️ 配置文件"]

    Pages --> Index["index/<br/>🔍 价格查询页"]
    Pages --> Trend["trend/<br/>📈 价格趋势页"]

    Utils --> Util["util.js<br/>通用工具"]
    Utils --> Request["request.js<br/>API 封装"]

    Components --> EcCanvas["ec-canvas/<br/>📊 ECharts 图表组件"]

    Config --> AppJson["app.json<br/>应用配置"]
    Config --> Swagger["swagger.json<br/>API 文档"]

    click Index "#pages-index" "查看 index 页面文档"
    click Trend "#pages-trend" "查看 trend 页面文档"
    click Utils "#utils" "查看 utils 模块文档"
    click EcCanvas "#components-ec-canvas" "查看 ec-canvas 组件文档"

    style Root fill:#e1f5ff,stroke:#01579b,stroke-width:3px
    style Pages fill:#fff9c4,stroke:#f57f17,stroke-width:2px
    style Index fill:#c8e6c9,stroke:#388e3c,stroke-width:2px
    style Trend fill:#c8e6c9,stroke:#388e3c,stroke-width:2px
    style Components fill:#f8bbd0,stroke:#c2185b,stroke-width:2px

模块索引

模块名	路径	职责	状态	文档
价格查询页	`pages/index`	主页，提供价格查询、统计展示、结果列表功能	✅ 已完成	查看文档
价格趋势页	`pages/trend`	趋势分析页，提供折线图展示与数据统计	✅ 已完成	查看文档
API 封装	`utils/request.js`	统一的 HTTP 请求封装与 API 接口定义	✅ 已完成	内联文档
通用工具	`utils/util.js`	日期时间格式化等通用工具函数	✅ 可用	查看文档
图表组件	`components/ec-canvas`	ECharts 图表组件封装	✅ 已完成	查看文档
应用配置	`app.json`	小程序全局配置、页面路由、组件注册	✅ 已配置	-
API 文档	`swagger.json`	后端 API 接口规范（OpenAPI 3.0）	✅ 完整	-

运行与开发

开发环境要求

微信开发者工具：最新稳定版
小程序基础库：2.10.4 及以上
Node.js：v14+（用于安装依赖）
后端 API 服务：运行在 http://makepower.top:9333

快速启动

1. 安装依赖

npm install

2. 构建npm

在微信开发者工具中：

菜单栏 → 工具 → 构建 npm
等待构建完成

3. 配置后端地址

编辑 utils/request.js 中的 API 基础地址：

const API_BASE_URL = 'http://makepower.top:9333'

4. 启动开发

使用微信开发者工具打开项目根目录
确保 AppID 配置正确（project.config.json）
点击"编译"按钮预览
在模拟器或真机中测试功能

开发配置

项目配置文件

project.config.json

{
  "appid": "wx26668630c98d7228",
  "compileType": "miniprogram",
  "libVersion": "trial"
}

app.json (关键配置)

{
  "pages": [
    "pages/index/index",
    "pages/trend/trend"
  ],
  "window": {
    "navigationBarTitleText": "钢材价格查询",
    "navigationBarBackgroundColor": "#0052D9"
  },
  "componentFramework": "glass-easel",
  "usingComponents": {
    "t-button": "tdesign-miniprogram/button/button"
  }
}

调试技巧

1. 网络请求调试

在微信开发者工具中：

调试器 → Network 面板
查看所有 API 请求与响应

2. 日志调试

console.log('查询参数:', params)

3. 真机调试

微信开发者工具 → 预览 → 生成二维码
使用微信扫码真机预览

后端 API 规范

API 基础信息

文档版本：1.0.0
协议：OpenAPI 3.0
Base URL：http://makepower.top:9333

主要接口列表

接口	方法	功能	使用场景
`/api/health`	GET	健康检查	启动时测试连接
`/api/prices/search`	GET	多条件搜索	价格查询（支持分页）
`/api/prices/stats`	GET	价格统计	统计卡片数据
`/api/prices/trend`	GET	价格趋势	趋势图表数据
`/api/prices/region`	GET	按地区查询	地区价格查询
`/api/prices/import`	POST	导入数据	批量导入（管理功能）

数据模型

Price（价格数据）

{
  price_region: "昆明",
  goods_material: "HPB300",
  goods_spec: "Φ8",
  hang_price: 3840,
  price_date: "2026-01-05",
  price_source: "云南钢协"
}

PriceStats（统计数据）

{
  count: 150,
  avgPrice: 3950.5,
  minPrice: 3500,
  maxPrice: 4500,
  trend: "up",
  changeRate: "+2.5%"
}

TrendData（趋势数据）

[
  { date: "2026-01-01", avgPrice: 3850 },
  { date: "2026-01-02", avgPrice: 3860 }
]

详细 API 文档请参考 swagger.json 文件。

测试策略

测试覆盖范围

1. 功能测试

✅ 价格查询功能（多条件组合）
✅ 统计数据展示
✅ 趋势图表渲染
✅ 表单验证（必填项、参数格式）
✅ 错误处理（网络异常、数据为空）
✅ 页面导航与 TabBar 切换

2. 兼容性测试

iOS 微信客户端
Android 微信客户端
不同屏幕尺寸适配
不同微信版本兼容性

3. 性能测试

首屏加载时间
API 响应时间
图表渲染性能
大数据量列表滚动

测试方法

手动测试流程

价格查询页测试

1. 选择地区（必填）
2. 可选：选择材质、品名、日期
3. 点击"查询价格"
4. 验证：统计数据展示正确
5. 验证：价格列表数据完整
6. 点击价格卡片，验证详情弹窗
7. 点击"重置"，验证表单清空

价格趋势页测试

1. 可选：选择地区、材质、时间范围
2. 点击"查询趋势"
3. 验证：折线图正常渲染
4. 验证：统计数据显示正确
5. 点击"重置"，验证图表清空

自动化测试（建议）

目前项目暂无自动化测试，建议补充：

单元测试：使用 Jest 测试工具函数
集成测试：使用微信开发者工具的自动化测试
E2E 测试：使用 Appium 或微信自动化 SDK

编码规范

JavaScript 规范

1. 代码风格

使用 ES6+ 语法
采用 2 空格缩进
使用单引号（字符串）
每行代码不超过 100 字符

2. 命名约定

变量和函数：驼峰命名法（camelCase）

const selectedRegion = '昆明'
function onSearch() { }

常量：全大写下划线分隔（UPPER_SNAKE_CASE）
```
const API_BASE_URL = 'http://...'
```

3. 注释规范

文件头注释：说明文件用途

函数注释：JSDoc 格式

/**
 * 搜索价格数据
 * @param {object} params - 搜索参数
 * @returns {Promise} 返回 Promise 对象
 */

4. 错误处理

使用 try-catch 捕获异步错误
统一错误提示机制

WXML/WXSS 规范

1. WXML 结构

使用 rpx 单位（响应式像素）
避免深层嵌套（不超过 3 层）
使用语义化的类名

2. WXSS 样式

遵循 BEM 命名规范
使用 Flex 布局
避免使用 ID 选择器

AI 使用指引

给 AI 的提示词模板

1. UI 开发

"请为价格查询页面设计一个简洁的搜索表单，包含地区、材质、日期选择器，使用 TDesign 组件库，蓝色主题（#0052D9）"

2. API 调用

"请基于 swagger.json 中的 API 定义，编写调用 /api/prices/search 接口的函数，支持多条件查询和错误处理"

3. 图表开发

"请使用 ECharts 绘制一个价格走势折线图，X 轴为日期，Y 轴为价格，支持平滑曲线和区域填充"

项目上下文快速加载

在与 AI 对话时，可以这样描述项目：

"我正在开发 SaleInfo 钢材价格查询小程序，使用微信小程序原生框架 + TDesign UI 组件库 + ECharts 图表库。项目有两个主要页面：价格查询页和价格趋势页，通过调用后端 RESTful API 获取数据。请参考根目录的 CLAUDE.md 了解项目结构。"

关键文件说明

文件	说明	用途
`swagger.json`	完整的后端 API 定义	所有接口调用参考此文档
`app.json`	小程序全局配置	页面路由、组件注册
`utils/request.js`	API 请求封装	统一的网络请求处理
`pages/index/index.js`	价格查询页逻辑	主要业务逻辑实现
`pages/trend/trend.js`	趋势分析页逻辑	图表数据处理

常见问题 (FAQ)

Q1: 如何修改 API 基础地址？

A: 编辑 utils/request.js 文件：

const API_BASE_URL = 'http://your-api-domain.com'

Q2: 如何添加新的地区选项？

A: 编辑 pages/index/index.js 的 regions 数组

Q3: 图表不显示怎么办？

A: 检查以下几点：

确保 ECharts 组件已正确引入
检查 API 返回数据格式
查看控制台错误信息

Q4: 如何部署到生产环境？

A: 步骤如下：

修改 utils/request.js 中的 API 地址
微信开发者工具 → 上传代码
微信公众平台 → 提交审核
审核通过后发布上线

开发路线图

✅ 已完成（Phase 1）

项目初始化与配置
价格查询页面开发
API 请求封装
统计数据展示
价格趋势页面开发
ECharts 图表集成
TDesign 组件库集成
TabBar 导航实现
表单验证与错误处理

🚀 待开发（Phase 2）

下拉刷新功能
搜索历史记录
价格数据缓存
收藏功能
数据导出（Excel/CSV）
多地区价格对比

🎯 规划中（Phase 3）

单元测试覆盖
性能优化（虚拟滚动）
智能推荐
价格预测（机器学习）

项目统计

代码规模

总文件数：18 个（不含 node_modules）
代码行数：约 2500 行
页面数：2 个
自定义组件：1 个
API 接口：6 个

联系方式

项目位置：d:\ECRZ\Gitea\new\steel_prices_service\Sale
文档维护：AI Context Architect
最后更新：2026-01-07 09:16:32

导航: 价格查询页 | 价格趋势页 | 工具函数 | 图表组件

16 KiB Raw Blame History Unescape Escape

SaleInfo - 钢材价格查询小程序

变更记录 (Changelog)

2026-01-07 09:16:32

2026-01-06

项目愿景

核心价值

目标用户

架构总览

技术栈

前端技术

后端服务

开发工具

系统架构

模块结构图

模块索引

运行与开发

开发环境要求

快速启动

1. 安装依赖

2. 构建npm

3. 配置后端地址

4. 启动开发

开发配置

项目配置文件

调试技巧

1. 网络请求调试

2. 日志调试

3. 真机调试

后端 API 规范

API 基础信息

主要接口列表

数据模型

Price（价格数据）

PriceStats（统计数据）

TrendData（趋势数据）

测试策略

测试覆盖范围

1. 功能测试

2. 兼容性测试

3. 性能测试

测试方法

手动测试流程

自动化测试（建议）

编码规范

JavaScript 规范

1. 代码风格

2. 命名约定

3. 注释规范

4. 错误处理

WXML/WXSS 规范

1. WXML 结构

2. WXSS 样式

AI 使用指引

给 AI 的提示词模板

1. UI 开发

2. API 调用

3. 图表开发

项目上下文快速加载

关键文件说明

常见问题 (FAQ)

Q1: 如何修改 API 基础地址？

Q2: 如何添加新的地区选项？

Q3: 图表不显示怎么办？

Q4: 如何部署到生产环境？

相关资源

技术文档

开发工具

开发路线图

✅ 已完成（Phase 1）

🚀 待开发（Phase 2）

🎯 规划中（Phase 3）

项目统计

代码规模

联系方式

16 KiB

Raw Blame History