docs: add comprehensive project README

2026-02-28 17:23:32 +08:00
parent 031eef9643
commit 6f23abe23d
1 changed files with 130 additions and 0 deletions
@@ -0,0 +1,130 @@
+# 戒烟助手小程序（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` 文件。