## 一、项目概述

### 1.1 项目简介

本项目是一个基于HarmonyOS平台开发的点评类应用，类似于"大众点评"的功能。应用提供了商家浏览、搜索、评价、购物车、订单支付等核心功能，帮助用户发现和选择优质商家。

### 1.2 技术栈

- **开发框架**：HarmonyOS ArkUI

- **开发语言**：ArkTS（TypeScript的超集）

- **数据库**：HarmonyOS RDB（关系型数据库）

- **状态管理**：AppStorage（应用级状态管理）

- **路由管理**：@ohos.router

### 1.3 项目结构

```

MyApplicationaaaa/

├── AppScope/                    # 应用级配置

│   ├── app.json5               # 应用配置

│   └── resources/              # 应用级资源

├── entry/                       # 主模块

│   └── src/main/

│       ├── ets/                # 源代码目录

│       │   ├── common/         # 公共模块

│       │   │   ├── Types.ets           # 类型定义

│       │   │   └── DatabaseService.ets # 数据库服务

│       │   ├── entryability/   # 入口Ability

│       │   │   └── EntryAbility.ets

│       │   └── pages/          # 页面组件

│       │       ├── Index.ets           # 首页

│       │       ├── Login.ets           # 登录页

│       │       ├── BusinessDetail.ets # 商家详情页

│       │       ├── Cart.ets            # 购物车页

│       │       └── Profile.ets         # 个人中心页

│       └── resources/          # 资源文件

└── build-profile.json5         # 构建配置

```

## 二、需求分析

### 2.1 功能需求

#### 2.1.1 用户认证模块

- **登录功能**：支持用户名/手机号登录，密码验证

- **快速注册**：提供测试账号快速注册功能

- **登录状态管理**：全局管理用户登录状态

#### 2.1.2 商家浏览模块

- **商家列表展示**：展示商家基本信息（名称、评分、分类、距离、价格等）

- **搜索功能**：支持按商家名称、分类、地址进行模糊搜索

- **分类导航**：提供美食、电影、酒店等分类快速筛选

- **商家详情**：查看商家详细信息、营业信息、用户评价

#### 2.1.3 互动功能模块

- **收藏功能**：用户可以收藏喜欢的商家

- **点赞功能**：对商家和评价进行点赞

- **评价功能**：用户可以发表评价，包含评分和文字内容

#### 2.1.4 购物功能模块

- **购物车管理**：添加商品到购物车，调整商品数量，删除商品

- **订单支付**：支持余额支付，创建订单记录

- **余额管理**：显示用户余额，支付时自动扣款

#### 2.1.5 个人中心模块

- **用户信息展示**：显示用户头像、昵称、余额

- **信息编辑**：支持修改昵称、手机号、头像

### 2.2 非功能需求

- **数据持久化**：使用本地数据库存储用户、购物车、订单数据

- **用户体验**：界面美观，操作流畅

- **状态同步**：多页面间状态实时同步

## 三、系统设计

### 3.1 架构设计

#### 3.1.1 整体架构

采用经典的MVC架构模式：

- **Model层**：`DatabaseService.ets` - 数据模型和数据库操作

- **View层**：各个页面组件（`Index.ets`、`Login.ets`等）

- **Controller层**：页面组件的业务逻辑处理

#### 3.1.2 数据流设计

```

用户操作 → 页面组件 → 业务逻辑处理 → 数据库服务 → RDB数据库

                ↓

            AppStorage（全局状态管理）

```

### 3.2 数据库设计

#### 3.2.1 数据库表结构

**用户表（user）**

| 字段名 | 类型 | 说明 |

|--------|------|------|

| id | INTEGER | 主键，用户ID |

| username | TEXT | 用户名 |

| phone | TEXT | 手机号 |

| avatar | TEXT | 头像地址 |

| balance | REAL | 账户余额 |

**购物车表（cart）**

| 字段名 | 类型 | 说明 |

|--------|------|------|

| id | INTEGER | 主键，自增 |

| userId | INTEGER | 用户ID |

| businessId | INTEGER | 商家ID |

| itemName | TEXT | 商品名称 |

| price | REAL | 单价 |

| quantity | INTEGER | 数量 |

**订单表（orders）**

| 字段名 | 类型 | 说明 |

|--------|------|------|

| id | INTEGER | 主键，自增 |

| userId | INTEGER | 用户ID |

| businessId | INTEGER | 商家ID |

| totalAmount | REAL | 订单总金额 |

| createTime | TEXT | 创建时间 |

#### 3.2.2 数据库初始化

在`DatabaseService.ets`中，通过`getRdbStore()`函数实现数据库的懒加载初始化：

- 首次调用时创建数据库连接

