modify：优化

2026-01-07 10:13:21 +08:00
parent da4a055c1c
commit 60b5aba7f8
10 changed files with 3148 additions and 280 deletions
--- a/Sale/CLAUDE.md
+++ b/Sale/CLAUDE.md
@@ -1,41 +1,109 @@
 # SaleInfo - 钢材价格查询小程序

-> 最后更新：2026-01-06 15:26:54
+> **项目状态**: 🚀 已完成（功能完整，可投入使用）
+>
+> **最后更新**: 2026-01-07 09:16:32

 ---

 ## 变更记录 (Changelog)

+### 2026-01-07 09:16:32
+- 重新生成完整的 AI 上下文文档
+- 补充项目架构分析
+- 更新模块索引与依赖关系
+- 添加 Mermaid 结构图
+- 补充测试策略与编码规范
+
 ### 2026-01-06
- 初始化项目 AI 上下文文档
- 完成全仓扫描与模块识别
- 生成架构文档与模块索引
+- 完成价格查询功能开发
+- 新增价格趋势图表页面
+- 集成 TDesign 组件库
+- 集成 ECharts 图表库
+- 实现 TabBar 导航
+- 添加品名筛选功能

 ---

 ## 项目愿景

-**SaleInfo** 是一个专注于钢材价格查询的微信小程序，旨在为用户提供简洁、快速的钢材价格查询服务。通过集成后端 API，用户可以按地区、材质、规格等多维度查询实时钢材价格数据。
+**SaleInfo** 是一个专注于钢材价格查询的微信小程序，为用户提供简洁、快速、专业的钢材价格查询与趋势分析服务。

-### 核心功能
- 多维度价格查询（地区、材质、规格、日期）
- 价格趋势分析与统计
- 数据可视化展示
- 简洁易用的用户界面
+### 核心价值
+
+- **实时价格查询**：支持多维度查询（地区、材质、规格、日期）
+- **趋势可视化**：折线图展示价格走势，直观了解市场动态
+- **数据统计分析**：自动计算均价、最高价、最低价、涨跌幅
+- **简洁专业界面**：基于 TDesign 的现代化 UI 设计
+- **快速响应**：优化的 API 调用与数据处理
+
+### 目标用户
+
+- 钢材采购人员
+- 建筑行业从业者
+- 钢材经销商
+- 市场分析师

 ---

 ## 架构总览

 ### 技术栈
- **前端框架**：微信小程序原生框架
- **组件框架**：glass-easel
- **后端 API**：RESTful API（基于 Node.js + Express）
- **数据格式**：JSON
- **文档规范**：OpenAPI 3.0

-### 项目类型
-微信小程序（Miniprogram）- 前端应用
+#### 前端技术
+- **小程序框架**：微信小程序原生框架（基础库 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 数据库)                          │
+└─────────────────────────────────────────────────────────────┘
+```

 ---

@@ -43,180 +111,440 @@

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

-    B --> E["index - 主页"];
-    B --> F["logs - 日志页"];
+    Pages --> Index["index/<br/>🔍 价格查询页"]
+    Pages --> Trend["trend/<br/>📈 价格趋势页"]

-    C --> G["util.js - 工具函数"];
+    Utils --> Util["util.js<br/>通用工具"]
+    Utils --> Request["request.js<br/>API 封装"]

-    D --> H["app.json - 应用配置"];
-    D --> I["project.config.json - 项目配置"];
-    D --> J["swagger.json - API文档"];
+    Components --> EcCanvas["ec-canvas/<br/>📊 ECharts 图表组件"]

-    click E "#pages-index" "查看 index 页面文档"
-    click F "#pages-logs" "查看 logs 页面文档"
-    click G "#utils" "查看 utils 模块文档"
+    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/logs` | 页面 | 日志记录页面 | 模板代码，可保留 |
-| `utils` | 工具库 | 通用工具函数（日期格式化等） | 可用 |
-| `app.js` | 入口 | 小程序应用入口，全局配置 | 需扩展 |
-| `swagger.json` | 文档 | 后端 API 接口规范（OpenAPI 3.0） | 完整，可直接使用 |
+| 模块名 | 路径 | 职责 | 状态 | 文档 |
+|--------|------|------|------|------|
+| **价格查询页** | `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 及以上
- 后端 API 服务运行在 `http://localhost:3000`

-### 启动步骤
+- **微信开发者工具**：最新稳定版
+- **小程序基础库**：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. 确保后端 API 服务已启动
-3. 点击"编译"按钮即可在模拟器中预览
+2. 确保 AppID 配置正确（`project.config.json`）
+3. 点击"编译"按钮预览
+4. 在模拟器或真机中测试功能

-### 配置说明
- **AppID**：`wxc9bdf24e598789b8`（测试号）
- **服务器域名**：需在微信公众平台配置合法域名
- **API 基础路径**：`http://localhost:3000/api`（开发环境）
+### 开发配置
+
+#### 项目配置文件
+
+**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://localhost:3000`
-  - 生产：`https://api.steel-prices.com`
+- **Base URL**：`http://makepower.top:9333`

-### 主要接口
+### 主要接口列表

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

 ### 数据模型
