nepiedg
131 lines
3.9 KiB
Markdown
131 lines
3.9 KiB
Markdown
# 戒烟助手小程序（smt）
|
||
|
||
基于 `uni-app + Vue 3 + Pinia` 的戒烟辅助小程序前端，核心目标是帮助用户记录抽烟/忍住行为，并通过首页看板、统计分析和 AI 建议逐步降低吸烟频率。
|
||
|
||
## 项目状态
|
||
|
||
- 当前分支：`master`
|
||
- 已落地核心流程：登录、引导、记录、历史、统计、首页整合接口渲染
|
||
- 部分页面能力仍在迭代（如个人中心部分菜单项）
|
||
|
||
## 功能概览
|
||
|
||
### 已实现
|
||
|
||
- 静默登录与会话持久化（`/auth/login` + 本地 `session_key`）
|
||
- 新用户引导（5 步问卷，提交 `profile`）
|
||
- 首页 Dashboard（问候语、计时器、下次建议时间、今日统计、AI 提示卡）
|
||
- 记录能力
|
||
- 记录抽烟（数量、等级、备注、时间）
|
||
- 记录“想抽忍住了”
|
||
- 统一弹框组件：`smoke-record-dialog`
|
||
- 历史记录页
|
||
- 分组展示（今天/昨天/日期）
|
||
- 按类型筛选（全部/已抽烟/已忍住）
|
||
- 下拉刷新、分页加载
|
||
- 编辑与删除
|
||
- 统计页
|
||
- 周/月/年切换
|
||
- 趋势柱状图、变化百分比、节省金额、健康恢复指标
|
||
|
||
### 规划中/开发中
|
||
|
||
- AI 助手页的深度交互（当前为基础展示）
|
||
- 个人中心多个菜单详情页（当前入口为占位）
|
||
|
||
## 技术栈
|
||
|
||
- `uni-app`
|
||
- `Vue 3`（`<script setup>` 为主）
|
||
- `Pinia`
|
||
- `uni.request` 二次封装（401 自动重登后重试）
|
||
- `easycom` 自动组件导入
|
||
|
||
## 页面与路由
|
||
|
||
在 `pages.json` 中注册了以下页面：
|
||
|
||
- `pages/index/index`：首页
|
||
- `pages/stats/index`：统计
|
||
- `pages/ai/index`：AI 助手
|
||
- `pages/logs/index`：历史记录
|
||
- `pages/profile/index`：个人中心
|
||
- `pages/onboarding/index`：新用户引导
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
smt/
|
||
├── api/ # 接口封装
|
||
├── components/ # 业务组件（含 smoke-record-dialog）
|
||
├── config/ # 环境配置（BASE_URL 等）
|
||
├── docs/ # PRD、API、算法与认证文档
|
||
├── hooks/ # 组合式逻辑（如 useLogin）
|
||
├── pages/ # 页面
|
||
├── stores/ # Pinia 状态管理
|
||
├── utils/ # 工具函数与本地存储封装
|
||
├── App.vue
|
||
├── main.js
|
||
├── manifest.json
|
||
└── pages.json
|
||
```
|
||
|
||
## 本地开发
|
||
|
||
## 1. 环境准备
|
||
|
||
- 推荐使用 `HBuilderX` 打开项目目录
|
||
- 微信开发者工具（用于运行到微信小程序）
|
||
|
||
> 说明：本仓库当前未包含 `package.json`，默认按 HBuilderX/uni-app 工程方式运行。
|
||
|
||
## 2. 配置后端地址
|
||
|
||
编辑 `config/index.js`：
|
||
|
||
- `development.BASE_URL`：开发环境 API 地址
|
||
- `production.BASE_URL`：生产环境 API 地址
|
||
- `MINI_PROGRAM_ID`：后端登录接口使用的小程序 ID
|
||
|
||
## 3. 小程序配置
|
||
|
||
`manifest.json` 中包含：
|
||
|
||
- `mp-weixin.appid`
|
||
- 微信端 `urlCheck` 等基础配置
|
||
|
||
## 4. 运行
|
||
|
||
在 HBuilderX 中：
|
||
|
||
1. 导入项目目录
|
||
2. 运行到 `微信开发者工具`
|
||
3. 确认接口可访问后开始联调
|
||
|
||
## 接口与文档
|
||
|
||
- 产品需求：`docs/PRD.md`
|
||
- 技术方案：`docs/TECH.md`
|
||
- 抽烟记录 API：`docs/api.md`
|
||
- 登录认证：`docs/auth.md`
|
||
- 算法说明：`docs/ALGORITHM.md`
|
||
- 组件文档：`components/smoke-record-dialog/README.md`
|
||
|
||
## 关键实现说明
|
||
|
||
- 全局启动时在 `App.vue` 发起静默登录
|
||
- 业务页面通过 `useLogin().waitForLogin()` 确保登录完成后请求接口
|
||
- `api/request.js` 统一处理请求：
|
||
- 自动注入 `Authorization: Bearer <session_key>`
|
||
- 401 自动登录并重试一次
|
||
|
||
## 注意事项
|
||
|
||
- `config/index.js` 里默认开发地址是局域网 IP，跨设备调试需改成可访问地址
|
||
- 历史记录与统计页依赖后端返回格式，联调时请以 `docs/api.md` 为准
|
||
- 仓库中 `docs/*` 可能存在进行中的改动，提交前建议按需选择暂存文件
|
||
|
||
## License
|
||
|
||
当前仓库未声明开源许可证；如需开源，请补充 `LICENSE` 文件。
|