# WaterFlow

**Repository Path**: Tooooa/WaterFlow

## Basic Information

- **Project Name**: WaterFlow
- **Description**: 基于WaterFlow容器，实现瀑布流布局。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 9
- **Created**: 2025-12-10
- **Last Updated**: 2026-01-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HMstore 鸿蒙商城应用

> 基于 HarmonyOS ArkUI 开发的电商应用，配套 Node.js 后端服务器  
> 最后更新：2026年1月2日

---

## 📱 项目简介

HMstore 是一款基于鸿蒙系统开发的购物商城应用，采用瀑布流布局展示商品，支持用户注册登录、商品浏览、购物车、订单管理、收藏关注、评论互动、私信聊天等完整电商功能。

### 技术架构

```
┌─────────────────────────────────────────────────────────────┐
│                      HarmonyOS 客户端                        │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
│  │  ArkUI  │  │ ArkTS   │  │ 状态管理 │  │本地存储 │        │
│  │  组件   │  │  逻辑   │  │ @State  │  │Preference│        │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘        │
└───────────────────────┬─────────────────────────────────────┘
                        │ HTTP/JSON
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                      Node.js 服务器                          │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
│  │ Express │  │Sequelize│  │  JWT    │  │  CORS   │        │
│  │  路由   │  │  ORM    │  │  认证   │  │  跨域   │        │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘        │
│                        │                                    │
│                        ▼                                    │
│               ┌─────────────────┐                           │
│               │     SQLite      │                           │
│               │     数据库       │                           │
│               └─────────────────┘                           │
└─────────────────────────────────────────────────────────────┘
```

---

## ✨ 功能特性

### 核心功能

| 功能模块 | 说明 |
|---------|------|
| 🔐 用户系统 | 注册、登录、个人资料管理 |
| 🛍️ 商品浏览 | 瀑布流展示、分类筛选、关键词搜索 |
| 🛒 购物车 | 添加商品、数量调整、批量结算 |
| 📦 订单管理 | 创建订单、订单列表、取消/确认收货 |
| ❤️ 收藏功能 | 收藏商品、收藏列表 |
| 👥 关注系统 | 关注用户、粉丝列表、关注列表 |
| 🎫 优惠券 | 领取优惠券、下单使用 |
| 💬 评论系统 | 发表评论、回复评论、点赞/点踩 |
| 📨 私信聊天 | 一对一聊天、消息列表、未读提醒 |
| 🤖 AI 客服 | 智能对话交互 |

---

## 🚀 快速开始

### 直接运行（推荐）

**应用已配置好云服务器，无需额外配置！**

```
默认服务器地址：http://182.92.87.206:3000
```

1. 用 DevEco Studio 打开 `WaterFlow` 项目
2. 连接设备或启动模拟器
3. 点击运行

> 💡 **说明**：`server/` 文件夹是独立的 Node.js 后端服务器代码，与 HarmonyOS 应用编译完全无关。  
> 直接运行应用时会自动连接云服务器，无需启动本地 server，也无需安装 Node.js。

### 环境要求

| 环境 | 版本要求 | 说明 |
|------|---------|------|
| HarmonyOS | 5.0.5 Release 及以上 | 必需 |
| DevEco Studio | 6.0.0 Release 及以上 | 必需 |
| HarmonyOS SDK | 6.0.0 Release 及以上 | 必需 |
| Node.js | 18.x LTS 及以上 | **仅自建服务器需要** |

---

## 🔧 自建服务器

如果你想在本地或自己的服务器上运行后端，请参考：

📖 **[自建服务器配置教程](自建服务器配置教程.md)**

教程包含：
- Node.js 安装
- 依赖安装（含淘宝镜像）
- 服务器启动
- 客户端 IP 配置
- 云服务器部署（安全组、pm2）
- 常见问题解决

---

## 📁 项目结构

