Suzhou-SafetyToolsWarning-WX/PROJECT_GUIDE.md

# 安全工器具预警小程序 - 项目说明

## 📋 项目概述

这是一个基于微信小程序原生开发的**安全工器具预警管理系统**，主要用于施工过程中使用的安全工器具的管理、维保和预警。

### 核心功能
- ✅ 设备台账管理（查看、添加、编辑、删除）
- ✅ 多维度筛选和搜索
- ✅ 检测预警和提醒
- ✅ 统计分析
- ✅ 个人中心

## 🏗️ 技术栈

- **框架**：微信小程序原生开发
- **UI组件库**：TDesign Miniprogram
- **开发语言**：JavaScript + WXML + WXSS
- **基础库版本**：3.6.3

## 📁 项目结构

```
miniprogram-1/
├── app.js                          # 小程序入口
├── app.json                        # 全局配置
├── app.wxss                        # 全局样式
├── project.config.json             # 项目配置
│
├── pages/                          # 页面目录
│   ├── index/                      # 首页（工作台）
│   │   ├── index.wxml             # 页面结构
│   │   ├── index.js               # 页面逻辑
│   │   ├── index.wxss             # 页面样式
│   │   └── index.json             # 页面配置
│   │
│   ├── device/                     # 设备管理模块
│   │   ├── list/                  # 设备列表
│   │   ├── detail/                # 设备详情
│   │   └── add/                   # 添加/编辑设备
│   │
│   ├── statistics/                 # 统计分析模块
│   │   └── index/                 # 统计首页
│   │
│   ├── warning/                    # 预警中心模块
│   │   ├── list/                  # 预警列表
│   │   └── settings/              # 预警设置
│   │
│   └── profile/                    # 个人中心模块
│       └── index/                 # 个人中心首页
│
├── components/                     # 自定义组件
├── utils/                          # 工具函数
├── assets/                         # 静态资源
└── miniprogram_npm/               # npm包（TDesign组件库）
```

## 🎯 功能模块详解

### 1. 首页（工作台）
**路径**：`pages/index/index`

**功能**：
- 设备总览统计（总数、预警数、到期数）
- 预警提醒列表（显示前3条）
- 快捷入口（设备台账、添加设备、统计分析、扫码查询）
- 最近操作记录

**数据结构**：
```javascript
{
  totalDevices: 156,        // 设备总数
  warningDevices: 12,       // 预警设备数
  expiredDevices: 3,        // 已到期设备数
  warningList: [...],       // 预警列表
  recentList: [...]         // 最近操作
}
```

### 2. 设备台账
**路径**：`pages/device/list/list`

**功能**：
- 设备列表展示
- 搜索功能（设备名称、编号、型号）
- 状态筛选（全部、正常、预警、已到期）
- 高级筛选（设备类型、使用单位）
- 跳转到设备详情

**数据结构**：
```javascript
{
  id: "设备ID",
  deviceName: "设备名称",
  deviceCode: "设备编号",
  deviceType: "设备类型",
  specification: "规格型号",
  useUnit: "使用单位",
  belongUnit: "所属单位",
  lastInspectionDate: "上次检验日期",
  nextInspectionDate: "下次检验日期",
  status: "设备状态（normal/warning/expired）",
  daysLeft: 7  // 距离到期天数
}
```

### 3. 设备详情
**路径**：`pages/device/detail/detail`

**功能**：
- 查看设备完整信息
- 编辑设备
- 删除设备

### 4. 添加/编辑设备
**路径**：`pages/device/add/add`

**功能**：
- 添加新设备
- 编辑现有设备
- 表单验证
- 日期选择器
- 下拉选择器

**必填字段**：
- 设备名称
- 设备编号
- 使用单位
- 上次检验日期
- 下次检验日期

### 5. 统计分析
**路径**：`pages/statistics/index/index`

**功能**：
- 设备总览统计
- 预警率统计
- 设备类型分布（图表 - 待开发）
- 单位设备统计（图表 - 待开发）

### 6. 预警中心
**路径**：`pages/warning/list/list`

**功能**：
- 预警列表展示
- 按时间筛选（全部、7天内、15天内、已到期）
- 预警等级标识
- 跳转到设备详情

### 7. 预警设置
**路径**：`pages/warning/settings/settings`

**功能**：
- 设置提前预警天数
- 消息推送设置（待开发）

### 8. 个人中心
**路径**：`pages/profile/index/index`

**功能**：
- 用户信息展示
- 单位管理（待开发）
- 预警设置
- 数据导出（待开发）
- 关于我们
- 帮助中心（待开发）

