README.md



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


当前流程：


用户进入扫码关卡详情页
点击“扫码打卡”时先检查是否已有家庭
没有家庭则提示后跳转 Welcome

Welcome -> AddProfile -> Welcome -> CreateFamily/JoinFamily -> 原详情页
返回详情页后再次扫码
若关卡启用地理围栏，先重新静默获取当前位置并判断范围
调起微信扫码
从二维码结果中解析真实的 activity_id / detail_id

调用真实打卡接口
成功后跳到扫码关卡列表页


补充约定：


打卡参数来自二维码内容，不来自当前页面路由参数
注册来源归因目前通过 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

如果只是调整扫码详情页底部按钮视觉位置，优先改样式，不要顺手改业务逻辑