- 自动创建三个数据表

- 使用单例模式，确保全局只有一个数据库连接

### 3.3 状态管理设计

#### 3.3.1 全局状态

使用`AppStorage`管理全局状态：

- `isLoggedIn`：用户登录状态（boolean）

- `user`：当前登录用户信息（User对象）

#### 3.3.2 页面状态

使用`@State`装饰器管理页面内部状态：

- 商家列表、搜索关键字、收藏列表等

- 购物车商品列表、总金额等

- 用户余额、编辑信息等

### 3.4 页面路由设计

应用采用单页面应用（SPA）架构，通过路由进行页面跳转：

| 路由路径 | 对应页面 | 说明 |

|---------|---------|------|

| pages/Index | 首页 | 应用入口，商家列表 |

| pages/Login | 登录页 | 用户登录 |

| pages/BusinessDetail | 商家详情页 | 商家详细信息 |

| pages/Cart | 购物车页 | 购物车管理 |

| pages/Profile | 个人中心页 | 用户信息管理 |

## 四、核心功能实现

### 4.1 用户认证模块实现

#### 4.1.1 登录功能

**实现位置**：`Login.ets`

**核心逻辑**：

1. 用户输入用户名/手机号和密码

2. 在模拟用户数据库中查找匹配的用户

3. 验证密码是否正确

4. 登录成功后：

   - 调用`ensureUser()`确保用户在数据库中存在（首次登录自动创建，初始余额200元）

   - 将用户信息存储到`AppStorage`

   - 设置登录状态为`true`

   - 返回上一页面

**关键代码片段**：

```typescript

handleLogin() {

  // 验证输入

  if (!this.username.trim() || !this.password.trim()) {

    this.errorMessage = '请输入用户名和密码';

    return;

  }

 

  // 查找用户并验证密码

  const user = this.mockUsers.find(u =>

    u.username === this.username || u.phone === this.username

  );

 

  if (user && this.password === this.mockPasswords[this.username]) {

    // 确保用户存在于数据库

    ensureUser(user.id, user.username, user.phone).then(() => {

      AppStorage.setOrCreate('user', user);

      AppStorage.setOrCreate('isLoggedIn', true);

      router.back();

    });

  }

}

```

#### 4.1.2 登录状态检查

在各个需要登录的功能中，通过`@StorageLink('isLoggedIn')`装饰器监听登录状态，未登录时自动跳转到登录页。

### 4.2 商家浏览模块实现

#### 4.2.1 首页商家列表

**实现位置**：`Index.ets`

**核心功能**：

1. **商家数据**：使用`@State`装饰器定义商家列表，包含5个示例商家

2. **搜索功能**：通过`getFilteredBusinessList()`方法实现模糊搜索

   - 支持按商家名称、分类、地址搜索

   - 使用`indexOf()`方法进行字符串匹配

3. **分类导航**：提供10个分类选项，点击切换分类（当前为演示功能）

4. **商家卡片**：展示商家关键信息，支持点击跳转到详情页

**搜索实现**：

```typescript

getFilteredBusinessList(): Array<Business> {

  const keyword: string = this.searchText.trim();

  if (!keyword) {

    return this.businessList;

  }

  const result: Business[] = [];

  for (let i = 0; i < this.businessList.length; i++) {

    const item = this.businessList[i];

    if (item.name.indexOf(keyword) >= 0 ||

        item.category.indexOf(keyword) >= 0 ||

        item.address.indexOf(keyword) >= 0) {

      result.push(item);

    }

  }

  return result;

}

```

#### 4.2.2 商家详情页

**实现位置**：`BusinessDetail.ets`

**核心功能**：

1. **数据接收**：通过路由参数接收商家信息

   ```typescript

   aboutToAppear() {

     const params = router.getParams() as RouteParams;

     if (params && params.business) {

       this.business = JSON.parse(params.business) as Business;

     }

   }

   ```

2. **信息展示**：

   - 商家基本信息（名称、评分、分类、距离）

   - 营业信息（地址、电话、营业时间）

   - 用户评价列表

   - 推荐菜品

3. **余额显示**：登录后显示当前用户余额

### 4.3 互动功能模块实现

#### 4.3.1 收藏功能

**实现位置**：`Index.ets`、`BusinessDetail.ets`

**实现方式**：

- 首页：使用`@State favoriteList: number[]`存储收藏的商家ID列表

- 点击收藏按钮时，检查是否已收藏，切换收藏状态

- 使用数组操作（`concat`、`filter`）更新收藏列表

**关键代码**：

