Hooke / swx_weapp

Go to a project
Toggle navigation Toggle navigation pinning
Switch branch/tag
项目文档.md 10.6 KB

静待花开-活动小助手 项目文档

项目概述

项目名称: 静待花开-活动小助手 (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

构建和部署

开发环境

# 切换Node.js版本
nvm use 16.14.2

# 安装依赖
npm install

# 启动微信小程序开发
npm run dev:weapp

生产构建

# 构建微信小程序
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
    • 自动跳转到目标页面

网络请求封装

请求拦截器

// 请求拦截器配置
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. 授权成功后跳转到缓存的目标页面

授权技术实现

// 授权登录核心代码
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. 更新时候注意事项
    • datetime-picker 组件有一部分写死修改，需要注意不要修改

添加新页面

  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