141 lines
6.7 KiB
Markdown
141 lines
6.7 KiB
Markdown
# 01 · 架构设计
|
||
|
||
## 1. 技术选型理由
|
||
|
||
选 **原生小程序 + 云开发**，因为：
|
||
|
||
- 云开发是微信官方为原生小程序量身打造，集成度最高、免运维、免自建鉴权。
|
||
- 汪圈 V1 是单机闭环，无跨端（App / H5 / 支付宝）需求，原生比 Taro / uni-app 更直接。
|
||
- 云函数里 `cloud.getWXContext().OPENID` 直接拿到可信用户标识，省掉整套登录鉴权后端。
|
||
|
||
## 2. 整体架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ 微信小程序客户端 │
|
||
│ pages/ (12屏) · components/ · utils/ │
|
||
│ globalData + 事件总线 │
|
||
└───────────────────┬─────────────────────────┘
|
||
│ wx.cloud.callFunction
|
||
┌────────────┴────────────┐
|
||
▼ ▼
|
||
┌───────────────┐ ┌───────────────┐
|
||
│ 云函数 │ │ 云数据库 │
|
||
│ login │◄───────►│ users │
|
||
│ dogManage │ │ dogs │
|
||
│ walkSave │ │ walks │
|
||
│ walkManual │ │ dog_achievements│
|
||
│ getDogDetail │ └───────────────┘
|
||
│ getHistory │
|
||
└───────────────┘ │
|
||
│ ▼
|
||
▼ ┌───────────────┐
|
||
成就判定/统计累加 │ 云存储 │
|
||
│ 头像/照片/分享图 │
|
||
└───────────────┘
|
||
```
|
||
|
||
**核心原则：写操作 + 敏感计算全部走云函数**，客户端只读（或经云函数读聚合结果）。连续天数、成就解锁、补记规则等绝不在客户端算。
|
||
|
||
## 3. 工程目录结构
|
||
|
||
```
|
||
Pet3/
|
||
├── cloudfunctions/ # 云函数（Node.js）
|
||
│ ├── login/ # 登录 + 首次建用户
|
||
│ │ ├── index.js
|
||
│ │ └── package.json
|
||
│ ├── dogManage/ # 狗狗增改查
|
||
│ ├── walkSave/ # 保存遛狗 + 触发统计/成就
|
||
│ ├── walkManual/ # 手动补记
|
||
│ ├── getDogDetail/ # 狗狗主页聚合数据
|
||
│ └── getHistory/ # 历史/记录 Tab 列表聚合
|
||
│
|
||
├── miniprogram/
|
||
│ ├── app.js # 初始化 wx.cloud、globalData
|
||
│ ├── app.json # 路由、tabBar、分包
|
||
│ ├── app.wxss # 全局样式 + 设计 token
|
||
│ ├── pages/
|
||
│ │ ├── login/ # 0a 登录
|
||
│ │ ├── dog-edit/ # 0b 建档/编辑（复用）
|
||
│ │ ├── home/ # 1 我的（tab）
|
||
│ │ ├── walking/ # 2/2b 遛狗中（含暂停态）
|
||
│ │ ├── summary/ # 3 成果卡
|
||
│ │ ├── dog-detail/ # 4 狗狗主页
|
||
│ │ ├── history/ # 5 遛狗历史
|
||
│ │ ├── records/ # 6/6b 记录（tab，含空状态）
|
||
│ │ └── achievements/ # 7 完整成就页
|
||
│ ├── components/
|
||
│ │ ├── dog-card/ # 狗狗卡片
|
||
│ │ ├── walk-row/ # 历史/记录行
|
||
│ │ ├── stat-grid/ # 统计三宫格
|
||
│ │ ├── achievement-medal/ # 成就勋章（解锁/锁定）
|
||
│ │ ├── multi-dog-sheet/ # 0c 多狗选择弹层
|
||
│ │ └── manual-add-sheet/ # 补记弹层
|
||
│ ├── utils/
|
||
│ │ ├── cloud.js # callFunction 统一封装 + 错误处理
|
||
│ │ ├── format.js # 时长/距离/日期格式化
|
||
│ │ ├── dogStep.js # 狗步换算（体型档位/步幅/体重校准）
|
||
│ │ └── store.js # 全局状态 + 订阅
|
||
│ └── images/ # 本地图标/占位图
|
||
│
|
||
├── docs/ # 设计文档（本目录）
|
||
├── wangquan-prototype.html # 交互原型
|
||
└── project.config.json
|
||
```
|
||
|
||
## 4. 全局状态（store）
|
||
|
||
不引入重型状态库。`miniprogram/utils/store.js` 维护：
|
||
|
||
```js
|
||
const store = {
|
||
userInfo: null, // { openid, nickname, avatar, joinedAt, walkCount }
|
||
dogs: [], // 当前用户的狗狗列表
|
||
currentDogId: null, // 默认/上次选中的狗
|
||
walkSession: null, // 进行中的遛狗会话（见下）
|
||
};
|
||
```
|
||
|
||
**遛狗会话（walkSession）** 是 V1 最关键的运行时状态，需支持小程序退到后台后恢复：
|
||
|
||
```js
|
||
walkSession = {
|
||
dogIds: ['xxx'], // 本次遛的狗（支持多狗）
|
||
startAt: 1719230000000,
|
||
pausedTotal: 0, // 累计暂停时长(ms)，结算时扣除
|
||
pausedAt: null, // 当前暂停起点，null=进行中
|
||
pooped: false, // 便便打卡
|
||
locationEnabled: false, // 是否获得定位授权
|
||
distanceMeters: null, // GPS 累计距离；未授权为 null
|
||
lastLocation: null, // 最近一次有效定位点，用于增量累计距离
|
||
status: 'walking' | 'paused',
|
||
}
|
||
```
|
||
|
||
落地策略：会话写入 `wx.setStorageSync('walkSession')`，App `onShow` 时恢复，避免锁屏/切后台丢失计时。计时基于 `startAt` 与当前时间差实时计算，**不依赖 setInterval 累加**（后台被冻结也不丢）。定位为可选增强：获得授权时累计 GPS 距离并换算狗步；未授权时 `distanceMeters` / `dogStepsByDog` 为 `null`，界面隐藏距离与狗步，闭环仍成立。
|
||
|
||
## 5. 设计 Token（迁移自原型）
|
||
|
||
原型 CSS 变量直接转为 `app.wxss` 全局变量，保证视觉一致：
|
||
|
||
| Token | 值 | 用途 |
|
||
|-------|-----|------|
|
||
| `--bg` | `#F2EDE6` | 页面背景 |
|
||
| `--surface` | `#FBF8F3` | 卡片 |
|
||
| `--ink` | `#2E2A24` | 主文字 |
|
||
| `--ink-2` | `#6E665B` | 次文字 |
|
||
| `--accent` | `#E8A04B` | 主色（按钮/FAB） |
|
||
| `--accent-deep` | `#C77E2E` | 主色深 |
|
||
| `--success` | `#6B8E5A` | 遛狗中 |
|
||
| `--warn` | `#D98A4E` | 暂停态 |
|
||
| `--danger` | `#C25A4E` | 结束/二次确认 |
|
||
|
||
> 小程序 WXSS 支持 CSS 变量，可直接 `var(--accent)`。不引第三方组件库，全部基础 UI（按钮、卡片、chip、toggle、勋章等）按原型纯手写为 `components/` 下的可复用组件。
|
||
|
||
|
||
|
||
|
||
|
||
|