```typescript

toggleFavorite(businessId: number) {

  if (!this.isLoggedIn) {

    router.pushUrl({ url: 'pages/Login' });

    return;

  }

  if (this.favoriteList.includes(businessId)) {

    // 取消收藏：过滤掉该ID

    const newFavorites: number[] = [];

    for (let i = 0; i < this.favoriteList.length; i++) {

      if (this.favoriteList[i] !== businessId) {

        newFavorites.push(this.favoriteList[i]);

      }

    }

    this.favoriteList = newFavorites;

  } else {

    // 添加收藏

    this.favoriteList = this.favoriteList.concat([businessId]);

  }

}

```

#### 4.3.2 评价功能

**实现位置**：`BusinessDetail.ets`

**核心功能**：

1. **评价展示**：使用`@State reviews: Review[]`存储评价列表

2. **发表评价**：

   - 点击"写评价"按钮显示评价输入框

   - 用户选择评分（1-5星）和输入文字内容

   - 提交后将新评价添加到列表顶部

   - 更新商家评价数量

**评价提交**：

```typescript

submitReview() {

  if (!this.newReview.trim()) {

    return;

  }

 

  const newReview: Review = {

    id: Date.now(),

    userId: this.currentUser.id,

    businessId: this.business.id,

    rating: this.reviewRating,

    content: this.newReview,

    createTime: new Date().toLocaleDateString(),

    likes: 0,

    user: this.currentUser

  };

 

  this.reviews = [newReview].concat(this.reviews);

  this.business.reviewCount += 1;

}

```

### 4.4 购物功能模块实现

#### 4.4.1 购物车管理

**实现位置**：`Cart.ets`、`DatabaseService.ets`

**核心功能**：

1. **添加商品**：在商家详情页点击"加入购物车"

   ```typescript

   // BusinessDetail.ets

   addToCart(this.currentUser.id, this.business.id,

             this.business.name, priceValue, 1)

   ```

2. **购物车列表**：从数据库加载当前用户的购物车商品

   ```typescript

   // Cart.ets

   getCartItems(this.currentUser.id).then((items: CartItem[]) => {

     this.cartItems = items;

     this.totalAmount = this.calcTotal(items);

   });

   ```

3. **数量调整**：

   - 点击"+"增加数量

   - 点击"-"减少数量，数量为0时删除商品

   - 每次操作后更新数据库并重新加载列表

4. **结算功能**：

   - 计算总金额

   - 检查余额是否充足

   - 扣减余额

   - 创建订单记录

   - 清空购物车

**结算流程**：

```typescript

handleCheckout() {

  // 1. 检查余额

  getUserBalance(this.currentUser.id).then((balance: number) => {

    if (balance < this.totalAmount) {

      this.message = '余额不足，无法结算';

      return;

    }

   

    // 2. 扣减余额

    const newBalance = balance - this.totalAmount;

    updateUserBalance(this.currentUser.id, newBalance).then(() => {

      // 3. 创建订单

      createOrder(this.currentUser.id, businessId, this.totalAmount).then(() => {

        // 4. 清空购物车

        clearCart(this.currentUser.id).then(() => {

          this.message = '结算成功';

          this.loadData(); // 重新加载数据

        });

      });

    });

  });

}

```

#### 4.4.2 立即购买

**实现位置**：`BusinessDetail.ets`

**功能**：在商家详情页直接购买，流程与购物车结算类似，但跳过购物车步骤，直接扣款并创建订单。

### 4.5 数据库服务实现

#### 4.5.1 数据库初始化

**实现位置**：`DatabaseService.ets`

**核心函数**：`getRdbStore()`

- 使用单例模式，确保全局只有一个数据库连接

- 首次调用时创建数据库和表结构

- 保存`abilityContext`用于数据库操作

```typescript

async function getRdbStore(): Promise<rdb.RdbStore> {

  if (rdbStore) {

    return rdbStore; // 返回已存在的连接

  }

 

  const config: rdb.StoreConfig = {

    name: DB_NAME,

  };

  const abilityContext: common.Context = getAbilityContext();

  const newRdbStore = await rdb.getRdbStore(abilityContext, config, DB_VERSION);

 

  // 创建表

  await newRdbStore.executeSql(SQL_CREATE_USER_TABLE, []);

  await newRdbStore.executeSql(SQL_CREATE_CART_TABLE, []);

  await newRdbStore.executeSql(SQL_CREATE_ORDER_TABLE, []);

 

  rdbStore = newRdbStore;

  return rdbStore;

}

```

#### 4.5.2 用户管理

- `ensureUser()`：确保用户存在，不存在则创建（初始余额200元）

- `getUserBalance()`：获取用户余额

- `updateUserBalance()`：更新用户余额

- `updateUserProfile()`：更新用户信息

#### 4.5.3 购物车管理

- `addToCart()`：添加商品到购物车

