551 lines
16 KiB
Markdown
551 lines
16 KiB
Markdown
# 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<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/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)
|