-详见 `swagger.json` 文件，包含以下核心模型：
- `Price`：钢材价格数据模型
- `PriceStats`：价格统计数据
- `TrendData`：趋势数据
- `Pagination`：分页信息
+
+#### 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` 文件。

 ---

 ## 测试策略

 ### 测试覆盖范围
- **单元测试**：暂无（待补充）
- **集成测试**：暂无（待补充）
- **手动测试**：使用微信开发者工具进行功能验证

-### 建议的测试工具
- 微信开发者工具自带的调试功能
- Mock 数据用于离线开发测试
+#### 1. 功能测试
+- ✅ 价格查询功能（多条件组合）
+- ✅ 统计数据展示
+- ✅ 趋势图表渲染
+- ✅ 表单验证（必填项、参数格式）
+- ✅ 错误处理（网络异常、数据为空）
+- ✅ 页面导航与 TabBar 切换
+
+#### 2. 兼容性测试
+- iOS 微信客户端
+- Android 微信客户端
+- 不同屏幕尺寸适配
+- 不同微信版本兼容性
+
+#### 3. 性能测试
+- 首屏加载时间
+- API 响应时间
+- 图表渲染性能
+- 大数据量列表滚动
+
+### 测试方法
+
+#### 手动测试流程
+
+**价格查询页测试**
+```
+1. 选择地区（必填）
+2. 可选：选择材质、品名、日期
+3. 点击"查询价格"
+4. 验证：统计数据展示正确
+5. 验证：价格列表数据完整
+6. 点击价格卡片，验证详情弹窗
+7. 点击"重置"，验证表单清空
+```
+
+**价格趋势页测试**
+```
+1. 可选：选择地区、材质、时间范围
+2. 点击"查询趋势"
+3. 验证：折线图正常渲染
+4. 验证：统计数据显示正确
+5. 点击"重置"，验证图表清空
+```
+
+#### 自动化测试（建议）
+
+目前项目暂无自动化测试，建议补充：
+- **单元测试**：使用 Jest 测试工具函数
+- **集成测试**：使用微信开发者工具的自动化测试
+- **E2E 测试**：使用 Appium 或微信自动化 SDK

 ---

 ## 编码规范

-### JavaScript/TypeScript 规范
+### JavaScript 规范
+
+#### 1. 代码风格
 - 使用 ES6+ 语法
 - 采用 2 空格缩进
- 变量命名采用驼峰命名法（camelCase）
- 常量命名采用全大写下划线分隔（UPPER_SNAKE_CASE）
+- 使用单引号（字符串）
+- 每行代码不超过 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 规范
- 使用 rpx 单位适配不同屏幕
- 避免深层嵌套（不超过 3 层）
- 使用 Flex 布局进行页面排版

-### 小程序最佳实践
- 合理使用 `setData`，避免频繁更新
- 图片资源使用 CDN 加速
- 网络请求添加错误处理与加载提示
+#### 1. WXML 结构
+- 使用 rpx 单位（响应式像素）
+- 避免深层嵌套（不超过 3 层）
+- 使用语义化的类名
+
+#### 2. WXSS 样式
+- 遵循 BEM 命名规范
+- 使用 Flex 布局
+- 避免使用 ID 选择器

 ---

 ## AI 使用指引

-### 推荐的 AI 辅助开发场景
-1. **UI 设计**：生成简洁的页面布局代码
-2. **API 调用**：基于 `swagger.json` 生成接口调用代码
-3. **数据可视化**：实现价格趋势图表展示
-4. **错误处理**：添加网络异常与数据校验逻辑
+### 给 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/util.js`：通用工具函数，可扩展 API 请求封装

-### 开发建议
-1. 优先实现价格查询核心功能
-2. UI 设计应简洁大方，突出数据展示
-3. 添加加载状态与错误提示
-4. 考虑添加数据缓存机制
+| 文件 | 说明 | 用途 |
+|------|------|------|
+| `swagger.json` | 完整的后端 API 定义 | 所有接口调用参考此文档 |
+| `app.json` | 小程序全局配置 | 页面路由、组件注册 |
+| `utils/request.js` | API 请求封装 | 统一的网络请求处理 |
+| `pages/index/index.js` | 价格查询页逻辑 | 主要业务逻辑实现 |
+| `pages/trend/trend.js` | 趋势分析页逻辑 | 图表数据处理 |

 ---

 ## 常见问题 (FAQ)

-### Q: 如何调试网络请求？
-A: 在微信开发者工具中，打开"调试器" -> "Network" 面板，可查看所有网络请求详情。
+### Q1: 如何修改 API 基础地址？

-### Q: 如何处理跨域问题？
-A: 微信小程序不存在跨域问题，但需在微信公众平台配置合法域名。
+**A**: 编辑 `utils/request.js` 文件：

-### 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)
-  }
-})
+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/)
- 项目 README：查看 `README.md` 文件
+
+### 开发工具
+
+- **微信开发者工具**：[下载地址](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)
+- **代码编辑器**：VS Code（推荐配合微信小程序插件）
+- **版本控制**：Git + GitHub/GitLab

 ---

-**文档生成时间**：2026-01-06 15:26:54
-**扫描覆盖率**：100% (18/18 文件)
-**项目规模**：小型（单模块微信小程序）
+## 开发路线图
+
+### ✅ 已完成（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)