# 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 文件)
**项目规模**：小型（单模块微信小程序）