# CodeWhisper

**Repository Path**: jerryzu/code-whisper

## Basic Information

- **Project Name**: CodeWhisper
- **Description**: 一个基于 QR 码的设备数据采集系统，一个AI的实验场
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-26
- **Last Updated**: 2026-03-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CodeWhisper

<div align="center">

![CodeWhisper Logo](docs/assets/logo.png)

**一个基于 QR 码的设备数据采集系统**

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Android](https://img.shields.io/badge/platform-Android-green.svg)](https://android.com/)
[![HarmonyOS](https://img.shields.io/badge/platform-HarmonyOS-red.svg)](https://developer.huawei.com/consumer/cn/harmonyos/)
[![WeChat](https://img.shields.io/badge/platform-微信小程序-brightgreen.svg)](https://developers.weixin.qq.com/miniprogram/dev/framework/)
[![Vue](https://img.shields.io/badge/platform-Web%20Client-4FC08D.svg)](https://vuejs.org/)
[![Node.js](https://img.shields.io/badge/node-20.x-brightgreen.svg)](https://nodejs.org/)
[![SQLite](https://img.shields.io/badge/database-SQLITE-orange.svg)](https://www.sqlite.org/)

[功能特性](#功能特性) • [快速开始](#快速开始) • [API 文档](#api-文档) • [开发指南](#开发指南) • [相关文档](#-相关文档)

</div>

---

## 📱 项目简介

CodeWhisper 是一个跨平台设备数据采集解决方案，通过扫描设备二维码快速收集设备信息，并支持批量上传到云端进行统一管理。系统包含：

- **Android 客户端** (Kotlin + Jetpack Compose)
- **HarmonyOS 客户端** (ArkTS + ArkUI)
- **微信小程序** (JavaScript + WXML/WXSS)
- **Web 管理后台** (Vue 3 + TypeScript + Ant Design Vue)
- **Node.js 后端服务** (Express.js + SQLite)

### 主要功能

- 📷 **QR 码扫描** - 快速采集设备信息
- 📤 **批量上传** - 支持批量上传设备数据
- 🔐 **用户认证** - JWT 认证与密码哈希保护
- 🔄 **密码重置** - 支持验证码重置密码
- 📊 **数据统计** - 设备状态统计与分析
- 🔒 **HTTPS 支持** - 自签名证书加密传输

---

## 📊 版本演进

### 分支说明

| 分支 | 状态 | 用途 |
|------|------|------|
| **master** | 🟢 活跃开发 | 新功能开发与演进 |
| **v1** | 🔵 维护模式 | 基础版本（仅修复 bug） |
| **v2** | 🔵 维护模式 | 设备属性版本（仅修复 bug） |
| **v3** | 🔵 维护模式 | Web 管理后台版本（仅修复 bug） |

### 版本对比表

| 功能 | v1 | v2 | v3 |
|------|----|----|----|
| Android 客户端 | ✅ | ✅ | ✅ |
| HarmonyOS 客户端 | ✅ | ✅ | ✅ |
| 微信小程序 | ✅ | ✅ | ✅ |
| 后端 API | ✅ | ✅ | ✅ |
| 设备属性（条码/位置/照片） | - | ✅ | ✅ |
| 照片同步 | - | ✅ | ✅ |
| 照片下载 | - | - | ✅ |
| 编辑冲突处理 | - | - | ✅ |
| Web 管理后台 | - | - | ✅ |
| 审计日志 | - | - | ✅ |
| 分页查询 | - | - | ✅ |

### 版本功能详情

#### v1 基线
核心功能已完成：
- Android 客户端（扫码、设备管理）
- 微信小程序（扫码、设备管理、服务器同步）
- HarmonyOS NEXT 客户端
- Node.js 后端（REST API、SQLite）

#### v2 新增功能（相对 v1）
- **设备属性扩展** - 条形码、位置、照片字段
- **照片同步** - 设备照片永久存储和关联
- **扫码优化** - 修复 Android 条形码扫描和权限处理

#### v3 新增功能（相对 v2）
- **Web 管理后台** - 完整的 Web 端设备/用户管理界面
- **审计日志** - 操作审计功能
- **分页功能** - 设备和用户管理的分页查询
- **照片下载** - 支持从服务器下载照片到本地
- **冲突处理** - 设备编辑冲突解决机制
- **架构优化** - Android 客户端重构，删除冗余层

---

## ✨ 功能特性

### 多端客户端

| 功能 | Android | HarmonyOS | 微信小程序 | Web 管理后台 |
|------|---------|-----------|------------|----------------|
| QR 码扫描 | ✅ CameraX | ✅ scanBarcode | ✅ wx.scanCode | ❌ |
| 设备管理 | ✅ | ✅ | ✅ | ✅ |
| 批量上传 | ✅ | ✅ | ✅ | ❌ |
| 状态追踪 | ✅ | ✅ | ✅ | ✅ |
| 用户认证 | ✅ 用户名密码 | ✅ 用户名密码 | ✅ 微信登录 + 账号绑定 | ✅ 用户名密码 |
| 离线缓存 | ✅ Room DB | ✅ Preferences | ✅ wx.Storage | ❌ |
| 设备同步 | ✅ 后台同步 | ✅ 后台同步 | ✅ 手动同步 | - |
| 服务器配置 | ✅ 扫码配置 | ✅ 扫码配置 | ✅ 扫码配置 | - |
| 用户管理 | ❌ | ❌ | ❌ | ✅（管理员） |
| 审计日志 | ❌ | ❌ | ❌ | ✅（管理员） |
| 数据统计 | ✅ | ✅ | ✅ | ✅ 图表展示 |

### Android / HarmonyOS 客户端

| 功能 | 说明 |
|------|------|
| QR 码扫描 | 使用相机扫描设备二维码，自动解析设备信息 |
| 设备管理 | 查看、编辑、删除本地设备，支持后台同步到服务器 |
| 批量上传 | 一键上传多个设备到服务器 |
| 状态追踪 | 实时显示设备上传状态（待上传/已上传/失败） |
| 用户认证 | 登录、注册、密码重置功能 |
| 网络配置 | 支持扫码配置服务器地址 |

### 微信小程序

| 功能 | 说明 |
|------|------|
| 微信登录 | 微信一键登录，首次使用需绑定系统账号 |
| QR 码扫描 | 支持设备码和服务器地址双模式扫码 |
| 设备管理 | 查看、编辑、删除本地设备 |
| 批量上传 | 一键上传多个设备到服务器 |
| 状态追踪 | 实时显示设备上传状态 |
| 设备同步 | 支持从服务器拉取设备数据并合并到本地 |
| 服务器配置 | 支持扫码配置服务器地址 |

### Web 管理后台

| 功能 | 说明 |
|------|------|
| 仪表板 | 设备统计卡片、状态分布饼图、最近设备列表 |
| 设备管理 | 设备列表（分页搜索）、设备详情查看 |
| 用户管理 | 用户列表（分页）、用户详情、角色管理（仅管理员） |
| 审计日志 | 操作日志查询、时间范围筛选（仅管理员） |
| 个人资料 | 用户信息查看、密码修改 |
| 数据可视化 | ECharts 图表展示设备状态分布 |

### 后端服务

| 功能 | 说明 |
|------|------|
| RESTful API | 标准的 REST API 接口 |
| JWT 认证 | 安全的令牌认证机制 |
| 微信登录 | 支持微信小程序登录和账号绑定 |
| 数据存储 | SQLite 轻量级数据库 |
| HTTPS 支持 | 自签名证书加密传输 |
| 密码重置 | 6 位数字验证码重置流程 |
| 设备统计 | 按状态、客户端统计设备数量 |
| 二维码生成 | 提供服务器地址二维码供客户端扫码配置 |

---

## 🛠 技术栈

### Android 客户端

- **语言**: Kotlin
- **架构**: MVVM + Repository Pattern
- **UI**: Jetpack Compose
- **依赖注入**: Hilt
- **网络**: Retrofit2 + OkHttp
- **数据库**: Room
- **导航**: Jetpack Navigation Compose
- **异步**: Coroutines + Flow

### HarmonyOS 客户端

- **语言**: ArkTS
- **架构**: MVVM
- **UI**: ArkUI 声明式 UI
- **网络**: @ohos.net.http
- **存储**: @ohos.data.preferences
- **扫码**: @ohos.scan.scanBarcode
- **最低版本**: HarmonyOS NEXT (API 5.0+)

### 微信小程序

- **框架**: 微信小程序原生
- **语言**: JavaScript/TypeScript
- **UI**: WXML + WXSS
- **网络**: wx.request 封装
- **存储**: wx.Storage
- **扫码**: wx.scanCode

### Web 管理后台

- **框架**: Vue 3
- **语言**: TypeScript
- **构建工具**: Vite
- **UI 组件库**: Ant Design Vue
- **状态管理**: Pinia
- **路由**: Vue Router
- **HTTP 客户端**: Axios
- **图表**: ECharts
- **密码加密**: Crypto-JS

### 后端服务

- **运行时**: Node.js 20.x
- **框架**: Express.js
- **数据库**: SQLite3
- **认证**: JWT (jsonwebtoken)
- **安全**: SHA-256 密码哈希
- **部署**: Docker + Docker Compose

---

## 🚀 快速开始

### 环境要求

| 组件 | 要求 |
|------|------|
| **Node.js** | >= 18.0.0 |
| **Android Studio** | Hedgehog | 2023.1.1 或更高版本 |
| **DevEco Studio** | 5.0.0 或更高版本（HarmonyOS 开发） |
| **微信开发者工具** | 最新稳定版 |
| **现代浏览器** | Chrome/Edge/Firefox 最新版本 |
| **JDK** | 17 或更高版本 |
| **SDK** | Android API 34+ (目标) |

### 后端服务启动

```bash
# 1. 进入服务端目录
cd server

# 2. 安装依赖
npm install

# 3. 配置环境变量
cp .env.example .env

# 4. 启动服务（开发模式）
npm run dev

# 生产模式
npm start
```

服务将同时监听：
- **HTTP**: http://localhost:3000
- **HTTPS**: https://localhost:3443

### Android 客户端构建

```bash
# 1. 进入 Android 目录
cd android

# 2. 构建调试版本
./gradlew assembleDebug

# 3. 安装到设备
adb install -r app/build/outputs/apk/debug/app-debug.apk
```

### HarmonyOS 客户端构建

```bash
# 1. 使用 DevEco Studio 打开 harmonyos 目录

# 2. 等待依赖自动下载完成

# 3. 连接 HarmonyOS 设备或启动模拟器

# 4. 点击运行按钮或使用快捷键构建安装
```

详细说明请查看 [harmonyos/README.md](harmonyos/README.md)

### 微信小程序开发

```bash
# 1. 进入小程序目录
cd miniprogram

# 2. 安装依赖
npm install

# 3. 构建npm
# 在微信开发者工具中：工具 -> 构建 npm

# 4. 使用微信开发者工具打开 miniprogram 目录

# 5. 在真机上预览或调试
```

详细说明请查看 [docs/miniprogram-development-guide.md](docs/miniprogram-development-guide.md)

### Web 管理后台开发

```bash
# 1. 进入 Web 目录
cd web

# 2. 安装依赖
npm install

# 3. 启动开发服务器
npm run dev

# 4. 构建生产版本
npm run build

# 5. 预览生产构建
npm run preview
```

开发服务器将运行在 http://localhost:5173，API 请求会自动代理到后端服务器。

### 默认账号

```
用户名: admin
密码: admin123
```

⚠️ **重要**: 首次登录后请立即修改默认密码！

---

## 📁 项目结构

```
CodeWhisper/
├── android/                 # Android 客户端
│   ├── app/
│   │   ├── src/main/
│   │   │   ├── java/com/codewhisper/
│   │   │   │   ├── data/        # 数据层
│   │   │   │   ├── ui/          # UI 界面
│   │   │   │   ├── viewmodel/   # ViewModel
│   │   │   │   ├── repository/  # 仓库层
│   │   │   │   └── util/        # 工具类
│   │   │   ├── res/             # 资源文件
│   │   │   └── AndroidManifest.xml
│   │   └── build.gradle.kts
│   └── build.gradle.kts
├── harmonyos/               # HarmonyOS 客户端
│   ├── AppScope/             # 应用全局配置
│   ├── entry/                # 主模块
│   │   └── src/main/ets/
│   │       ├── entryability/  # 应用入口
│   │       ├── pages/         # 页面
│   │       ├── viewmodels/    # ViewModel
│   │       ├── services/      # 业务服务
│   │       ├── api/           # API 接口
│   │       ├── models/        # 数据模型
│   │       ├── utils/         # 工具函数
│   │       └── components/    # UI 组件
│   └── oh-package.json5
├── miniprogram/             # 微信小程序
│   ├── api/                  # API 接口层
│   ├── pages/                # 页面
│   ├── utils/                # 工具函数
│   └── app.js
├── web/                     # Web 管理后台
│   ├── src/
│   │   ├── api/              # API 接口层
│   │   ├── components/       # 公共组件
│   │   ├── layouts/          # 布局组件
│   │   ├── router/           # 路由配置
│   │   ├── stores/           # Pinia 状态管理
│   │   ├── utils/            # 工具函数
│   │   ├── views/            # 页面视图
│   │   │   ├── auth/         # 认证页面
│   │   │   ├── dashboard/    # 仪表板
│   │   │   ├── devices/      # 设备管理
│   │   │   ├── users/        # 用户管理
│   │   │   ├── audit/        # 审计日志
│   │   │   └── profile/      # 个人资料
│   │   ├── App.vue
│   │   └── main.ts
│   ├── index.html
│   ├── vite.config.ts
│   └── package.json
├── server/                  # 后端服务
│   ├── src/
│   │   ├── config/           # 配置文件
│   │   ├── models/           # 数据模型
│   │   ├── routes/           # API 路由
│   │   ├── middleware/       # 中间件
│   │   └── utils/            # 工具函数
│   ├── data/                 # 数据库文件
│   ├── ssl/                  # SSL 证书
│   ├── app.js
│   └── package.json
├── docs/                    # 文档
└── README.md
```

---

## 📡 API 文档

### 认证接口

| 方法 | 端点 | 说明 |
|------|------|------|
| `POST` | `/api/auth/login` | 用户登录（Android/HarmonyOS） |
| `POST` | `/api/auth/register` | 用户注册 |
| `POST` | `/api/auth/wechat-login` | 微信小程序登录 |
| `POST` | `/api/auth/bind-account` | 绑定微信到系统账号 |
| `POST` | `/api/auth/forgot-password` | 请求重置密码 |
| `POST` | `/api/auth/reset-password` | 重置密码 |
| `GET` | `/api/auth/verify` | 验证令牌 |
| `GET` | `/api/auth/me` | 获取当前用户信息 |

### 设备接口

| 方法 | 端点 | 说明 |
|------|------|------|
| `GET` | `/api/devices` | 获取设备列表 |
| `GET` | `/api/devices/stats` | 获取设备统计 |
| `GET` | `/api/devices/:id` | 获取单个设备 |
| `POST` | `/api/devices/batch` | 批量上传设备 |
| `PUT` | `/api/devices/:id` | 更新设备 |
| `DELETE` | `/api/devices/:id` | 删除设备 |

### 二维码接口

| 方法 | 端点 | 说明 |
|------|------|------|
| `GET` | `/api/qrcode` | 获取服务器地址二维码（PNG 图片） |

详细 API 文档请查看 [docs/API.md](docs/API.md)

---

## 🔧 开发指南

### 环境配置

#### 后端

创建 `.env` 文件：

```bash
NODE_ENV=development
PORT=3000
HTTP_PORT=3000
HTTPS_PORT=3443
JWT_SECRET=your-secret-key-here
JWT_EXPIRES_IN=7d
DB_PATH=./data/codewhisper.db
DEFAULT_ADMIN_USERNAME=admin
DEFAULT_ADMIN_PASSWORD=admin123

# 微信小程序配置（可选）
WECHAT_APP_ID=wx1234567890abcdef
WECHAT_APP_SECRET=your_app_secret_here
```

#### Android 客户端

修改 `app/build.gradle.kts` 中的服务器地址：

```kotlin
debug {
    buildConfigField("String", "API_BASE_URL", "\"https://192.168.28.112:3443/\"")
}
```

#### HarmonyOS 客户端

修改 AppScope 资源文件中的服务器地址，或在应用内设置中配置。

#### 微信小程序

修改 `utils/request.ts` 中的 `BASE_URL`，或在应用内设置中配置。

#### Web 管理后台

修改 `vite.config.ts` 中的代理配置：

```typescript
server: {
  proxy: {
    '/api': {
      target: 'https://192.168.28.112:3443',  // 修改为你的服务器地址
      changeOrigin: true,
      secure: false
    }
  }
}
```

生产环境部署时，修改 `src/api/client.ts` 中的 `baseURL`。

### 密码哈希配置

确保客户端和服务器使用相同的盐值：

**服务器** (`server/src/utils/passwordHasher.js`):
```javascript
this.APP_SALT = 'CW_SALT_2026_SECURE_v1';
```

**客户端** (`android/app/src/main/java/com/codewhisper/util/PasswordHasher.kt`):
```kotlin
private const val APP_SALT = "CW_SALT_2026_SECURE_v1"
```

**小程序客户端** (`miniprogram/utils/password.js`):
```javascript
const APP_SALT = 'CW_SALT_2026_SECURE_v1';
```

**Web 管理后台** (`web/src/utils/password.ts`):
```typescript
export const APP_SALT = 'CW_SALT_2026_SECURE_v1';
```

### HTTPS 自签名证书

开发环境使用自签名证书，位置：`server/ssl/`

生成新证书：
```bash
cd server/ssl
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem \
  -days 365 -nodes \
  -subj "/C=CN/ST=Beijing/L=Beijing/O=CodeWhisper/CN=192.168.28.112"
```

---

## 📦 部署

### Docker 部署

```bash
# 构建并启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
```

### 生产环境注意事项

1. **修改默认密码** - 首次登录后立即修改
2. **配置 HTTPS** - 使用正式 SSL 证书
3. **设置强密钥** - 更改 JWT_SECRET
4. **启用防火墙** - 限制数据库访问
5. **定期备份** - 备份数据库文件

---

## 📸 截图

<div align="center">

### Android 客户端
### 主页 | 扫码 | 设备列表
![主页](docs/screenshots/main.png) | ![扫描](docs/screenshots/scan.png) | ![设备列表](docs/screenshots/device-list.png)

### 上传设备
![上传](docs/screenshots/upload.png)

</div>

---

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'feat: add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

---

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

---

## 📮 联系方式

- **仓库地址**: https://gitee.com/jerryzu/code-whisper
- **问题反馈**: [Issues](https://gitee.com/jerryzu/code-whisper/issues)

### 📚 相关文档

- [API 文档](docs/API.md) - 完整的 REST API 接口说明
- [微信小程序开发指南](docs/miniprogram-development-guide.md) - 小程序开发规范
- [微信小程序测试指南](docs/miniprogram-testing-guide.md) - 小程序测试方法
- [API 测试指南](docs/API-Testing-Guide.md) - 后端 API 测试
- [HarmonyOS 客户端](harmonyos/README.md) - HarmonyOS 客户端说明
- [Web 管理后台](web/README.md) - Web 管理后台说明

---

<div align="center">

**⭐ 如果这个项目对你有帮助，请给一个 Star！**

Made with ❤️ by [Jerry](https://gitee.com/jerryzu)

</div>