```
WaterFlow/
├── AppScope/                    # 应用全局配置
├── entry/                       # 主模块
│   └── src/main/ets/
│       ├── common/
│       │   ├── bean/            # 数据模型
│       │   │   ├── Comment.ets      # 评论模型
│       │   │   ├── Conversation.ets # 会话模型
│       │   │   └── Message.ets      # 消息模型
│       │   ├── constants/       # 常量配置
│       │   │   ├── CommonConstants.ets
│       │   │   └── ServerConfig.ets # 服务器配置
│       │   ├── network/         # 网络层
│       │   │   └── HttpClient.ets
│       │   └── utils/           # 工具类
│       │       ├── ApiModels.ets    # API数据模型
│       │       ├── ApiService.ets   # API服务封装
│       │       ├── CartManager.ets
│       │       ├── CommentManager.ets
│       │       ├── CouponManager.ets
│       │       ├── FavoritesManager.ets
│       │       ├── FollowManager.ets
│       │       ├── MessageManager.ets
│       │       ├── OrderManager.ets
│       │       └── UserManager.ets
│       ├── pages/               # 页面
│       │   ├── MainPage.ets         # 主页（Tab容器）
│       │   ├── HomePage.ets         # 首页（商品瀑布流）
│       │   ├── ProductDetailPage.ets# 商品详情
│       │   ├── CartPage.ets         # 购物车
│       │   ├── OrderListPage.ets    # 订单列表
│       │   ├── PaymentPage.ets      # 支付页面
│       │   ├── ProfilePage.ets      # 个人资料
│       │   ├── ChatPage.ets         # 聊天页面
│       │   ├── MessagePage.ets      # 消息列表
│       │   ├── FavoritesPage.ets    # 收藏列表
│       │   ├── FollowListPage.ets   # 关注/粉丝列表
│       │   ├── CouponListPage.ets   # 优惠券列表
│       │   ├── LoginPage.ets        # 登录
│       │   └── RegisterPage.ets     # 注册
│       ├── view/                # 可复用组件
│       │   ├── WaterFlowComponent.ets  # 瀑布流组件
│       │   ├── FlowItemComponent.ets   # 商品卡片
│       │   ├── SearchComponent.ets     # 搜索组件
│       │   ├── SwiperComponent.ets     # 轮播图
│       │   ├── AIFloatingButton.ets    # AI悬浮按钮
│       │   └── AIChatDialog.ets        # AI对话框
│       └── viewmodel/           # 视图模型
│           ├── HomeViewModel.ets
│           ├── ProductItem.ets
│           ├── CartItem.ets
│           └── User.ets
├── server/                      # 后端服务器
│   ├── src/
│   │   ├── index.js             # 入口文件
│   │   ├── app.js               # Express应用
│   │   ├── models/              # 数据模型
│   │   │   ├── User.js
│   │   │   ├── Product.js
│   │   │   ├── Order.js
│   │   │   ├── Favorite.js
│   │   │   ├── Follow.js
│   │   │   ├── Coupon.js
│   │   │   ├── Comment.js
│   │   │   └── Message.js
│   │   ├── routes/              # API路由
│   │   │   ├── auth.js          # 认证
│   │   │   ├── user.js          # 用户
│   │   │   ├── products.js      # 商品
│   │   │   ├── orders.js        # 订单
│   │   │   ├── favorites.js     # 收藏
│   │   │   ├── follows.js       # 关注
│   │   │   ├── coupons.js       # 优惠券
│   │   │   ├── comments.js      # 评论
│   │   │   └── messages.js      # 消息
│   │   └── middleware/
│   │       └── auth.js          # JWT中间件
│   ├── database.sqlite          # SQLite数据库
│   └── package.json
└── screenshots/                 # 截图
```

---

## 🔌 API 接口文档

### 认证模块

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/auth/register` | POST | 用户注册 |
| `/api/auth/login` | POST | 用户登录 |

**注册请求**：
```json
{
  "username": "testuser",
  "password": "123456",
  "nickname": "测试用户",
  "email": "test@example.com",
  "phone": "13800138000"
}
```

**登录响应**：
```json
{
  "success": true,
  "data": {
    "user": { "id": 1, "username": "testuser", "nickname": "测试用户" },
    "token": "eyJhbGciOiJIUzI1NiIs..."
  }
}
```

### 用户模块

| 接口 | 方法 | 认证 | 说明 |
|------|------|------|------|
| `/api/user/profile` | GET | ✅ | 获取当前用户信息 |
| `/api/user/profile` | PUT | ✅ | 更新用户信息 |
| `/api/user/:username` | GET | ❌ | 根据用户名获取用户 |

### 商品模块

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/products` | GET | 商品列表（支持分页、筛选、搜索） |
| `/api/products/:id` | GET | 商品详情 |

### 收藏模块

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/favorites` | GET | 收藏列表 |
| `/api/favorites` | POST | 添加收藏 |
| `/api/favorites/:productId` | DELETE | 取消收藏 |
| `/api/favorites/check/:productId` | GET | 检查收藏状态 |

### 关注模块

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/follows/following` | GET | 关注列表 |
| `/api/follows/followers` | GET | 粉丝列表 |
| `/api/follows/count` | GET | 关注/粉丝数量 |
| `/api/follows/:userId` | POST | 关注用户 |
| `/api/follows/:userId` | DELETE | 取消关注 |
| `/api/follows/check/:userId` | GET | 检查关注状态 |