## 🚀 快速开始

### 1. 环境准备
- 安装微信开发者工具
- Node.js 环境（用于 npm 包管理）

### 2. 安装依赖
```bash
# 在微信开发者工具中点击"工具" -> "构建 npm"
# 或者在命令行执行
npm install
```

### 3. 运行项目
1. 使用微信开发者工具打开项目目录
2. 点击"编译"按钮
3. 在模拟器或真机中预览

### 4. TabBar 图标配置（可选）

当前项目使用纯文字 TabBar。如需添加图标：

1. 准备图标文件（81px * 81px，PNG格式）
2. 将图标放入 `assets/icons/` 目录
3. 在 `app.json` 中配置图标路径：

```json
{
  "pagePath": "pages/index/index",
  "text": "首页",
  "iconPath": "assets/icons/home.png",
  "selectedIconPath": "assets/icons/home-active.png"
}
```

所需图标：
- home.png / home-active.png
- device.png / device-active.png
- chart.png / chart-active.png
- warning.png / warning-active.png
- user.png / user-active.png

## 📊 数据管理

### 当前状态
项目目前使用**模拟数据（Mock Data）**，所有数据都在页面的 JS 文件中硬编码。

### 后续开发建议

#### 方案一：微信云开发（推荐）
```javascript
// 初始化云开发
wx.cloud.init({
  env: 'your-env-id'
});

// 查询设备列表
const db = wx.cloud.database();
db.collection('devices').get({
  success: res => {
    console.log(res.data);
  }
});
```

#### 方案二：本地存储
```javascript
// 保存数据
wx.setStorageSync('devices', deviceList);

// 读取数据
const devices = wx.getStorageSync('devices');
```

#### 方案三：后端API
```javascript
// 请求后端接口
wx.request({
  url: 'https://your-api.com/devices',
  method: 'GET',
  success: res => {
    console.log(res.data);
  }
});
```

## 🔧 待开发功能

### 高优先级
- [ ] 数据持久化（云开发或后端API）
- [ ] 用户登录和权限管理
- [ ] 消息推送（订阅消息）
- [ ] 扫码功能完善（生成设备二维码）

### 中优先级
- [ ] 统计图表（使用 echarts-for-weixin）
- [ ] 数据导出（Excel）
- [ ] 批量导入设备
- [ ] 设备照片上传

### 低优先级
- [ ] 单位管理
- [ ] 操作日志
- [ ] 帮助文档
- [ ] 深色模式优化

## 🎨 UI组件使用

项目使用 TDesign Miniprogram 组件库，已在 `app.json` 中全局注册常用组件：

```javascript
// 已注册的组件
t-button        // 按钮
t-icon          // 图标
t-cell          // 单元格
t-cell-group    // 单元格组
t-tag           // 标签
t-badge         // 徽章
t-search        // 搜索框
t-tabs          // 标签页
t-tab-panel     // 标签页面板
t-empty         // 空状态
t-loading       // 加载
t-dialog        // 对话框
t-message       // 消息
t-toast         // 轻提示
t-input         // 输入框
t-picker        // 选择器
t-date-time-picker  // 日期时间选择器
```

更多组件请参考：[TDesign 小程序文档](https://tdesign.tencent.com/miniprogram/overview)

## 📝 开发规范

### 命名规范
- 页面文件：小写字母，使用连字符（如：`device-list`）
- 变量命名：驼峰命名法（如：`deviceList`）
- 常量命名：大写字母+下划线（如：`MAX_COUNT`）

### 代码注释
```javascript
// 单行注释

/**
 * 多行注释
 * @param {string} id - 设备ID
 * @returns {Object} 设备信息
 */
```

### 样式规范
- 使用 rpx 作为尺寸单位（响应式）
- 颜色使用变量（参考 `app.wxss`）
- 避免使用 !important

## 🐛 常见问题

### 1. 编译报错：找不到 TDesign 组件
**解决方案**：点击"工具" -> "构建 npm"

### 2. TabBar 不显示
**原因**：图标文件不存在
**解决方案**：参考上文"TabBar 图标配置"

### 3. 页面跳转失败
**检查**：
- 页面路径是否正确
- 是否在 `app.json` 中注册
- TabBar 页面使用 `wx.switchTab`，非 TabBar 页面使用 `wx.navigateTo`

## 📞 联系方式

如有问题，请联系开发团队。

---

**版本**：v1.0.0  
**最后更新**：2024-05-27