# 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/` 下的可复用组件。