Hooke / lls_program

Go to a project
Toggle navigation Toggle navigation pinning
Switch branch/tag
README.md 5.04 KB

lls_program

lls_program 是一个基于 Taro 4 + Vue 3 + NutUI 的微信小程序项目，当前业务围绕家庭管理、活动参与、积分奖励，以及海报/扫码打卡展开。

这不是一个通用模板仓库。当前代码里已经有比较明确的业务结构，尤其是扫码打卡链路、资料补全链路、家庭创建/加入链路，后续开发建议直接沿用现有实现方式，而不是重新搭一套平行流程。

技术栈

  • Taro 4.1.7
  • Vue 3.3
  • NutUI Taro 4.3.13
  • Pinia 3.0
  • TailwindCSS 3.4
  • Less
  • axios-miniprogram
  • Vitest

核心功能

  • 微信小程序登录与静默授权
  • 家庭创建、加入、家庭资料维护
  • 用户资料补全与注册来源归因
  • 活动详情、海报打卡、扫码打卡
  • 积分、奖励、优惠券相关页面
  • 地理位置相关能力与位置权限接入

当前重点业务链路

扫码打卡

当前扫码打卡已接入真实接口，主要页面和工具如下：

  • 列表页：src/pages/ScanCheckinList/index.vue
  • 详情页：src/pages/ScanCheckinDetail/index.vue
  • API：src/api/map.js
  • 地理围栏：src/utils/checkinLocation.js
  • 扫码参数解析：src/utils/scanCheckin.js
  • 回跳参数处理：src/utils/returnUrl.js
  • 富文本渲染：src/components/RichTextRenderer.vue

当前流程：

  1. 用户进入扫码关卡详情页
  2. 点击“扫码打卡”时先检查是否已有家庭
  3. 没有家庭则提示后跳转 Welcome
  4. Welcome -> AddProfile -> Welcome -> CreateFamily/JoinFamily -> 原详情页
  5. 返回详情页后再次扫码
  6. 若关卡启用地理围栏，先重新静默获取当前位置并判断范围
  7. 调起微信扫码
  8. 从二维码结果中解析真实的 activity_id / detail_id
  9. 调用真实打卡接口
  10. 成功后跳到扫码关卡列表页

补充约定：

  • 打卡参数来自二维码内容，不来自当前页面路由参数
  • 注册来源归因目前通过 reg_source、reg_stage_id 透传
  • reg_activity_id 已经不再使用
  • return_url 回跳统一通过 src/utils/returnUrl.js 处理

项目结构

src/
├── api/                    # 接口定义，只放请求相关代码
├── assets/                 # 静态资源
├── components/             # 通用组件
├── pages/                  # 页面
├── stores/                 # Pinia 状态管理
├── utils/                  # 工具函数、流程辅助
├── app.config.js           # 页面注册、权限声明
└── app.less                # 全局样式

几个常用目录说明：

  • src/api/user.js：用户认证、资料接口
  • src/api/family.js：家庭相关接口
  • src/api/map.js：地图、扫码关卡、扫码打卡相关接口
  • src/utils/request.js：请求拦截器、sessionid 注入
  • src/utils/userProfile.js：资料相关 helper
  • src/components/RichTextRenderer.vue：富文本渲染组件

开发约定

API 与 helper 分层

  • src/api/*.js 只放接口调用
  • 参数拼装、字段解析、距离计算、回跳处理等逻辑放 src/utils/

例如：

  • buildUpdateUserProfilePayload 在 src/utils/userProfile.js
  • 扫码结果解析在 src/utils/scanCheckin.js
  • 地理围栏判断在 src/utils/checkinLocation.js

请求返回判断

所有接口都要显式判断：

if (res.code === 1) {
  // success
}

不要写成：

if (res.code) {
  // 不推荐
}

小程序环境约束

页面里不要使用浏览器 API：

  • window
  • document
  • localStorage
  • 原生 fetch

统一使用 Taro API：

  • Taro.navigateTo
  • Taro.redirectTo
  • Taro.switchTab
  • Taro.scanCode
  • Taro.getLocation

页面生命周期

页面优先使用 Taro 提供的生命周期：

  • useLoad
  • useShow
  • useDidShow
  • useReady

登录与认证

项目当前通过 sessionid 维持服务端登录态：

  • 从 storage 读取 sessionid
  • 在请求拦截器中注入到 cookie
  • 401 交给现有授权/跳转逻辑处理

需要注意：

  • sessionid 只是认证凭证
  • 它不等于“用户一定能继续后续业务流程”
  • 业务上是否可继续，仍要结合资料、家庭、活动规则等条件判断

本地开发

安装依赖

npm install

微信小程序开发

npm run dev:weapp

微信小程序构建

npm run build:weapp

其他常用命令

npm run dev:h5
npm run dev:alipay
npm run dev:tt
npm run lint
npm run format
npm run test:run

页面注册与权限

页面统一在 src/app.config.js 中注册。

当前已经声明位置相关能力：

  • requiredPrivateInfos: ['getLocation']
  • permission.scope.userLocation

这也是扫码打卡地理围栏能力能直接接上的基础配置。

备注

  • NutUI 组件是自动导入的，不需要手动 import
  • ScanCheckinDetail 顶部 banner 现在使用 NutUI nut-swiper
  • ScanCheckinDetail 富文本展示统一使用 RichTextRenderer
  • 如果只是调整扫码详情页底部按钮视觉位置，优先改样式，不要顺手改业务逻辑