# 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 数据库) │
└─────────────────────────────────────────────────────────────┘
```
---
## 模块结构图
```mermaid
graph TD
Root["SaleInfo
(钢材价格查询小程序)"]
Root --> Pages["pages/
📱 页面模块"]
Root --> Utils["utils/
🔧 工具模块"]
Root --> Components["components/
🎨 组件模块"]
Root --> Config["⚙️ 配置文件"]
Pages --> Index["index/
🔍 价格查询页"]
Pages --> Trend["trend/
📈 价格趋势页"]
Utils --> Util["util.js
通用工具"]
Utils --> Request["request.js
API 封装"]
Components --> EcCanvas["ec-canvas/
📊 ECharts 图表组件"]
Config --> AppJson["app.json
应用配置"]
Config --> Swagger["swagger.json
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/index/CLAUDE.md) |
| **价格趋势页** | `pages/trend` | 趋势分析页，提供折线图展示与数据统计 | ✅ 已完成 | [查看文档](./pages/trend/CLAUDE.md) |
| **API 封装** | `utils/request.js` | 统一的 HTTP 请求封装与 API 接口定义 | ✅ 已完成 | 内联文档 |
| **通用工具** | `utils/util.js` | 日期时间格式化等通用工具函数 | ✅ 可用 | [查看文档](./utils/CLAUDE.md) |
| **图表组件** | `components/ec-canvas` | ECharts 图表组件封装 | ✅ 已完成 | [查看文档](./components/ec-canvas/CLAUDE.md) |
| **应用配置** | `app.json` | 小程序全局配置、页面路由、组件注册 | ✅ 已配置 | - |
| **API 文档** | `swagger.json` | 后端 API 接口规范（OpenAPI 3.0） | ✅ 完整 | - |
---
## 运行与开发
### 开发环境要求
- **微信开发者工具**：最新稳定版
- **小程序基础库**：2.10.4 及以上
- **Node.js**：v14+（用于安装依赖）
- **后端 API 服务**：运行在 `http://makepower.top:9333`
### 快速启动
#### 1. 安装依赖
```bash
npm install
```
#### 2. 构建npm
在微信开发者工具中：
- 菜单栏 → 工具 → 构建 npm
- 等待构建完成
#### 3. 配置后端地址
编辑 `utils/request.js` 中的 API 基础地址：
```javascript
const API_BASE_URL = 'http://makepower.top:9333'
```
#### 4. 启动开发
1. 使用微信开发者工具打开项目根目录
2. 确保 AppID 配置正确（`project.config.json`）
3. 点击"编译"按钮预览
4. 在模拟器或真机中测试功能
### 开发配置
#### 项目配置文件
**project.config.json**
```json
{
"appid": "wx26668630c98d7228",
"compileType": "miniprogram",
"libVersion": "trial"
}
```
**app.json** (关键配置)
```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. 日志调试
```javascript
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（价格数据）
```javascript
{
price_region: "昆明",
goods_material: "HPB300",
goods_spec: "Φ8",
hang_price: 3840,
price_date: "2026-01-05",
price_source: "云南钢协"
}
```
#### PriceStats（统计数据）
```javascript
{
count: 150,
avgPrice: 3950.5,
minPrice: 3500,
maxPrice: 4500,
trend: "up",
changeRate: "+2.5%"
}
```
#### TrendData（趋势数据）
```javascript
[
{ 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）
```javascript
const selectedRegion = '昆明'
function onSearch() { }
```
- **常量**：全大写下划线分隔（UPPER_SNAKE_CASE）
```javascript
const API_BASE_URL = 'http://...'
```
#### 3. 注释规范
- **文件头注释**：说明文件用途
- **函数注释**：JSDoc 格式
```javascript
/**
* 搜索价格数据
* @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` 文件：
```javascript
const API_BASE_URL = 'http://your-api-domain.com'
```
### Q2: 如何添加新的地区选项？
**A**: 编辑 `pages/index/index.js` 的 `regions` 数组
### Q3: 图表不显示怎么办？
**A**: 检查以下几点：
1. 确保 ECharts 组件已正确引入
2. 检查 API 返回数据格式
3. 查看控制台错误信息
### Q4: 如何部署到生产环境？
**A**: 步骤如下：
1. 修改 `utils/request.js` 中的 API 地址
2. 微信开发者工具 → 上传代码
3. 微信公众平台 → 提交审核
4. 审核通过后发布上线
---
## 相关资源
### 技术文档
- [微信小程序官方文档](https://developers.weixin.qq.com/miniprogram/dev/framework/)
- [TDesign 小程序组件库](https://tdesign.tencent.com/miniprogram/components/button)
- [ECharts 微信小程序版](https://github.com/ecomfe/echarts-for-weixin)
- [OpenAPI 3.0 规范](https://swagger.io/specification/)
### 开发工具
- **微信开发者工具**：[下载地址](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)
- **代码编辑器**：VS Code（推荐配合微信小程序插件）
- **版本控制**：Git + GitHub/GitLab
---
## 开发路线图
### ✅ 已完成（Phase 1）
- [x] 项目初始化与配置
- [x] 价格查询页面开发
- [x] API 请求封装
- [x] 统计数据展示
- [x] 价格趋势页面开发
- [x] ECharts 图表集成
- [x] TDesign 组件库集成
- [x] TabBar 导航实现
- [x] 表单验证与错误处理
### 🚀 待开发（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
---
**导航**: [价格查询页](./pages/index/CLAUDE.md) | [价格趋势页](./pages/trend/CLAUDE.md) | [工具函数](./utils/CLAUDE.md) | [图表组件](./components/ec-canvas/CLAUDE.md)