# wanandroid Uniapp 项目 - 模块化重构说明

## 项目概述

本项目是基于Uniapp框架开发的wanandroid客户端应用，已按照软件工程原则进行了模块化重构，提高了代码的可维护性、可复用性和可扩展性。

## 目录结构

```
uniapp/
├── common/                    # 公共资源
│   ├── api/                  # API接口管理
│   │   ├── home.api.js       # 首页模块API
│   │   └── project.api.js    # 项目模块API
│   ├── utils/                # 工具函数
│   │   ├── request.js        # 统一请求工具
│   │   └── common.js         # 通用工具函数
│   ├── constants/            # 常量定义
│   │   └── app.constants.js  # 应用常量
│   └── config/               # 配置文件
│       └── api.config.js     # API配置
├── components/               # 公共组件
│   ├── common/              # 通用组件
│   │   ├── loading.vue      # 加载组件
│   │   └── empty-state.vue  # 空状态组件
│   ├── home/                # 首页专用组件
│   │   └── banner.vue       # Banner轮播组件
│   └── project/             # 项目模块专用组件
│       └── category-tabs.vue # 分类标签组件
├── pages/                   # 页面
│   ├── home/               # 首页模块
│   │   └── index.vue       # 首页页面（已重构）
│   ├── project/            # 项目模块
│   │   ├── project.vue     # 项目列表页面（已重构）
│   │   └── project-detail/ # 项目详情
│   ├── wxarticle/          # 公众号模块
│   ├── tree/               # 体系模块
│   └── mine/               # 我的模块
├── static/                  # 静态资源
│   ├── images/
│   ├── icons/
│   └── fonts/
└── store/                   # 状态管理（待实现）
```

## 模块化设计原则

### 1. 单一职责原则
- 每个模块/组件只负责一个特定的功能
- API管理、UI组件、业务逻辑分离

### 2. 高内聚低耦合
- 相关功能集中管理（如首页所有API在`home.api.js`中）
- 模块间通过清晰的接口通信

### 3. 可复用性
- 提取公共组件（Loading、EmptyState等）
- 工具函数统一管理
- 配置集中管理

### 4. 可维护性
- 清晰的目录结构
- 统一的代码规范
- 完善的错误处理

## 已完成的模块

### 1. 首页模块 (`/pages/index/index.vue`)
- **功能**：Banner轮播、文章列表、搜索热词
- **组件**：HomeBanner、CommonLoading、EmptyState
- **API**：`home.api.js`（统一管理首页所有API）
- **特性**：
  - 下拉刷新、上拉加载
  - 图片懒加载
  - 回到顶部功能
  - 完善的错误处理

### 2. 项目模块 (`/pages/project/project.vue`)
- **功能**：项目分类、项目列表、项目搜索
- **组件**：ProjectCategoryTabs、CommonLoading、EmptyState
- **API**：`project.api.js`（统一管理项目所有API）
- **特性**：
  - 分类标签切换
  - 项目网格布局
  - 点赞、收藏、查看源码
  - 项目状态标识（NEW、HOT）

## 公共组件

### 1. CommonLoading (`components/common/loading.vue`)
- 统一的加载动画组件
- 支持自定义文本和样式
- 支持全屏和局部加载

### 2. EmptyState (`components/common/empty-state.vue`)
- 空状态提示组件
- 支持自定义图标、标题、描述
- 支持操作按钮

### 3. HomeBanner (`components/home/banner.vue`)
- Banner轮播组件
- 支持自动播放、循环播放
- 支持点击事件和跳转

### 4. ProjectCategoryTabs (`components/project/category-tabs.vue`)
- 项目分类标签组件
- 支持水平滚动
- 选中状态指示器

## API管理

### 统一请求工具 (`common/utils/request.js`)
- 封装`uni.request`，提供统一的错误处理
- 支持请求拦截器和响应拦截器
- 支持GET、POST、PUT、DELETE方法
- 自动处理加载状态

### API配置 (`common/config/api.config.js`)
- 统一管理所有API接口地址
- 按模块分组管理
- 支持环境配置

### 模块化API (`common/api/`)
- 每个模块有独立的API管理文件
- 提供完整的业务方法
- 统一的数据处理逻辑

## 工具函数 (`common/utils/common.js`)
- 时间格式化（相对时间、绝对时间）
- 防抖和节流函数
- 深度克隆
- 安全属性访问
- 文件大小格式化
- 剪贴板操作

## 常量定义 (`common/constants/app.constants.js`)
- 应用信息
- 存储键名
- 页面路由
- 事件名称
- 错误码和错误消息
- 颜色配置
- 字体配置
- 动画配置

## 使用示例

### 在页面中使用API
```javascript
// 导入API
import { getHomeData } from '@/common/api/home.api.js'

// 使用API
async loadData() {
  try {
    const homeData = await getHomeData(this.currentPage)
    this.bannerList = homeData.bannerList
    this.articleList = homeData.articleList
  } catch (error) {
    console.error('加载数据失败:', error)
  }
}
```

### 在页面中使用组件
```vue
<template>
  <!-- 使用公共组件 -->
  <common-loading :visible="loading" />
  <empty-state v-if="isEmpty" @action="refreshData" />
  
  <!-- 使用模块组件 -->
  <home-banner :banner-list="bannerList" @click="handleBannerClick" />
</template>

<script>
import CommonLoading from '@/components/common/loading.vue'
import EmptyState from '@/components/common/empty-state.vue'
import HomeBanner from '@/components/home/banner.vue'

export default {
  components: {
    CommonLoading,
    EmptyState,
    HomeBanner
  }
}
</script>
```

### 使用工具函数
```javascript
import { formatRelativeTime, debounce } from '@/common/utils/common.js'

// 格式化时间
const relativeTime = formatRelativeTime(timestamp)

// 防抖处理
const debouncedSearch = debounce(this.handleSearch, 500)
```

## 后续开发建议

### 1. 状态管理
- 实现Vuex或Pinia进行全局状态管理
- 管理用户信息、主题设置等全局状态

### 2. 更多模块开发
- 公众号模块 (`wxarticle`)
- 体系模块 (`tree`)
- 我的模块 (`mine`)

### 3. 性能优化
- 图片懒加载优化
- 列表虚拟滚动
- 数据缓存策略

### 4. 功能扩展
- 搜索功能
- 用户登录/注册
- 文章收藏
- 夜间模式

### 5. 测试
- 单元测试
- 集成测试
- E2E测试

## 开发规范

### 1. 命名规范
- 组件：大驼峰命名，如`HomeBanner`
- 文件：小写字母+连字符，如`home-banner.vue`
- 变量：小驼峰命名，如`articleList`
- 常量：大写字母+下划线，如`API_CONFIG`

### 2. 代码组织
- 每个文件不超过500行
- 每个函数不超过50行
- 使用ES6+语法
- 添加必要的注释

### 3. 错误处理
- 所有异步操作都要有错误处理
- 用户友好的错误提示
- 错误日志记录

### 4. 性能考虑
- 避免不必要的重渲染
- 合理使用计算属性和侦听器
- 图片优化和懒加载

## 总结

本次重构按照软件工程原则，将项目从简单的页面堆砌重构为模块化、组件化的架构。新的架构具有以下优势：

1. **可维护性**：清晰的目录结构和模块划分
2. **可复用性**：公共组件和工具函数
3. **可扩展性**：易于添加新功能和模块
4. **可靠性**：统一的错误处理和API管理
5. **一致性**：统一的代码规范和设计模式

这种架构为后续的功能扩展和维护提供了良好的基础。