- `getCartItems()`：获取用户购物车列表

- `updateCartItemQuantity()`：更新商品数量

- `deleteCartItem()`：删除购物车商品

- `clearCart()`：清空购物车

#### 4.5.4 订单管理

- `createOrder()`：创建订单记录

### 4.6 个人中心模块实现

#### 4.6.1 用户信息展示

**实现位置**：`Profile.ets`

**功能**：

- 显示用户头像（首字母头像）

- 显示用户名和余额

- 从数据库加载余额信息

#### 4.6.2 信息编辑

**功能**：

- 编辑昵称、手机号、头像地址

- 保存后更新数据库和全局状态

- 使用`updateUserProfile()`更新数据库

- 同步更新`AppStorage`中的用户信息

## 五、关键技术点

### 5.1 ArkUI组件使用

#### 5.1.1 装饰器

- `@Entry`：标记入口组件

- `@Component`：标记自定义组件

- `@State`：组件内部状态管理

- `@StorageLink`：与AppStorage双向绑定

- `@Builder`：自定义构建函数

#### 5.1.2 常用组件

- `Column`、`Row`：布局组件

- `Text`、`TextInput`：文本组件

- `Button`：按钮组件

- `List`、`ListItem`：列表组件

- `Scroll`：滚动容器

- `Divider`：分隔线

### 5.2 路由管理

使用`@ohos.router`进行页面跳转：

```typescript

// 跳转到指定页面

router.pushUrl({

  url: 'pages/BusinessDetail',

  params: { business: JSON.stringify(business) }

});

// 返回上一页

router.back();

```

### 5.3 数据持久化

使用HarmonyOS RDB进行数据持久化：

- 使用`RdbPredicates`构建查询条件

- 使用`ValuesBucket`进行数据插入和更新

- 使用`ResultSet`遍历查询结果

### 5.4 状态管理

- **全局状态**：使用`AppStorage`管理登录状态和用户信息

- **页面状态**：使用`@State`管理页面内部状态

- **状态同步**：通过`@StorageLink`实现跨页面状态同步

## 六、项目特色

### 6.1 完整的业务流程

- 从用户登录到浏览商家、添加购物车、支付结算的完整流程

- 数据持久化，应用重启后数据不丢失

### 6.2 良好的用户体验

- 清晰的界面布局

- 流畅的页面跳转

- 实时的状态反馈

### 6.3 规范的代码结构

- 模块化设计，职责清晰

- 类型定义统一管理

- 数据库操作封装

## 七、项目总结

### 7.1 实现的功能

✅ 用户登录和状态管理  

✅ 商家列表浏览和搜索  

✅ 商家详情查看  

✅ 收藏和点赞功能  

✅ 用户评价功能  

✅ 购物车管理  

✅ 订单支付（余额支付）  

✅ 个人中心信息管理  

✅ 数据持久化存储  

### 7.2 技术亮点

1. **数据库设计**：合理的数据表结构，支持用户、购物车、订单的完整管理

2. **状态管理**：使用AppStorage实现全局状态管理，确保多页面状态同步

3. **业务逻辑封装**：数据库操作统一封装在DatabaseService中，便于维护

4. **用户体验优化**：登录检查、余额验证、操作反馈等细节处理

### 7.3 可扩展方向

1. **网络请求**：接入真实的后端API，实现数据动态加载

2. **图片加载**：使用网络图片替代文字占位符

3. **地图功能**：集成地图SDK，显示商家真实位置

4. **支付功能**：接入真实的支付SDK

5. **推送功能**：订单状态变更推送

6. **数据统计**：用户行为分析

## 八、学习要点

### 8.1 HarmonyOS开发基础

- ArkTS语言特性（类型系统、装饰器）

- ArkUI组件使用

- 页面路由管理

- 数据持久化（RDB）

### 8.2 应用架构设计

- MVC架构模式

- 状态管理方案

- 模块化设计思想

### 8.3 业务逻辑实现

- 用户认证流程

- 购物车和订单管理

- 数据CRUD操作

### 8.4 代码规范

- 类型定义规范

- 函数命名规范

- 代码注释规范

## 九、运行说明

### 9.1 环境要求

- DevEco Studio 4.0+

- HarmonyOS SDK API 9+

- HarmonyOS设备或模拟器

### 9.2 测试账号

- 账号1：`13800000000`，密码：`123456`

- 账号2：`13900000000`，密码：`123456`

- 账号3：`用户123`，密码：`123456`

### 9.3 运行步骤

1. 使用DevEco Studio打开项目

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

3. 点击运行按钮

4. 使用测试账号登录

5. 体验各项功能

---

**文档版本**：v1.0  

**最后更新**：2025年  

**作者**：江鸟中原