223 lines
6.0 KiB
Markdown
223 lines
6.0 KiB
Markdown
# SaleInfo - 钢材价格查询小程序
|
||
|
||
> 最后更新：2026-01-06 15:26:54
|
||
|
||
---
|
||
|
||
## 变更记录 (Changelog)
|
||
|
||
### 2026-01-06
|
||
- 初始化项目 AI 上下文文档
|
||
- 完成全仓扫描与模块识别
|
||
- 生成架构文档与模块索引
|
||
|
||
---
|
||
|
||
## 项目愿景
|
||
|
||
**SaleInfo** 是一个专注于钢材价格查询的微信小程序，旨在为用户提供简洁、快速的钢材价格查询服务。通过集成后端 API，用户可以按地区、材质、规格等多维度查询实时钢材价格数据。
|
||
|
||
### 核心功能
|
||
- 多维度价格查询（地区、材质、规格、日期）
|
||
- 价格趋势分析与统计
|
||
- 数据可视化展示
|
||
- 简洁易用的用户界面
|
||
|
||
---
|
||
|
||
## 架构总览
|
||
|
||
### 技术栈
|
||
- **前端框架**：微信小程序原生框架
|
||
- **组件框架**：glass-easel
|
||
- **后端 API**：RESTful API（基于 Node.js + Express）
|
||
- **数据格式**：JSON
|
||
- **文档规范**：OpenAPI 3.0
|
||
|
||
### 项目类型
|
||
微信小程序（Miniprogram）- 前端应用
|
||
|
||
---
|
||
|
||
## 模块结构图
|
||
|
||
```mermaid
|
||
graph TD
|
||
A["(根) SaleInfo"] --> B["pages"];
|
||
A --> C["utils"];
|
||
A --> D["配置文件"];
|
||
|
||
B --> E["index - 主页"];
|
||
B --> F["logs - 日志页"];
|
||
|
||
C --> G["util.js - 工具函数"];
|
||
|
||
D --> H["app.json - 应用配置"];
|
||
D --> I["project.config.json - 项目配置"];
|
||
D --> J["swagger.json - API文档"];
|
||
|
||
click E "#pages-index" "查看 index 页面文档"
|
||
click F "#pages-logs" "查看 logs 页面文档"
|
||
click G "#utils" "查看 utils 模块文档"
|
||
```
|
||
|
||
---
|
||
|
||
## 模块索引
|
||
|
||
| 模块路径 | 类型 | 职责 | 状态 |
|
||
|---------|------|------|------|
|
||
| `pages/index` | 页面 | 主页，展示用户信息与价格查询入口 | 模板代码，需改造 |
|
||
| `pages/logs` | 页面 | 日志记录页面 | 模板代码，可保留 |
|
||
| `utils` | 工具库 | 通用工具函数（日期格式化等） | 可用 |
|
||
| `app.js` | 入口 | 小程序应用入口，全局配置 | 需扩展 |
|
||
| `swagger.json` | 文档 | 后端 API 接口规范（OpenAPI 3.0） | 完整，可直接使用 |
|
||
|
||
---
|
||
|
||
## 运行与开发
|
||
|
||
### 开发环境要求
|
||
- 微信开发者工具（最新版本）
|
||
- 小程序基础库 2.10.4 及以上
|
||
- 后端 API 服务运行在 `http://localhost:3000`
|
||
|
||
### 启动步骤
|
||
1. 使用微信开发者工具打开项目根目录
|
||
2. 确保后端 API 服务已启动
|
||
3. 点击"编译"按钮即可在模拟器中预览
|
||
|
||
### 配置说明
|
||
- **AppID**：`wxc9bdf24e598789b8`（测试号）
|
||
- **服务器域名**：需在微信公众平台配置合法域名
|
||
- **API 基础路径**：`http://localhost:3000/api`（开发环境）
|
||
|
||
---
|
||
|
||
## 后端 API 规范
|
||
|
||
### API 基础信息
|
||
- **文档版本**：1.0.0
|
||
- **协议**：OpenAPI 3.0
|
||
- **Base URL**：
|
||
- 开发：`http://localhost:3000`
|
||
- 生产：`https://api.steel-prices.com`
|
||
|
||
### 主要接口
|
||
|
||
#### 1. 健康检查
|
||
- **端点**：`GET /api/health`
|
||
- **说明**：检查服务是否正常运行
|
||
|
||
#### 2. 价格查询
|
||
- **按地区查询**：`GET /api/prices/region?region={region}&date={date}`
|
||
- **搜索价格**：`GET /api/prices/search?material={material}&page={page}`
|
||
- **获取统计**：`GET /api/prices/stats?region={region}&days={days}`
|
||
- **获取趋势**：`GET /api/prices/trend?region={region}&days={days}`
|
||
|
||
#### 3. 数据管理
|
||
- **导入数据**：`POST /api/prices/import`
|
||
|
||
### 数据模型
|
||
详见 `swagger.json` 文件，包含以下核心模型：
|
||
- `Price`：钢材价格数据模型
|
||
- `PriceStats`：价格统计数据
|
||
- `TrendData`：趋势数据
|
||
- `Pagination`：分页信息
|
||
|
||
---
|
||
|
||
## 测试策略
|
||
|
||
### 测试覆盖范围
|
||
- **单元测试**：暂无（待补充）
|
||
- **集成测试**：暂无（待补充）
|
||
- **手动测试**：使用微信开发者工具进行功能验证
|
||
|
||
### 建议的测试工具
|
||
- 微信开发者工具自带的调试功能
|
||
- Mock 数据用于离线开发测试
|
||
|
||
---
|
||
|
||
## 编码规范
|
||
|
||
### JavaScript/TypeScript 规范
|
||
- 使用 ES6+ 语法
|
||
- 采用 2 空格缩进
|
||
- 变量命名采用驼峰命名法（camelCase）
|
||
- 常量命名采用全大写下划线分隔（UPPER_SNAKE_CASE）
|
||
|
||
### WXML/WXSS 规范
|
||
- 使用 rpx 单位适配不同屏幕
|
||
- 避免深层嵌套（不超过 3 层）
|
||
- 使用 Flex 布局进行页面排版
|
||
|
||
### 小程序最佳实践
|
||
- 合理使用 `setData`，避免频繁更新
|
||
- 图片资源使用 CDN 加速
|
||
- 网络请求添加错误处理与加载提示
|
||
|
||
---
|
||
|
||
## AI 使用指引
|
||
|
||
### 推荐的 AI 辅助开发场景
|
||
1. **UI 设计**：生成简洁的页面布局代码
|
||
2. **API 调用**：基于 `swagger.json` 生成接口调用代码
|
||
3. **数据可视化**：实现价格趋势图表展示
|
||
4. **错误处理**：添加网络异常与数据校验逻辑
|
||
|
||
### 关键文件说明
|
||
- `swagger.json`：包含完整的后端 API 定义，所有接口调用应参考此文档
|
||
- `app.json`：页面路由注册位置，新增页面需在此配置
|
||
- `utils/util.js`：通用工具函数，可扩展 API 请求封装
|
||
|
||
### 开发建议
|
||
1. 优先实现价格查询核心功能
|
||
2. UI 设计应简洁大方，突出数据展示
|
||
3. 添加加载状态与错误提示
|
||
4. 考虑添加数据缓存机制
|
||
|
||
---
|
||
|
||
## 常见问题 (FAQ)
|
||
|
||
### Q: 如何调试网络请求？
|
||
A: 在微信开发者工具中，打开"调试器" -> "Network" 面板，可查看所有网络请求详情。
|
||
|
||
### Q: 如何处理跨域问题？
|
||
A: 微信小程序不存在跨域问题，但需在微信公众平台配置合法域名。
|
||
|
||
### Q: 如何添加新页面？
|
||
A:
|
||
1. 在 `pages` 目录下创建新页面文件夹
|
||
2. 创建页面文件（.js, .wxml, .wxss, .json）
|
||
3. 在 `app.json` 的 `pages` 数组中注册页面路径
|
||
|
||
### Q: 后端 API 如何调用？
|
||
A: 使用 `wx.request()` 方法，示例：
|
||
```javascript
|
||
wx.request({
|
||
url: 'http://localhost:3000/api/prices/region?region=昆明',
|
||
method: 'GET',
|
||
success: (res) => {
|
||
console.log(res.data)
|
||
}
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## 相关资源
|
||
|
||
- [微信小程序官方文档](https://developers.weixin.qq.com/miniprogram/dev/framework/)
|
||
- [OpenAPI 3.0 规范](https://swagger.io/specification/)
|
||
- 项目 README：查看 `README.md` 文件
|
||
|
||
---
|
||
|
||
**文档生成时间**：2026-01-06 15:26:54
|
||
**扫描覆盖率**：100% (18/18 文件)
|
||
**项目规模**：小型（单模块微信小程序）
|