hookehuyr

docs: 添加项目文档"静待花开-活动小助手"

添加完整的项目文档,包含项目概述、技术栈、项目结构、核心功能模块、API接口设计、状态管理、UI组件库、开发规范、项目配置、工具函数库、构建部署说明、注意事项和页面实现细节等内容
# 静待花开-活动小助手 项目文档
## 项目概述
**项目名称**: 静待花开-活动小助手 (swx-weapp)
**项目版本**: 1.0.0
**项目类型**: 微信小程序
**开发框架**: Taro 3.4.10 + Vue 3 + Vant Weapp
**Node.js版本**: 16.14.2
## 技术栈
### 核心框架
- **Taro**: 3.4.10 (多端统一开发框架)
- **Vue**: 3.2.24 (使用 Composition API)
- **Pinia**: 2.0.6 (状态管理)
- **Vant Weapp**: 1.11.7 (UI组件库)
### 开发工具
- **构建工具**: Webpack + Babel
- **样式预处理**: Less
- **代码规范**: ESLint + Stylelint
- **包管理**: npm/pnpm
- **跨平台环境变量**: cross-env
### 网络请求
- **HTTP客户端**: axios-miniprogram 2.0.0-rc-2
- **数据序列化**: qs 6.11.0
- **时间处理**: dayjs 1.11.5
## 项目结构
```
src/
├── api/ # API接口层
│ ├── Activity/ # 活动相关接口
│ ├── Host/ # 主办方接口
│ ├── Member/ # 成员接口
│ ├── Partner/ # 合作伙伴接口
│ ├── Reg/ # 注册接口
│ ├── User/ # 用户接口
│ ├── wx/ # 微信相关接口
│ ├── common.js # 通用接口
│ └── fn.js # 接口封装函数
├── assets/ # 静态资源
│ ├── images/ # 图片资源
│ └── styles/ # 全局样式
├── components/ # 公共组件
│ ├── vant-weapp/ # Vant组件库
│ ├── activity-bar.vue # 活动栏组件
│ ├── activity-card.vue # 活动卡片组件
│ ├── navbar.vue # 底部导航栏
│ └── ...
├── pages/ # 页面目录
│ ├── index/ # 首页
│ ├── createActivity/ # 创建活动
│ ├── activityDetail/ # 活动详情
│ ├── joinActivity/ # 参加活动
│ ├── userInfo/ # 用户信息
│ ├── auth/ # 授权页面
│ ├── my/ # 我的页面
│ └── ...
├── stores/ # 状态管理
│ ├── counter.js # 计数器状态
│ ├── host.js # 主办方状态
│ └── router.js # 路由状态
├── utils/ # 工具函数
│ ├── config.js # 配置文件
│ ├── request.js # 网络请求封装
│ ├── tools.js # 工具函数
│ └── ...
├── app.config.js # 应用配置
├── app.js # 应用入口
└── app.less # 全局样式
```
## 核心功能模块
### 1. 用户认证模块
- **授权页面**: `/pages/auth/index`
- **功能**: 微信授权登录,获取用户信息
- **权限控制**: 未授权用户自动跳转到授权页面
### 2. 活动管理模块
- **首页**: 推荐活动展示,轮播图
- **创建活动**: `/pages/createActivity/index`
- **活动详情**: `/pages/activityDetail/index`
- **参加活动**: `/pages/joinActivity/index`
- **我的活动**: 创建的活动和参加的活动列表
### 3. 用户管理模块
- **用户信息**: `/pages/userInfo/index`
- **用户编辑**: `/pages/editInfo/index`
- **用户搜索**: `/pages/userSearch/index`
### 4. 项目管理模块
- **项目管理**: `/pages/projectManage/index`
- **创建项目**: `/pages/createProject/index`
- **编辑项目**: `/pages/editProject/index`
## API接口设计
### 基础配置
- **服务器地址**: `https://oa.onwall.cn`
- **请求格式**: RESTful API
- **参数标识**: `f=swx`
- **超时时间**: 5000ms
### 主要接口模块
#### 活动接口 (Activity)
- `activity_join_list`: 我加入的活动列表
- `activity_add_list`: 我创建的活动列表
- `activity_copy`: 复制活动
- `activity_end`: 结束活动
- `activity_del`: 删除活动
- `activity_info_qrcode`: 生成小程序码
#### 用户接口 (User)
- `user_info`: 获取用户信息
- `user_edit`: 修改用户信息
#### 通用接口 (Common)
- `sms`: 发送验证码
- `upload`: 获取七牛云上传token
- `save_file`: 保存文件
## 状态管理
### Pinia Store
- **router.js**: 路由状态管理,缓存未授权访问的页面
- **host.js**: 主办方相关状态
- **counter.js**: 计数器状态
## UI组件库
### Vant Weapp 组件
已配置的组件包括:
- 基础组件: button, icon, loading, info
- 表单组件: field, cell, picker, stepper, uploader, switch, radio, checkbox
- 反馈组件: toast, dialog, action-sheet, share-sheet
- 展示组件: image, tag, skeleton, empty
- 导航组件: tab, tabs, sticky
- 布局组件: col, row, popup, overlay
### 自定义组件
- **navbar.vue**: 底部导航栏 (首页/创建/我的)
- **activity-card.vue**: 活动卡片展示
- **activity-bar.vue**: 活动栏组件
## 开发规范
### 代码规范
- 使用 Vue 3 Composition API
- 使用 `<script setup>` 语法糖
- 样式使用 Less 预处理器
- 遵循 ESLint 代码规范
### 文件命名
- 页面文件: 小写字母 + 连字符
- 组件文件: 小写字母 + 连字符
- 工具文件: 小写字母 + 连字符
### 注释规范
- 文件头部包含作者、日期、描述信息
- 函数使用 JSDoc 风格注释
- 重要逻辑添加行内注释
## 项目配置详解
### Taro 配置 (config/index.js)
- **设计稿宽度**: 750px
- **设备适配比例**: 支持 640/750/828 多种设备
- **路径别名配置**:
- `@/utils`: 工具函数目录
- `@/components`: 组件目录
- `@/images`: 图片资源目录
- `@/api`: API接口目录
- `@/stores`: 状态管理目录
### 插件配置
- **taro-plugin-pinia**: Pinia 状态管理支持
- **@tarojs/plugin-framework-vue3**: Vue3 框架支持
- **@tarojs/plugin-html**: HTML 标签支持
- **@tarojs/plugin-inject**: 第三方组件注入
- **tarojs-plugin-platform-miniprogram**: 自定义 wxml 支持
### 样式处理
- **pxtransform**: px 转 rpx,排除 van- 前缀组件
- **url处理**: 图片资源转换,限制 1024 字节
- **CSS Modules**: 默认关闭
## 工具函数库 (utils/tools.js)
### 时间处理
- `formatDate(date)`: 格式化时间为 YYYY-MM-DD HH:mm
- 使用 moment.js 进行时间处理
### 平台检测
- `wxInfo()`: 检测浏览器平台信息
- isAndroid: 安卓平台检测
- isiOS: iOS平台检测
- isWx: 微信环境检测
- isWxPc: PC端微信检测
### 字符串工具
- `strExist(array, str)`: 检查字符串是否存在于数组中
- `parseQueryString(url)`: 解析URL查询参数
- `randomId(n)`: 生成随机ID
## 构建和部署
### 开发环境
```bash
# 切换Node.js版本
nvm use 16.14.2
# 安装依赖
npm install
# 启动微信小程序开发
npm run dev:weapp
```
### 生产构建
```bash
# 构建微信小程序
npm run build:weapp
```
### 支持平台
- 微信小程序 (主要)
- 支付宝小程序
- 百度小程序
- 字节跳动小程序
- QQ小程序
- H5
- React Native
## 注意事项
### 开发环境要求
- Node.js 版本必须使用 16.14.2
- 建议使用 nvm 管理 Node.js 版本
- 项目较老,可能存在依赖兼容性问题
### 已知问题
- 需要更新 browserslist 配置
- 部分依赖版本较老,升级需谨慎
- OpenSSL 兼容性问题,需使用指定 Node.js 版本
### 开发建议
1. 严格按照现有代码风格开发
2. 新增 Vant 组件需在 `vantComponentConf.js` 中配置
3. API 接口统一使用封装的 `fn` 函数处理
4. 页面路由需在 `app.config.js` 中注册
5. 状态管理优先使用 Pinia
6. 样式单位使用 rem,适配小程序
7. 图片上传使用七牛云存储
8. 富文本编辑使用自定义 `activity-editor` 组件
9. 表单验证遵循现有的验证规则
10. 错误处理统一使用 Toast 提示
## 页面实现细节
### 创建活动页面 (/pages/createActivity/index.vue)
- **功能**: 创建新活动,包含主办方选择、活动信息填写、封面上传等
- **关键组件**:
- `van-field`: 表单输入组件
- `van-uploader`: 图片上传组件
- `activity-editor`: 富文本编辑器
- **技术特点**:
- 支持图片上传到七牛云
- 动态表单字段配置
- 富文本内容编辑
- 表单验证和提交
### 首页 (/pages/index/index.vue)
- **功能**: 展示推荐活动,轮播图展示
- **关键组件**:
- `swiper`: 轮播图组件
- `activity-card`: 活动卡片组件
- `scroll-view`: 滚动加载
- **技术特点**:
- 无限滚动加载
- 缺省页面处理
- 活动卡片点击跳转
### 授权页面 (/pages/auth/index.vue)
- **功能**: 微信授权登录
- **技术实现**:
- 使用 `Taro.login()` 获取授权码
- 发送到服务器换取 sessionid
- 自动跳转到目标页面
## 网络请求封装
### 请求拦截器
```javascript
// 请求拦截器配置
service.interceptors.request.use(
config => {
// POST 请求数据序列化(排除上传接口)
config.data = config.method === 'post' &&
!strExist(['a=upload', 'upload.qiniup.com'], config.url)
? qs.stringify(config.data) : config.data;
return config
}
)
```
### 响应处理
- 统一错误处理和 Toast 提示
- 自动处理授权失效跳转
- 支持七牛云上传响应格式
## 业务流程
### 用户授权流程
1. 用户首次进入小程序
2. 检查是否已授权 (sessionid)
3. 未授权自动跳转授权页面 (`/pages/auth/index`)
4. 调用 `Taro.login()` 获取 code
5. 发送 code 到服务器获取 openid
6. 服务器返回 sessionid,保存到本地存储
7. 授权成功后跳转到缓存的目标页面
### 授权技术实现
```javascript
// 授权登录核心代码
Taro.login({
success: function (res) {
if (res.code) {
request.post('/srv/?a=openid', {
code: res.code
}).then(res => {
if (res.data.code) {
// 保存 sessionid
wx.setStorageSync("sessionid", res.cookies[0]);
// 跳转到目标页面
}
})
}
}
})
```
### 活动参与流程
1. 首页浏览推荐活动
2. 点击活动卡片查看详情
3. 填写参与信息
4. 提交参与申请
5. 查看参与状态
## 维护和扩展
### 添加新页面
1.`src/pages/` 下创建页面目录
2.`app.config.js` 中注册路由
3. 如需分包,在 `subpackages` 中配置
### 添加新接口
1. 在对应的 API 模块中定义接口
2. 使用统一的 `fn` 函数封装
3. 添加必要的错误处理
### 添加新组件
1.`src/components/` 下创建组件
2. 如使用新的 Vant 组件,需在配置文件中添加
3. 遵循现有的组件开发规范
---
**文档更新日期**: 2024年12月
**维护人员**: 开发团队
**联系方式**: hookehuyr@gmail.com
\ No newline at end of file