### 订单模块

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/orders` | GET | 订单列表 |
| `/api/orders` | POST | 创建订单 |
| `/api/orders/:orderNo` | GET | 订单详情 |
| `/api/orders/:orderNo/cancel` | PUT | 取消订单 |
| `/api/orders/:orderNo/confirm` | PUT | 确认收货 |

### 优惠券模块

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/coupons` | GET | 优惠券列表 |
| `/api/coupons/claim` | POST | 领取优惠券 |
| `/api/coupons/count` | GET | 可用优惠券数量 |
| `/api/coupons/:id/use` | PUT | 使用优惠券 |

### 评论模块

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/comments/product/:productId` | GET | 获取商品评论 |
| `/api/comments` | POST | 发表评论 |
| `/api/comments/:commentId/reply` | POST | 回复评论 |
| `/api/comments/:commentId/vote` | POST | 点赞/点踩 |
| `/api/comments/:commentId` | DELETE | 删除评论 |

### 消息模块

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/messages/conversations` | GET | 会话列表 |
| `/api/messages/chat/:otherUserId` | GET | 聊天记录 |
| `/api/messages/send` | POST | 发送消息 |
| `/api/messages/read/:otherUserId` | PUT | 标记已读 |
| `/api/messages/unread/count` | GET | 未读消息数 |

---

## 🔒 安全设计

### 密码加密

- **算法**：SHA256
- **盐值**：`HMstore_${username}_salt_2026`
- **存储格式**：`$hashed$` + 64位十六进制哈希值

### JWT Token

- **有效期**：7天
- **请求头**：`Authorization: Bearer <token>`

---

## 🧪 测试账号

| 用户名 | 密码 | 说明 |
|--------|------|------|
| 111111 | 111111 | 测试账号1 |
| 222222 | 222222 | 测试账号2 |
| 333333 | 333333 | 测试账号3 |
| 444444 | 444444 | 测试账号4 |
| aaaaaa | aaaaaa | 测试账号5 |
| qqqqqq | qqqqqq | 测试账号6 |

---

## ❓ 常见问题

### 1. 端口被占用

```bash
# 查看占用端口的进程
netstat -ano | findstr :3000

# 结束进程
taskkill /PID <进程ID> /F
```

### 2. 模拟器无法连接服务器

- 确认服务器已启动
- 确认使用 `10.0.2.2` 地址
- 检查 Windows 防火墙是否放行 Node.js

### 3. 真机无法连接服务器

- 确认手机和电脑在同一网络
- 确认 IP 地址正确
- 手机浏览器访问 `http://IP:3000/api/products` 测试

### 4. npm install 失败

```bash
# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com
npm install

# 或清除缓存重试
npm cache clean --force
npm install
```

### 5. 数据库重置

```bash
# 删除数据库文件，重启服务器会自动重建
del server\database.sqlite
npm start
```

---

## 🌐 云服务器部署

### 部署步骤

1. 上传 `server/` 文件夹到云服务器
2. 安装 Node.js
3. 安装依赖：`npm install`
4. 启动服务：`npm start`
5. **开放防火墙端口**（重要！）

### 安全组配置

在云服务器控制台（阿里云/腾讯云）添加入站规则：

| 协议 | 端口 | 来源 |
|------|------|------|
| TCP | 3000 | 0.0.0.0/0 |

### 客户端配置

修改 `ServerConfig.ets`：
```typescript
export const SERVER_BASE_URL: string = 'http://你的公网IP:3000';
```

---

## 📋 技术要点

### ArkUI 状态管理

```typescript
// ❌ 错误：直接修改不触发更新
this.items[0].name = 'new name';

// ✅ 正确：创建新引用
this.items = this.items.map((item, i) => 
  i === 0 ? {...item, name: 'new name'} : item
);
```

### 数据同步模式

采用"服务器优先"模式：
1. 用户操作 → 请求服务器
2. 服务器成功 → 更新本地缓存
3. 服务器失败 → 返回错误，不更新本地

---

## 📄 相关文档

- [server文件夹说明.md](server文件夹说明.md) - server 与 App 编译无关的说明
- [自建服务器配置教程.md](自建服务器配置教程.md) - 本地/云服务器搭建教程
- [server/README.md](server/README.md) - 后端服务器详细说明

---

## 📜 许可证

本项目仅供学习交流使用。

---

*如有问题，请检查服务器日志和客户端控制台输出*