a

2026-07-03 16:58:28 +08:00
commit 32b43f85bd
6240 changed files with 1987678 additions and 0 deletions
@@ -0,0 +1,263 @@
+# 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. **一致性**：统一的代码规范和设计模式
+
+这种架构为后续的功能扩展和维护提供了良好的基础。