steel_prices_service/Sale/CLAUDE.md

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）- 前端应用

---

模块结构图

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() 方法，示例：

wx.request({
  url: 'http://localhost:3000/api/prices/region?region=昆明',
  method: 'GET',
  success: (res) => {
    console.log(res.data)
  }
})

---

相关资源

• 微信小程序官方文档
• OpenAPI 3.0 规范
• 项目 README：查看 README.md 文件

---

文档生成时间：2026-01-06 15:26:54 扫描覆盖率：100% (18/18 文件) 项目规模：小型（单模块微信小程序）